25.10 (Goldeye) brings many new features and improvements to the TrueNAS experience.
Redesigned Management Interfaces
The Updates screen introduces risk-tolerance profiles for better control over system update notifications, while the refreshed Users screen provides improved account management with streamlined user creation workflows and better at-a-glance access to account information.
Advanced Networking and Storage
TrueNAS 25.10 introduces comprehensive networking enhancements designed for terabit Ethernet performance.
NVMe over Fabric support includes NVMe/TCP for Community Edition and NVMe/RDMA for Enterprise hardware.
RDMA capabilities eliminate TCP overhead and reduce latency for high-performance storage networking on Enterprise systems.
Updated drivers provide 400GbE network interface support, while enhanced network configuration management improves robustness when transitioning between DHCP and static configurations.
Virtual Machine Improvements
TrueNAS 25.10 delivers comprehensive virtual machine enhancements, including Secure Boot support for enhanced security and refined startup behavior to prevent conflicts between container and VM management interfaces.
VM disk import and export capabilities support multiple formats (QCOW2, QED, RAW, VDI, VHDX, VMDK), streamlining VM migration and setup processes.
NVIDIA Open GPU Kernel Module Support
Support for NVIDIA’s open GPU kernel module drivers enables compatibility with the latest graphics cards, including the Blackwell architecture.
Modern GPU acceleration capabilities are available for TrueNAS Apps and container workloads.
See NVIDIA GPU Support for compatibility details.
ZFS Performance and Stability Improvements
Critical ZFS updates include stability fixes for encrypted snapshot replication, enhanced memory pressure handling, faster pool operations, improved I/O scaling, and new Direct I/O support for better performance in virtualized environments.
Application Pool Migration and Registry Mirrors
Automatic migration of existing applications when changing application pools eliminates manual reconfiguration and reduces downtime during pool transitions.
Support for external container registry mirrors provides alternative sources for Docker images, improving reliability.
Flexible Disk Health Monitoring
TrueNAS 25.10 transitions from built-in SMART test scheduling to a more flexible approach with automatic migration of existing tests to cron tasks.
Users can install the Scrutiny app for advanced monitoring or use custom solutions while TrueNAS continues to automatically alert on critical disk health indicators.
See Disk Management for details on the SMART monitoring transition.
This section guides you through installing TrueNAS, or migrating from a FreeBSD-based TrueNAS version to a Linux-based TrueNAS version, and using the UI to access and configure TrueNAS.
Configuration includes setting up initial storage, backup, and data sharing, and expanding TrueNAS with different application solutions.
The Evaluation Guide also provides video tutorials for installing and exploring the full potential of TrueNAS.
Contents
⎙ Download or Print: View all TrueNAS Getting Started articles as a single page for download or print.
Feature Deprecations: Notes about TrueNAS features deprecated in the latest nightly releases.
TrueNAS Hardware Guide: Provides information on system hardware and minimum requirements (CPU, memory, etc.). Covers storage considerations, media, controllers, device sizing and cooling, SAS expanders.
Migrating from CORE: Instructions for migrating from FreeBSD TrueNAS CORE to Linux-based TrueNAS versions.
Third-Party Data Migration: Provides data migration instructions for users wanting move data from a third-party NAS solution to the TrueNAS system using the Syncthing Enterprise app.
The TrueNAS team is pleased to release TrueNAS 25.10.8!
This release updates the Linux kernel to address more than 1,600 upstream CVEs. It also fixes a dataset passphrase exposure in internal job arguments, NVMe over TCP I/O errors on large transfers, and SMB, rsync, Cloud Sync, TrueNAS Connect, and Apps issues.
Notable changes:
Fixes an issue that exposed dataset passphrases in plain text in internal job arguments (NAS-144783).
When a passphrase-encrypted dataset was unlocked from the web interface, the passphrase was stored unredacted in the arguments of an internal zfs.dataset.bulk_process job. TrueNAS now treats these arguments as secret so the passphrase no longer appears in job details.
Updates the Linux kernel to the latest 6.12 LTS release (v6.12.113) (NAS-143852, NAS-144791).
This update fixes more than 1,600 upstream CVEs. Several of these are critical or high severity issues in components TrueNAS uses.
Key fixes include:
io_uring: Fixes a use-after-free error in a task the kernel runs for the submission queue (CVE-2026-98858).
Fixes an issue where large NVMe over TCP transfers failed and caused I/O errors on connected hosts (NAS-144298).
The NVMe over TCP target told hosts it had no limit on transfer size, but it rejected any single transfer larger than 4 MiB. Linux hosts that sent larger transfers received I/O errors, which could silently lose data on some file systems such as ext4. The target now reports a transfer size limit that hosts follow.
Fixes an error that prevented changes to SMB service settings when directory services are enabled (NAS-143595).
An error in the check for NetBIOS alias changes caused any attempt to save a change on the SMB service screen to fail with the error too many values to unpack (expected 2). SMB service settings now save as expected.
Fixes rsync tasks that failed when the extra options contained quoted values (NAS-143382).
A change in 25.10.7 caused TrueNAS to use quoted values in the Extra options field literally. For example, --rsync-path="sudo rsync" was treated as a single command named sudo rsync and the task failed. TrueNAS now handles quoted values the same way as in 25.10.6.
Fixes cloud sync tasks that failed for Backblaze B2 credentials with leading or trailing spaces (NAS-144662).
Spaces copied along with a Backblaze B2 key could cause an invalid authorization token error when TrueNAS verified the credential or ran the task. TrueNAS now removes leading and trailing spaces from credential values before it uses them.
Fixes certificate generation that failed when the certificate authority responded slowly (NAS-144031).
Requests from TrueNAS to TrueNAS Connect timed out after 15 seconds, which was not always long enough when the certificate authority was slow. This caused certificate generation to fail. TrueNAS now waits up to 55 seconds for a response.
Fixes apps that kept an invalid NVIDIA GPU identifier after a GPU replacement (NAS-142006).
When a GPU was replaced with a different card in the same slot, an app that used it kept the old card identifier and the app failed to start. TrueNAS now updates the stored identifier to match the installed card.
Edit and save the app, or redeploy it, to apply the updated identifier.
The TrueNAS team is pleased to release TrueNAS 25.10.7!
Notable changes:
Updates the Linux kernel to the latest 6.12 LTS release (v6.12.105).
Fixes a kernel panic in the NFS server that could occur when a client’s dropped connection caused the same request to arrive twice (NAS-142560).
If an NFSv4.1 client lost its connection twice in quick succession, two copies of the same request could reach the server at the same time. Both were read from the session reply cache, but one thread could also modify that cached entry while the other read it, which caused a NULL pointer dereference and crashed the system. TrueNAS now leaves the cached reply untouched when replaying it.
Fixes a crash that could occur when unregistering an iSCSI target while a peer controller was leaving the cluster (NAS-142264).
On Enterprise HA systems, target unregistration during failover could follow a stale list pointer if another teardown ran at the same time, which crashed the system or corrupted memory. The affected code now restarts its list walk from the beginning after each removal instead of relying on a saved position.
Fixes a crash that could occur when a task management command arrived while an iSCSI session was being reassigned to a new access control group (NAS-142258).
An ABORT_TASK or other task management request received during session reassignment could dereference a pointer that was temporarily cleared, which crashed the task management thread. TrueNAS now keeps the previous access control group installed until the reassignment finishes.
Fixes a crash in the iSER (iSCSI over RDMA) target driver that could occur when a connection closed during active I/O (NAS-142161).
A response posted just before a connection closed could be released twice, and the second release read from memory that had already been reused, which crashed the target. TrueNAS now tracks response ownership correctly so this cannot happen.
Fixes a crash that could occur when a Fibre Channel target driver was unloaded while a target’s enabled state was still being changed (NAS-142126).
A queued request to enable or disable a target could still run after the target began unregistering, which re-armed a port whose driver was already partially torn down and crashed the system. TrueNAS now blocks queued work for a target once it starts unregistering.
Fixes an Enterprise HA networking issue that could let both controllers become active for the same IPv6 virtual IP (NAS-142303).
The VRRP service listened for advertisements on the wrong IPv6 address, so it never received the peer controller’s advertisements and considered itself the primary controller for every IPv6 VIP. TrueNAS now binds the listener to the correct address so failover state is tracked correctly.
Improves resilience to brief Non-Transparent Bridge (NTB) interruptions on Enterprise HA systems (NAS-142152).
A short NTB packet loss event could trigger an unnecessary cluster reset. TrueNAS now waits up to 60 seconds for the NTB link to recover before treating the peer controller as down.
Updates ZFS 2.3 from version 2.3.4 to 2.3.9 (NAS-142153, NAS-142538).
This update includes upstream fixes for silent read corruption after block cloning, data loss during redacted replication send, zvol sync writes that did not reach the ZIL, incomplete dRAID rebuilds, and a permission check gap that let a caller open a device without read access. There is no on-disk format change.
Fixes intermittent “permission denied” errors on NFS shares for users in Active Directory or LDAP environments (NAS-142228).
A brief winbind or SSSD outage could cause the kernel to cache an empty group list for a user. This stripped that user of access to any share that depended on group membership for up to 30 minutes, even after the directory service recovered. TrueNAS no longer treats these empty replies as valid.
Fixes an issue where a single unreachable container registry could stop TrueNAS from checking for app updates (NAS-142192).
If one registry returned an unexpected error, such as a certificate mismatch, the update check stopped for every remaining app. Affected apps could not be upgraded from the web interface until a later check succeeded. TrueNAS now logs the error for the failing image and continues checking the rest.
Reduces unnecessary restarts of the ix-vendor service caused by routine IPv6 network activity (NAS-142227).
Routers that send frequent IPv6 router advertisements could cause TrueNAS to treat each address lifetime refresh as a new address change, restarting the service every few seconds. TrueNAS now recognizes these refreshes and ignores them.
Fixes a serialization error in the reporting API when aggregated data was not requested (NAS-142197).
Calls to reporting.get_data with aggregation disabled failed validation and logged a serialization warning instead of returning a clean result. This affected features, such as Dashboard graphs, that request non-aggregated reporting data.
Fixes an issue where testing an alert service could hide the real reason the test failed (NAS-140259).
A coding error in the alert service test handler raised an unrelated error before the actual failure reason could be reported, so users saw a misleading message instead of the real cause of a failed test.
Fixes Cloud Sync tasks that failed to run when cloud credentials contained certain special characters (NAS-142234).
Some characters in credential values could produce an invalid rclone configuration file, which caused the Cloud Sync task to fail. TrueNAS now escapes these characters when generating the configuration.
Fixes the snapshot task Lifetime field accepting invalid values of 0 and -1 (NAS-142610).
The web interface allowed a snapshot task to be saved with a lifetime of zero or a negative number, neither of which is a valid retention period. The field now rejects these values.
The TrueNAS team is pleased to release TrueNAS 25.10.6!
This release updates the Linux kernel and NVIDIA GPU driver to address security vulnerabilities and maintain driver support. It also fixes Fibre Channel crashes on Enterprise systems, an NFS server hang, false drive self-test alerts, deduplication table pruning errors, and directory services configuration changes.
Notable changes:
Updates the Linux kernel to the latest 6.12 LTS release (v6.12.99) (NAS-142007).
TrueNAS 25.10.6 advances the kernel from v6.12.95 in the previous release to v6.12.99. This update includes fixes for more than 250 upstream CVEs, including several critical issues in components TrueNAS uses: a reference count underflow in the TCP request socket queue (CVE-2026-53260), an NFS server failure to release layout state after an unsuccessful lease request (CVE-2026-53399), out-of-bounds reads in the NVMe target discovery log page and authentication reply handling (CVE-2026-64320 and CVE-2026-64319), unbounded transfer lengths in the siw and rtrs-srv RDMA drivers (CVE-2026-64268 and CVE-2026-64269), a traffic control action handling issue (CVE-2026-64530), a BPF device map issue with fragmented frames (CVE-2026-64355), and an out-of-bounds read in TIPC broadcast acknowledgment handling (CVE-2026-64450).
Updates the NVIDIA GPU driver to version 580.173.02 (NAS-142008).
The 570 driver branch included in earlier releases reached end of life and does not build against the 6.12.99 kernel. TrueNAS now ships the 580 long-term support branch, which NVIDIA supports through June 2028.
Fixes crashes when Fibre Channel target mode starts or stops (NAS-142014, NAS-142018).
If the Fibre Channel target driver detached while the adapter still delivered traffic, an incoming login or abort request could reference memory that was already released and crash the system. TrueNAS now checks for this condition and drops or rejects the request instead. TrueNAS also reports an error and leaves target mode disabled when target registration fails, rather than enabling the port anyway.
Fixes an NFS server hang that could stop the server from expiring clients (NAS-142112).
A leaked callback reference on an NFSv4 delegation could leave client teardown waiting forever. After this happened, no further NFSv4 client cleanup could complete, and the rpc.nfsd process could not be stopped without a system reboot. A brief network interruption on a client that held a write delegation was enough to trigger it. This release includes two upstream kernel fixes that prevent the leak.
Fixes false drive self-test failure alerts and errors when TrueNAS reads drive SMART data (NAS-140652, NAS-141951).
TrueNAS read the oldest NVMe self-test result instead of the newest, so some drives raised a “failed a SMART selftest” alert for a test that did not fail. A drive that returned a self-test entry without a status also produced a KeyError that filled /var/log/middlewared.log with errors and stopped the SMART alert check from completing. TrueNAS now handles both cases so self-test alerts reflect actual drive results.
Fixes several issues with deduplication table (DDT) pruning (NAS-142045).
Pruning could select the wrong entries when the target age matched a histogram boundary, and the youngest age bin did not start at zero, so the age of recent entries could be misjudged. Counters could also overflow on tables with more than two billion entries. Pruning now uses the time the histogram build starts as the age cutoff and handles large tables correctly.
Fixes the Save button that stayed unavailable on the directory services configuration screen (NAS-138641).
After an upgrade from 25.04 to 25.10, the Save button in Credentials > Directory Services could stay greyed out no matter which setting changed, which blocked all directory services configuration changes. The button now becomes available when a setting changes.
Adds the ability to change the ALUA setting when the standby controller is unreachable (NAS-142057).
On Enterprise HA systems, TrueNAS blocked changes to the ALUA setting when it could not reach the standby controller. Administrators can now turn ALUA on or off while the standby controller is down.
Improves failover speed by moving a remote disk scan out of the critical failover path (NAS-141988, NAS-140406).
On Enterprise HA systems, failover asked the other controller to rescan its disks before it imported the pool, which could stall failover for a minute or more while services stayed offline. The request now runs outside the critical failover section and does not wait for a response.
Fixes audit entry parsing that could restart the audit handler (NAS-139610).
A local authentication event could produce an audit message with a hostname value that contained spaces and its own key and value pairs. The audit parser did not expect this format, which raised an exception and forced truenas_audit_handler to restart. The parser now handles these messages correctly.
The TrueNAS team is pleased to release TrueNAS 25.10.5!
This release updates the Linux kernel to address local privilege escalation and other security vulnerabilities. It also fixes a console memory leak, incorrect drive health data, stalled TrueCloud Backup jobs, SSH key handling for replication and cloud credentials, alert email delivery, and share ACL edits.
Notable changes:
Updates the Linux kernel to the latest 6.12 LTS release (v6.12.95) (NAS-141384, NAS-141588, NAS-141696).
TrueNAS 25.10.5 advances the kernel from the previous release through v6.12.93, v6.12.94, and v6.12.95. This update mitigates several kernel vulnerabilities, including the SharedFrag local privilege escalation (CVE-2026-43503) and the PeditCOW local privilege escalation (CVE-2026-46331). The v6.12.95 update adds further high-severity upstream fixes, including an out-of-bounds read in the rxrpc ACK parser (CVE-2026-53151), use-after-free issues in network bonding (CVE-2026-31419 and CVE-2026-52975), a use-after-free in eventpoll (CVE-2026-46242), an IPv6 tunnel network namespace issue (CVE-2026-52909), an SCTP UDP-tunnel handling fix (CVE-2026-53070), and a SELinux overlayfs access-check bypass (CVE-2026-46054), along with additional upstream security and stability fixes.
Fixes a memory leak in the console CLI process that could cause system-wide out-of-memory crashes (NAS-141238).
The CLI process running on the system console (getty@tty1) could leak a large amount of memory over time, eventually exhausting system RAM and triggering out-of-memory (OOM) kills that affected other processes. The leak is fixed so the console CLI no longer consumes excess memory.
Fixes faulty parsing of smartctl output that could produce incorrect drive health information (NAS-141215).
TrueNAS could misread the output of the smartctl utility when collecting SMART data from drives, which could lead to inaccurate disk health reporting. The parsing logic is corrected so SMART attributes are read reliably.
Fixes TrueCloud Backup jobs that could hang indefinitely and hide restic error messages (NAS-141287).
A KeyError while reading restic progress output caused TrueCloud Backup to discard all restic error messages, so failing jobs could appear stuck with no explanation. TrueNAS now handles the progress output correctly and surfaces the underlying restic errors.
Fixes several SSH key handling issues affecting remote replication and cloud credentials (NAS-141677).
Removing an SSH key pair now correctly updates SFTP cloud credentials that used that key. Encrypted SSH private keys are rejected more consistently during validation, and remote SSH semi-automatic setup returns a clear error when the selected key pair is missing or invalid. SSH pairing with TrueNAS 13 systems during remote replication setup now works correctly.
Fixes alert emails that were not RFC 5322 compliant and could be rejected by mail providers (NAS-141699).
Alert notification emails did not conform to RFC 5322, so some providers such as Gmail bounced them and administrators did not receive the alerts. TrueNAS now generates compliant messages so alert emails are delivered reliably.
Fixes an issue that prevented editing a share ACL (NAS-139535).
Attempts to edit the ACL on a share could fail, which blocked permission changes. Editing share ACLs now works as expected.
The TrueNAS team is pleased to release TrueNAS 25.10.4!
This release updates the Linux kernel and Samba to address multiple security vulnerabilities, and includes data integrity, NFS, iSCSI, networking, and Active Directory fixes.
Notable changes:
Updates the Linux kernel to the latest 6.12 LTS release (v6.12.91).
This update mitigates several kernel vulnerabilities, including the Dirty-Frag local privilege escalation (CVE-2026-43284 and CVE-2026-43500), the CIFSwitch local privilege escalation in the CIFS client (CVE-2026-46243), a ptrace privilege issue (CVE-2026-46333), and the related Fragnesia privilege escalation in the ESP-in-TCP path (CVE-2026-46300). It also enables additional CPU side-channel mitigations.
Updates Samba to version 4.22.10 to address multiple security vulnerabilities.
This Samba maintenance release resolves several CVEs, including a missing access check that let read-only users set or delete reparse point attributes (CVE-2026-1933) and a flaw in the WORM (Write Once, Read Many) module that allowed protected files to be overwritten by renaming a new file over them (CVE-2026-2340). See the Samba 2026 security release impact statement for the TrueNAS-specific impact assessment, or the Samba 4.22.10 release notes for the complete upstream list.
Fixes a potential double free when freeing blocks cloned after deduplication table pruning.
Blocks created through block cloning could be freed more than once if their deduplication table (DDT) entries had already been pruned, because the free path did not check the block reference table (BRT) first.
Fixes virtual machines stored on NFSv4.1 datasets failing to power on.
A change introduced in 25.10.2.1 could cause the NFSv4 change cookie to move backward after a file left the cache due to memory pressure, a remount, or a reboot. NFSv4.1 clients that depend on a monotonic change cookie, notably VMware ESXi, rejected the affected files. A virtual machine stored on an NFSv4.1-exported ZFS dataset then failed to power on with the error “The file specified is not a virtual disk.” This release reverts that change while a complete fix is finalized upstream.
Fixes a kernel crash in the iSCSI target layer during SCSI bus or LUN resets.
A use-after-free in the clustered locking path of the iSCSI target could crash the system during a SCSI reset, most often on Enterprise High Availability (HA) systems while a peer controller was leaving the cluster. The target layer now waits for lock teardown to complete before releasing the associated memory.
Improves iSCSI LUN replacement during High Availability failover.
On Enterprise HA systems, cleanup of a replaced LUN could stall during failover while a peer controller was being evicted from the cluster, which blocked later LUN replacements. Cleanup is now held until the cluster coordination it depends on has finished.
Fixes a validation error that blocked static network configuration on some High Availability systems.
On HA-capable systems, saving a static network configuration could incorrectly fail with “Enabling DHCPv4/v6 on HA systems is unsupported” even when DHCP was not being enabled. This affected fresh installs before any interface had a saved configuration. The check now triggers only when DHCP or IPv6 autoconfiguration is explicitly enabled.
Improves Active Directory rejoin, reset, and recovery handling.
This release hardens the Active Directory rejoin and directory services reset operations, improves domain controller selection on systems with more than one available controller, and produces clearer diagnostics when a join or authentication problem occurs.
Fixes ZFS automatic snapshots not being created after a Time Machine backup until the Mac reconnects.
When a Time Machine SMB share has automatic snapshots enabled, recent macOS versions (Tahoe and later) sometimes keep the SMB session open after a backup completes instead of disconnecting, which prevented the post-backup ZFS snapshot from being taken until the client reconnected or restarted. The snapshot logic is updated to handle these persistent Time Machine sessions.
Reduces excessive winbind log messages for failed user and group lookups.
When Active Directory is enabled, looking up a user or group that does not exist (for example through getpwnam or getgrnam) generated a warning for every failed lookup, which could rapidly fill the winbind log. These messages are now logged at informational level instead of as warnings.
The TrueNAS team is pleased to release TrueNAS 25.10.3!
Notable changes:
Fixes read authentication errors caused by block cloning between encrypted ZVOLs with different encryption keys (NAS-140263).
Block cloning between encrypted ZVOLs that did not share compatible encryption keys was allowed, but subsequent reads of the cloned data produced authentication failures. TrueNAS now verifies that encryption keys match before allowing a block clone operation to proceed.
Fixes Active Directory users and groups not found when using the idmap_ad backend with RFC2307 (NAS-140077).
The idmap_ad backend failed when smb.conf was configured to disallow a private krb5.conf, preventing Active Directory users and groups from being resolved. Shares and services that depend on directory service identities were inaccessible on affected systems.
Fixes pool creation errors on systems with a USB boot drive or other disk with a duplicate serial number (NAS-139947).
The disk availability check incorrectly blocked pool creation if any disk on the system had a duplicate serial number, even when that disk was unrelated to the new pool. USB boot drives commonly have blank or duplicate serial numbers and were the most frequent cause. Note that TrueNAS does not recommend USB boot devices. Installing on SATA, SAS, or NVMe flash media is recommended.
Fixes issues with log VDEV removal (NAS-140080).
Resolves errors that could occur when removing a log VDEV from a storage pool. Affected systems encountered failures during the log VDEV removal process.
Fixes link aggregation failover not working out of the box (NAS-136978).
Resolves an issue where the MII polling interval was not correctly configured for bonding interfaces using the FAILOVER protocol. The bonding driver could not monitor slave link status, causing failover to fail silently when an interface lost carrier.
Fixes Netlink socket errors that caused network interface operations to fail (NAS-140041).
Concurrent netlink route operations could collide at the kernel level, producing “Netlink socket busy” (EBUSY) errors. This was most visible as bond status alert failures. The fix serializes netlink route operations to prevent collisions, increases the retry limit, and adds a short delay between retries to reduce the chance of repeated failures.
Fixes NTB transport memory allocation failures during link state changes (NAS-139627).
Non-Transparent Bridge (NTB) transport memory windows were allocated and freed on every link up/down event. Allocating several megabytes of physically contiguous memory on a running system could fail, causing instability. Memory windows are now pre-allocated at boot, avoiding repeated allocation attempts during link changes. This primarily affects TrueNAS Enterprise High Availability (HA) systems.
Fixes stale NFS file handles for ZFS snapshots that could not be recovered without a client reboot (NAS-140474).
When mountd failed to resolve a snapshot’s filesystem ID — such as after failover, snapshot expiration, or an automount failure — it permanently cached a negative response, causing all subsequent file handle lookups to return ESTALE errors. Client-side remounts did not clear the cached state. The fix replaces the permanent negative cache with a 120-second retry window, allowing recovery once the snapshot becomes accessible again.
Documentation improvement: Adds Drive Health Management documentation covering how TrueNAS 25.10 monitors drive health through ZFS real-time failure detection, automated 90-minute SMART polling, and improved alert filtering. Also covers manual SMART test scheduling options available to TrueNAS Community Edition users. See the Drive Health Management tutorial for full details.
The TrueNAS team is pleased to release TrueNAS 25.10.3.1!
This release mitigates CVE-2026-31431, a Linux kernel vulnerability in the AEAD cryptographic socket interface, and includes additional fixes primarily affecting TrueNAS Enterprise systems and users.
Notable changes:
Mitigates CVE-2026-31431, a CVSS 7.8 local privilege escalation vulnerability in the Linux kernel AEAD cryptographic socket interface (CWE-669: Incorrect Resource Transfer Between Spheres).
While the specific attack vector does not directly affect ZFS, TrueNAS integrates the upstream kernel patch as a security best practice. The fix reverts AEAD socket operations to out-of-place mode, eliminating the incorrect resource transfer between memory spheres that the vulnerability exploits.
Fixes Kerberos-secured NFS mounts failing after HA failover or system reboot when the NFS service is not configured to start automatically (NAS-138933).
When the NFS service did not have Start Automatically enabled, gssproxy failed to initialize when the service was started manually after a reboot or failover, causing /proc/net/rpc/use-gss-proxy to return 0. Kerberos-secured NFS mounts (krb5, krb5i, and krb5p) were unavailable as a result. This affected systems joined to both FreeIPA and Active Directory.
Restores SNMP visibility for ZFS filesystem datasets and adds a new MIB table covering the full dataset tree.
A long-standing regression caused the SNMP agent to report only zvols, silently omitting filesystem datasets from network monitoring tools such as Zabbix and Nagios. The SNMP agent now enumerates the complete dataset tree. A new datasetTable MIB entry exposes both filesystems and zvols with index, descriptor, and used, available, and referenced byte counts. The existing zvolTable is unchanged, so monitoring configurations that already poll it continue to work.
The TrueNAS team is pleased to release TrueNAS 25.10.2!
Notable changes:
Fixes critical upgrade failure affecting some systems upgrading from TrueNAS 25.04 to 25.10 (NAS-139541).
Resolves “Could not prepare Boot variable: No space left on device” error that caused affected systems to become unbootable after failed upgrade attempts.
Fixes SMB service startup failure after upgrading from older TrueNAS versions with legacy ACL configurations (NAS-139076).
Systems with legacy SMB share permission strings stored in their configuration database could not start the SMB service after upgrading to 25.10.1. This update automatically converts legacy permission formats to the current binary format during service initialization.
Improves NFS performance for NFSv4 clients (NAS-139128).
This item was included in the 25.10.2 release notes in a clerical error. This improvement is included in TrueNAS 25.10.2.1.
Improves ZFS pool import performance and write operation responsiveness (NAS-138879).
Limits the time async destroy operations can run per transaction group, preventing these operations from blocking pool imports and other write operations. Pool imports that previously took extended time due to prolonged async destroy operations complete more quickly.
Fixes disk replacement validation incorrectly rejecting identical capacity drives (NAS-138678).
Resolves “device is too small” error when attempting to replace failed drives with identical capacity models. The system now correctly validates replacement drive capacity and allows legitimate disk replacements to proceed.
Reduces excessive API calls during user and group selection in the web interface (NAS-139459).
Implements longer debounce period for autocomplete fields to prevent the system from making API requests for every keystroke. This reduces system load and eliminates logs filled with failed requests during routine typing.
Reduces background CPU usage when running containerized applications (NAS-139089).
Optimizes YAML processing and Docker stats collection to reduce asyncio_loop CPU usage caused by repeated container inspection operations holding the Global Interpreter Lock.
Fixes Dashboard storage widget displaying “Unknown” for used and free space (NAS-138705).
Resolves issue where secondary storage pools showed no capacity metrics in the Dashboard widget, preventing visibility into actual storage usage and availability.
Fixes network configuration lockout caused by invalid IPv6 routes (NAS-139575).
Resolves issue where unusual IPv6 route entries in the routing table prevented access to network settings, app management, and bug reporting. The system now gracefully handles invalid route entries instead of becoming unresponsive.
Fixes network bridge creation validation errors (NAS-139196).
Resolves Pydantic validation failures that prevented users from creating network bridges through the standard workflow of removing IPs from an interface, creating a bridge, and reassigning those IPs.
Adds Hosts Allow and Hosts Deny network access controls to SMB shares (NAS-138814).
Provides IP-based access restrictions for SMB shares across all relevant purpose presets. Also adds ability to synchronize Kerberos keytab Service Principal Names (SPNs) with Active Directory updates for improved multiprotocol share management.
Fixes IPv6 address formatting in Kerberos configuration for Active Directory (NAS-139734).
Resolves Active Directory authentication failures when using IPv6 addresses for Kerberos Distribution Centers (KDCs). The system now properly formats IPv6 addresses with square brackets in krb5.conf, preventing “Invalid argument while getting initial credentials” errors.
Improves Users page default filter to include Directory Services users (NAS-139073).
Directory Services users now appear in the default view without requiring manual filter adjustment. This improves discoverability of directory service accounts in the user management interface.
Fixes SSH access removal for user accounts (NAS-139130).
Resolves issue where clearing the SSH Access option appeared to save without error, but the SSH indicator persisted in the user list. Users can now properly disable SSH access through the web interface.
Fixes session expiry settings not being respected (NAS-138467).
Resolves issues where users were logged out unexpectedly during active operations despite configured session timeout settings, and where page refresh (F5) triggered the login screen despite an active session. Session expiration now functions as configured.
Fixes certificate management for certificates with large Distinguished Names (NAS-139056).
Certificates with DNs exceeding 1024 characters (typically those with many Subject Alternative Names) can now be properly imported and managed. Previously, these certificates would upload successfully but fail during subsequent listing operations.
Fixes Cloud Sync tasks becoming invisible after upgrading from TrueNAS CORE to SCALE (NAS-138886).
Resolves data inconsistency where the bwlimit field contained empty objects instead of empty arrays, preventing the UI from displaying cloud sync tasks. Tasks remained functional via command-line but were not visible in the web interface.
Improves S3 endpoint URI validation for Cloud Sync tasks (NAS-138903).
Adds upfront validation to ensure S3 endpoints include the required https:// protocol prefix. Previously, omitting the protocol resulted in an unhelpful “Invalid endpoint” error. The system now provides clearer guidance during configuration.
Fixes iSCSI extent wizard hanging when adding second extent to a target (NAS-138856).
Resolves issue where an unsaved changes popup appeared unexpectedly after saving, followed by duplicate item errors. The wizard pane now closes automatically as expected, though the extent is added successfully despite the confusing error messages.
Fixes error notifications displaying placeholder text (NAS-139010).
Resolves formatting bug where error notifications showed “%(err)s Warning” instead of descriptive error messages.
Improves error dialog usability for long error messages (NAS-138424).
Adds proper scrolling to error dialogs with lengthy content. Previously, users had to zoom out to 50% to see action buttons when error messages (such as those listing numerous dependent clones) extended beyond the visible area.
Restricts root account group membership to preserve system stability.
The system now locks root account group membership to the builtin_administrators group and prevents modification through the UI. This prevents accidental removal of required privileges that could cause scheduled tasks, cloud sync operations, cron jobs, and other system functions to fail. To disable root account access to the TrueNAS UI, use the Disable Password option in Credentials > Local Users instead of modifying group membership.
The TrueNAS team is pleased to release TrueNAS 25.10.2.1!
This is a small maintenance release to fix NIC bonding disruptions and SMB Legacy Share validation errors after the TrueNAS 25.10.2 release, and includes the NFS performance improvement for NFSv4 clients that was originally announced for 25.10.2.
Notable changes:
Improves NFS performance for NFSv4 clients (NAS-139128).
Adds support for STATX_CHANGE_COOKIE to properly surface ZFS sequence numbers to NFS clients via knfsd. The NFS change_info4 structure now accurately tracks directory and file changes, which reduces unnecessary server requests. Client attribute cache invalidation is also improved. Previously, the system synthesized change IDs based on ctime, which could fail to increment consistently due to kernel timer coarseness.
Fixes NIC bonding configuration disrupted after a system update (NAS-139889).
Resolves an issue where network interface bond configurations could break after a TrueNAS 25.10.2 update. Affected systems could lose network connectivity on bonded interfaces.
Fixes SMB Legacy Share validation errors that broke share management UI forms (NAS-139892).
Resolves an issue where SMB shares using the Legacy Share preset with certain path_suffix variable substitutions failed middleware validation. The SMB share configuration forms became unusable in the web interface as a result.
Fixes API result serialization failures caused by unhandled validation errors (NAS-139896).
Resolves an issue where certain Pydantic validation errors were not caught during API result serialization. This caused unexpected errors to appear in the web interface instead of proper error messages.
Fixes SSL certificate connection failure error handling (NAS-139938).
Resolves an AttributeError that occurred when an HTTPS connection failed due to a certificate error. Cloud sync tasks, replication, or other SSL-dependent network operations could surface a secondary AttributeError instead of the original connection failure message.
The TrueNAS team is pleased to release TrueNAS 25.10.1!
Notable changes:
Fixes issue where storage pools appeared offline after upgrading to 25.10.0 (NAS-138236).
Affected systems experienced temporarily missing VDEVs that required a system reboot to restore pool access.
Adds Final Cut Pro Storage Share purpose preset for SMB shares (NAS-138402).
Provides optimized configuration for Final Cut Pro workflows. See Setting Up Final Cut Pro SMB Shares for more information.
Adds automatic validation for SMB share audit logging configurations.
TrueNAS 25.10.1 automatically disables SMB shares when auditing is enabled and watch or ignore lists contain invalid groups (deleted/renamed groups or groups that are no longer SMB-type). This protective measure prevents auditing misconfigurations that could cause security or compliance issues. The system generates alerts identifying affected shares and problematic groups. See Configuring SMB Auditing for configuration details and troubleshooting steps.
Adds REST API usage monitoring alert.
TrueNAS now displays a daily alert when deprecated REST API endpoints are accessed, helping identify integrations that need migration. TrueNAS deprecated the REST API in version 25.04. Full removal is planned for TrueNAS 27. For more information about the JSON-RPC 2.0 over WebSocket API, see the API documentation.
Adds Clear Config button to the directory services configuration form.
This button allows users to easily remove existing directory service configurations. This is useful for troubleshooting, reconfiguration, or switching between directory service types.
Updates Samba from 4.22.5 to 4.22.6 (NAS-138644).
Includes upstream fix for Time Machine backup failures on newer macOS versions. Resolves an issue where Time Machine backups failed on macOS 15.2 (Tahoe) and later due to a Samba 4.22 behavioral change affecting directory rename operations for open files. TrueNAS 25.04 releases are unaffected.
Fixes Windows 11 virtual machine Trusted Platform Module (TPM) persistence (NAS-138165).
Resolves issue where BitLocker PINs and other TPM data reset after every VM restart. Users need to reset their PIN after upgrading, after which persistence functions normally.
Fixes Secure Boot for virtual machines (NAS-137898).
Resolves issue where VMs with Secure Boot enabled failed to boot signed operating systems like Windows 11 due to missing Microsoft keys in OVMF firmware.
Fixes VM image file upload default location (NAS-138502).
Prevents ISO files from being saved to the boot drive /mnt folder when users do not change the default upload location during VM image upload.
Fixes VDI disk import for virtual machines (NAS-137897).
Resolves errors when creating VMs using .vdi disk images.
Improves error handling for legacy FreeNAS dataset properties (NAS-138629).
Users can encounter "aclmode: failed to get property" errors when editing datasets on long-running systems that contain invalid aclmode=discard_chmod property values from legacy FreeNAS versions. This update improves error messaging to help identify affected datasets. If you encounter this error, run zfs set aclmode=passthrough dataset_name via CLI to reset the property to a valid value, then reboot the system.
Improves error messaging for pool operations (NAS-138330).
Provides clearer error messages when attempting to extend VDEVs or replace disks fails due to ZFS checkpoints or other conditions.
Fixes rsync tasks using SSH keychain credentials (NAS-138334).
Resolves UnboundLocalError that prevented saving or running SSH-based rsync tasks after upgrading to 25.10.0.
Improves replication error messages (NAS-138202).
Provides clearer error messages when replication tasks fail due to interrupted SSH connections or network issues.
Fixes email sending error after upgrading to 25.10.0 (NAS-138270).
Resolves 'str' object has no attribute 'decode' error when attempting to send test emails or system notifications.
Restores HDD temperature data via SNMP (NAS-138433).
Resolves issue where SNMP queries for disk temperature (OID .1.3.6.1.4.1.50536.3) returned no data after upgrading to 25.10.0.
Fixes issue disabling SSH and Shell access for user accounts (NAS-138307).
The Save button no longer disables when clearing these access options.
Network: 400GbE interface support and improved DHCP-to-static configuration transitions.
UI/UX Improvements:
Redesigned Updates, Users, Datasets, and Storage Dashboard screens.
Improved password manager compatibility.
Breaking Changes Requiring Action:
NVIDIA GPU Drivers:
TrueNAS 25.10 switches to open GPU kernel drivers supporting Turing and newer (RTX/GTX 16-series+). Pascal, Maxwell, and Volta architectures are no longer supported. See NVIDIA GPU Support for compatibility details.
Active Directory IDMAP:
The Active Directory AUTORID IDMAP backend is removed and auto-migrated to RID to improve consistency across multi-server environments. Users should review their ACLs and permissions after upgrade and might need to reconfigure them in some edge cases.
Certificate Management:
25.10 removes the Certificate Authority (CA) functionality that allowed TrueNAS to create and sign certificates.
Users can continue to manage certificates by creating Certificate Signing Requests (CSRs) to be signed by external certificate authorities or and importing certificates that have been signed by external CAs or directory services.
These alternatives provide the certificate management capabilities most users need while ensuring proper certificate validation through established certificate authorities.
SMART Monitoring:
25.10 removes the built-in SMART test scheduling and monitoring interface. TrueNAS continues automated drive health monitoring through middleware-integrated SMART polling and ZFS failure detection. Existing scheduled SMART tests are automatically migrated to cron tasks during upgrade, and smartmontools binaries remain installed.
See Drive Health Management for more information on disk health monitoring in 25.10 and beyond.
SMB Shares:
In 25.10, SMB share configuration only displays options relevant to each purpose-based preset.
Existing shares that previously used the No Preset option are automatically migrated to the Legacy Share preset during upgrade.
New shares cannot access legacy configuration options.
Legacy Share options include enabling SMB guest access, the SMB recycle bin, home directory export, AFP compatibility shares, and disabling shadow copies.
The SMB recycle bin feature is no longer available for new shares due to security and usability concerns.
For file recovery and versioning, use ZFS snapshots, which provide more reliable and predictable data protection.
For more information, see Legacy Share Settings and the TrueNAS API documentation sharing.smb.create return values for optionsLegacyOpt.
Virtual Machine Startup Changes:
VMs created in TrueNAS 25.04 (pre-25.04.2) and displayed on the Containers screen no longer automatically start on system boot to prevent conflicts with VMs on the Virtual Machines screen.
See Containers and Virtual Machines for more information.
Improves ZFS property handling during dataset replication (NAS-137818).
Resolves issue where the storage page temporarily displayed errors when receiving active replications due to ZFS properties being unavailable while datasets were in an inconsistent state.
Fixes “Failed to load datasets” error on Datasets page (NAS-138034).
Resolves issue where directories with ZFS-incompatible characters (such as [) caused the Datasets page to fail by gracefully handling EZFS_INVALIDNAME errors.
Fixes zvol editing and resizing failures (NAS-137861).
Resolves validation error “inherit_encryption: Extra inputs are not permitted” when attempting to edit or resize VM zvols through the Datasets interface.
Fixes VM disk export failure (NAS-137836).
Resolves KeyError when attempting to export VM disks through the Devices menu, allowing successful disk image exports.
Fixes inability to remove transfer speed limits from SSH replication tasks (NAS-137813).
Resolves validation error “Input should be a valid integer” when attempting to clear the speed limit field, allowing users to successfully remove speed restrictions from existing replication tasks.
Fixes Cloud Sync task bandwidth limit validation (NAS-137922).
Resolves “Input should be a valid integer” error when configuring bandwidth limits by properly handling rclone-compatible bandwidth formats and improving client-side validation.
Fixes NVMe-oF connection failures due to model number length (NAS-138102).
Resolves “failed to connect socket: –111” error by limiting NVMe-oF subsystem model string to 40 characters, preventing kernel errors when enabling NVMe-oF shares.
Fixes application upgrade failures with validation traceback (NAS-137805).
Resolves TypeError “’error’ required in context” during app upgrades by ensuring proper Pydantic validation error handling in schema construction.
Fixes application update failures due to schema validation errors (NAS-137940).
Resolves “argument after ** must be a mapping” exceptions when updating apps by properly handling nested object validation in app schemas.
Fixes application image update checks failing with “Connection closed” error (NAS-137724).
Resolves RuntimeError when checking for app image updates by ensuring network responses are read within the active connection context.
Fixes AMD GPU detection logic (NAS-137792).
Resolves issue where AMD graphics cards were not properly detected due to incorrect kfd_device_exists variable handling.
Fixes API backwards compatibility for configuration methods (NAS-137468).
Resolves issue where certain API endpoints like network.configuration.config were unavailable in the 25.10.0 API, causing “[ENOMETHOD] Method ‘config’ not found” errors when called from scripts or applications using previous API versions.
Fixes console messages display panel not rendering (NAS-137814).
Resolves issue where the console messages panel appeared as a black, unresponsive bar by refactoring the filesystem.file_tail_follow API endpoint to properly handle console message retrieval.
Fixes unwanted “CronTask Run” email notifications (NAS-137472).
Resolves issue where cron tasks were sending emails with subject “CronTask Run” containing only “null” in the message body.
The TrueNAS team is pleased to release TrueNAS 25.10.0.1!
This is a maintenance release that includes fixes to SMB shares, application management, cloud sync operations, and error handling.
Notable changes:
Fixes an SMB2 query directory with SMB_REOPEN flag issue (NAS-138259).
Resolves an issue where client systems connected to TrueNAS 25.10 SMB shares could experience file access issues, including files appearing missing or shares showing as empty when browsing directories, media libraries (Plex, Jellyfin, etc.) losing access to files or removing them from indexes, and files failing to open or save over SMB.
Fixes VFS disconnect handling that prevented Time Machine snapshots (NAS-135813).
Resolves a bug in the io_uring_vfs_disconnect function where walking the Samba VFS stack for smb_vfs_disconnect was terminating early, causing Apple Time Machine snapshots to fail execution. The function now properly traverses the full VFS stack without premature exit.
Fixes Docker service startup failures on systems with slow disk initialization (NAS-138232).
Resolves a timeout issue where Docker initialization on HDD-equipped systems could exceed the default 120-second service timeout. This caused the apps service to be incorrectly marked as FAILED even though Docker eventually started successfully. The service timeout is extended to 960 seconds (16 minutes) to accommodate slower disk scenarios.
Fixes custom application update failures from version 1.2.13 to 1.2.14 (NAS-138230).
Resolves an issue where custom applications failed to update properly, with multiple update attempts yielding no errors but the update notification persisting. The fix ensures that custom app versions are correctly upgraded alongside image updates during the application upgrade process.
Fixes false validation errors for custom app upgrades (NAS-138534).
Resolves an issue where validation errors were incorrectly raised for custom apps during upgrade summaries when only the container image required updating. The system now properly recognizes that custom apps qualify for upgrade availability if either their images are outdated or catalog manifest changes exist.
Fixes cloud sync task validation errors after upgrading to 25.10 (NAS-138281).
Resolves an issue where cloud sync tasks would display no available tasks after upgrade, with validation errors occurring when querying cloud sync tasks. The errors stemmed from Pydantic validation failures where parameters like chunk_size exceeded schema-defined limits.
Fixes a DNS validation typo in directory services (NAS-138364).
Resolves a typo in DNS validation logic where “@” was incorrectly used instead of “.” as the separator between hostname and domain name.
Fixes ZFS error handling for paths with multibyte UTF-8 characters (NAS-138554).
Resolves an issue where ZFS paths containing multibyte characters would generate corrupted error descriptions, causing the Python Unicode decoder to fail. This resulted in simplified error messages instead of detailed ZFS exceptions and misclassification of error codes (EZFS_UNKNOWN instead of EZFS_INVALIDNAME), breaking dataset resolution APIs.
Fixes false temperature alerts for disks with negative threshold values (NAS-138028).
Resolves an issue where disks with invalid or negative temperature thresholds triggered persistent warning alerts in the GUI and automated email notifications. The system now properly filters out disks with negative temperature threshold configurations during alert generation.
Improves NetBIOS naming by expanding permitted identifiers (NAS-138390).
Removes additional blacklist restrictions on NetBIOS names and workgroups, allowing more Microsoft-restricted keywords to be used. This change addresses customer environment needs where previously prohibited network naming identifiers are required.
Known Issue: Apps configured to use SMB or NFS shares as storage can experience an occasional race condition during boot that causes them to show a “crashed” status. The workaround is to restart the affected app after a minute or two. See Known Issues for details. Additional fixes are expected in 25.10.1.
Early releases are intended for testing and feedback purposes.
Do not use early release software for critical tasks.
September 30, 2025
The TrueNAS team is pleased to release TrueNAS 25.10-RC.1!
25.10-RC.1 Notable changes
Enhances remote syslog configuration to support up to two servers (NAS-137315).
Updates the Syslog configuration options in System > Advanced Settings to allow configuring multiple syslog servers with individual transport and TLS certificate options.
Improves NVMeoF target configuration with automatic port defaults (NAS-137394, NAS-137395).
Sets port 4420 as the default for NVMe over Fabric targets, eliminating the need for manual port configuration.
Clarifies VM secure boot configuration as create-only setting (NAS-137397).
Removes secure boot option from VM edit form as this setting can only be configured during initial VM creation.
Fixes upgrade blocking issue for systems without BIOS partition (NAS-137352).
Resolves traceback during 25.10 upgrades on systems originally deployed with TrueNAS CORE that lack a BIOS partition.
Fixes SMB service hanging during Windows client file operations (NAS-137095).
Resolves issue where Windows clients became unresponsive during file moves and editing operations, requiring manual thread termination.
Fixes incorrect disk temperature threshold alerts (NAS-137385).
Resolves issue where critical temperature alerts were triggered incorrectly when threshold was set to 0 degrees Celsius.
Improves password manager compatibility with WebUI login screen (NAS-136335).
Resolves issue where password managers like Bitwarden and Dashlane failed to automatically recognize and fill login credentials.
Consolidates Users page interface (NAS-137443).
Removes legacy Users page and renames Users (WIP) to Users for a cleaner interface experience.
Fixes network usage units display on Applications page (NAS-137428).
Corrects network usage units from lowercase ‘b’ to capital ‘B’ (B/s, kB/s, MB/s) to properly indicate bytes per second.
Fixes UI Bug Reporting feature “FAILED: This TrueNAS build is experimental” error (NAS-137445).
Resolves issue preventing bug report submissions through the UI.
Fixes incorrect time sort for frequency on Cloud Sync Tasks screen (NAS-137096).
Fixes Users page showing “can not retrieve response” error due to invalid email address (NAS-137198).
Fixes Virtual Machines page not refreshing properly (NAS-136973).
Adds VM disk image import and export capabilities (NAS-137334, NAS-137335).
Enables importing disk images (QCOW2, QED, RAW, VDI, VHDX, and VMDK formats) during VM creation and exporting VM disks to portable image formats, streamlining VM migration and setup processes.
Improves Virtual Machine configuration performance (NAS-136937).
Prevents libvirt service from starting automatically when browsing VM creation options, improving system responsiveness.
Enhances session security with improved random number generation (NAS-137318).
Uses SSL-based random number generator for creating session IDs, improving overall cryptographic security.
Fixes an issue where the ACL editor ignored unset “Apply Owner” and “Apply Group” checkboxes and always applied owner/group changes recursively, potentially causing unintended ownership changes (NAS-137378).
The PGP public keys for the TrueNAS Security Team have been renewed and published to the TrueNAS Security Advisories.
Early releases are intended for testing and feedback purposes.
Do not use early release software for critical tasks.
August 28, 2025
The TrueNAS team is pleased to release TrueNAS 25.10-BETA.1!
This first public release version of TrueNAS 25.10 (Goldeye) has software component updates and new features that are in the polishing phase.
Virtual Machines are now “Enterprise ready” with support for TrueNAS Enterprise High Availability (HA) systems and failover (NAS-136509).
Failover moves to the Advanced Settings screen (NAS-135469).
Introduces a redesigned Updates screen that allows users to select an update profile reflecting their risk-tolerance level (NAS-133600). TrueNAS only notifies users of updates recommended for their selected profile level.
Introduces changes to Certificates, Certificate Authorities (CA), and Certificate Signing Requests (CSR) (NAS-135168):
Removes Certificate Authorities (CA) screens and support for CAs, which means you cannot sign CSRs or create self-signed certificates.
Removes Add from Certificates. Users can import a certificate created by an external certificate authority.
Allows adding a certificate using the new Create ACME Certificate screen found under Certificate Signing Requests and an existing DNS authenticator added through the ACME DNS Authenticators screen.
See Preparing to Upgrade for more information.
Introduces a refreshed Users (WIP) screen that provides improved, at-a-glance access to account information and simplified user creation (NAS-134198).
Introduces changes to the Datasets and Storage Dashboard screens (NAS-135362, NAS-135364).
Renames dataset and pool widgets, and changes links to other screens.
Removes Scrub Tasks configuration and scheduling from the Data Protection Tasks screen, but makes it available on the Storage Health widget located on the Storage Dashboard (NAS-135555).
Fixes the NVIDIA GPU-related error “RenderError: Expected [uuid] to be set for GPU in slot” (NAS-134152).
Adds support for directory services authentication via FTP (NAS-135200).
Adds the Enable Secure Boot option to virtual machine configuration screens (NAS-136466).
Allows TrueNAS to automatically migrate existing applications when selecting a new applications pool (NAS-132188).
Adds TrueNAS Apps service support for configuring external container registry mirrors as alternative sources for Docker images (NAS-136553).
Introduces various UI improvements and optimizations to simplify core user experiences (NAS-135159).
Includes critical ZFS stability fixes and performance improvements, including fixed corruptions for plaintext replication of encrypted snapshots, enhanced memory pressure handling, faster pool export operations, improved I/O scaling capabilities, zfs rewrite and Direct I/O support (NAS-135902).
Simplifies and improves robustness of gateway and name server settings when changing from DHCP to static aliases (NAS-136360 and NAS-136360).
Moves Network screen under the System main menu option.
Fixes insufficient memory pressure on ZFS ARC by Virtual Machines to prevent out-of-memory conditions (NAS-135499).
Virtual machines created in 25.04 (pre-25.04.2) and displayed on the Containers screen do not automatically start on system boot to prevent conflicts with VMs on the Virtual Machines screen that might use the same zvols (NAS-136946).
Makes changes to SMB shares:
Enables access-based enumeration for SMB shares with NFSv4 ACL type, so directory listings only show files that users have permission to read (NAS-136499).
Changes SMB share Advanced Options, Purpose, and Other Option settings associated with the preset setting selected (NAS-136499).
Removes the AUTORID IDMAP backend option from Active Directory configuration to improve consistency across multi-server environments (NAS-136630).
Existing configurations using AUTORID are automatically migrated to RID during upgrade.
Users should review their ACLs and permissions after upgrade and might need to reconfigure them in some edge cases.
Completes the transition to the versioned JSON-RPC 2.0 over WebSocket API by migrating all remaining jobs and events from the deprecated REST API (NAS-133984).
Full removal of the REST API is planned for the TrueNAS 27 release.
Removes the built-in SMART test scheduling and monitoring interface to improve user flexibility while maintaining smartmontools binaries for continued third-party script compatibility (NAS-135020).
Existing scheduled SMART tests are automatically migrated to cron tasks during upgrade, and users can install the Scrutiny app for advanced SMART monitoring.
SMART tests functions no longer show on the Data Protections Tasks, Storage Dashboard, or individual disk screens.
See Drive Health Management for more information on the SMART monitoring transition.
Improves drive temperature monitoring efficiency by extending the drivetemp kernel module to include SCSI/SAS disk temperatures.
Fixes an issue affecting drive temperature reporting on the dashboard (NAS-135572).
Fixes a bug to reenable available update notifications for custom apps (NAS-135124).
Fixes contrast issues on some UI theme options (NAS-135519).
These are ongoing issues that can affect multiple versions in the 25.10 series. When resolved, issues move to Notable Changes for the appropriate release.
Current Known Issues
TrueNAS Enterprise
UI login delays during High Availability failover with STIG configuration changes.
When toggling STIG settings in System > Advanced > System Security that require a system reboot, UI login authentication can experience extended delays (over 2 minutes) during failover when one controller is rebooting.
Workaround: Wait 2-3 minutes for authentication timeout to complete.
High Availability STIG configuration changes can cause production downtime if active controller is rebooted prematurely.
When enabling or disabling STIG in System > Advanced > System Security, the system automatically reboots the standby controller in the background. Both controllers must reboot to complete the configuration change.
Workaround: After saving STIG settings, wait until the standby controller is fully online before rebooting the active controller. Rebooting the active controller while the standby is still booting can cause disrupt production.
This issue is resolved in TrueNAS 27.
Apps using SMB/NFS storage can experience race condition during boot.
When apps are configured to use SMB or NFS shares as storage passthroughs, there can be an occasional race condition during TrueNAS boot where the app startup conflicts with the sharing services startup.
This causes affected apps to not fully start and show a “crashed” status.
Workaround: Restart the affected app after a minute or two.
Long-running systems with legacy FreeNAS datasets might encounter dataset editing errors (NAS-138629).
Users might see "aclmode: failed to get property" errors when attempting to edit dataset properties. This affects datasets with invalid aclmode=discard_chmod property values carried over from legacy FreeNAS versions. TrueNAS 25.10.1 improves error messages to help identify affected datasets.
Users encountering this issue should run zfs set aclmode=passthrough dataset_name via CLI for each affected dataset (replacing dataset_name with the actual dataset path), then reboot the system.
NVMe over TCP is incompatible with VMware ESXi environments (NAS-137372).
TrueNAS 25.10 uses the Linux kernel NVMe over TCP target driver, which lacks support for fused commands required by VMware ESXi.
This is an upstream kernel limitation that prevents path initialization in ESXi environments.
Two-Factor Authentication (2FA) can fail during daylight saving time transitions (NAS-138200).
Systems with two-factor authentication configured can experience login failures for approximately one hour during daylight saving time transitions when clocks move backward.
The authentication system resolves automatically once the duplicated hour passes.
Locking encrypted datasets fails when actively shared via iSCSI or SMB.
Attempting to lock an encrypted dataset while it is actively shared via iSCSI or SMB fails with an EBUSY error.
No alert is generated and no email notification is sent when the lock operation fails.
Workaround: Before locking the dataset, disable the share (iSCSI extent or SMB share) in the sharing configuration.
After locking the dataset, you can re-enable the share if needed.
This issue will be resolved in a future TrueNAS release.
Existing SMB sessions cannot connect to shares created after the session was established.
SMB clients with active sessions might be unable to access newly-created shares without first reconnecting to the server.
This is a long-standing behavior that affects all SMB clients, not specific to any operating system.
Workaround: Restart the SMB service in System > Services, or disconnect and reconnect the SMB client (unmount and remount the server).
This issue is resolved in TrueNAS 27.
Fibre Channel iSCSI initiator changes do not apply to the running configuration until the iSCSI service is restarted.
When updating a Fibre Channel initiator on an iSCSI share, SCST updates with the change but the running configuration file does not reflect the update until the iSCSI service is stopped and started.
Workaround: After updating the Fibre Channel initiator, stop and then start the iSCSI service in System > Services to apply the change to the running configuration.
Sorting is unavailable on the Fibre Channel Ports screen, and search does not match every column. The Fibre Channel Ports tab does not provide sortable column headers, unlike the other iSCSI share tabs such as Targets, Extents, and Initiators. Clicking a column header does not reorder the list. The search field also does not match values in every displayed column, so a search for a target name can return no results even when that target shows in the table.
Workaround: None. All configured ports remain listed on the screen.
Switching to the General update profile can display a TypeError on the Update screen (NAS-140736).
When a TrueNAS version is promoted from Early Adopter to General availability, users already running that version who then change their update profile to General can see a TypeError: 'NoneType' object is not subscriptable error on the Update screen. The error persists after refreshing the page or logging out and back in, but clears after a system reboot.
Workaround: Reboot the system after changing the update profile to clear the error message.
This issue is resolved in TrueNAS 27.
The Reload button in the new license confirmation dialog does not reload the web interface (NAS-140931).
After applying a new license, the confirmation dialog appears with a Reload button. Clicking Reload does not trigger a page reload; the license is applied correctly but the web interface continues to display the pre-license state until the page is manually refreshed.
Workaround: After applying a new license, manually refresh the browser page to update the web interface.
See the latest status on Jira for public issues discovered in 25.10 that are being resolved in a future TrueNAS release.
See the Release Notes section of the TrueNAS forum for ongoing updates about known issues, investigations, and statistics about TrueNAS releases.
25.10 (Goldeye) brings many new features and improvements to the TrueNAS experience.
Redesigned Management Interfaces
The Updates screen introduces risk-tolerance profiles for better control over system update notifications, while the refreshed Users screen provides improved account management with streamlined user creation workflows and better at-a-glance access to account information.
Advanced Networking and Storage
TrueNAS 25.10 introduces comprehensive networking enhancements designed for terabit Ethernet performance.
NVMe over Fabric support includes NVMe/TCP for Community Edition and NVMe/RDMA for Enterprise hardware.
RDMA capabilities eliminate TCP overhead and reduce latency for high-performance storage networking on Enterprise systems.
Updated drivers provide 400GbE network interface support, while enhanced network configuration management improves robustness when transitioning between DHCP and static configurations.
Virtual Machine Improvements
TrueNAS 25.10 delivers comprehensive virtual machine enhancements, including Secure Boot support for enhanced security and refined startup behavior to prevent conflicts between container and VM management interfaces.
VM disk import and export capabilities support multiple formats (QCOW2, QED, RAW, VDI, VHDX, VMDK), streamlining VM migration and setup processes.
NVIDIA Open GPU Kernel Module Support
Support for NVIDIA’s open GPU kernel module drivers enables compatibility with the latest graphics cards, including the Blackwell architecture.
Modern GPU acceleration capabilities are available for TrueNAS Apps and container workloads.
See NVIDIA GPU Support for compatibility details.
ZFS Performance and Stability Improvements
Critical ZFS updates include stability fixes for encrypted snapshot replication, enhanced memory pressure handling, faster pool operations, improved I/O scaling, and new Direct I/O support for better performance in virtualized environments.
Application Pool Migration and Registry Mirrors
Automatic migration of existing applications when changing application pools eliminates manual reconfiguration and reduces downtime during pool transitions.
Support for external container registry mirrors provides alternative sources for Docker images, improving reliability.
Flexible Disk Health Monitoring
TrueNAS 25.10 transitions from built-in SMART test scheduling to a more flexible approach with automatic migration of existing tests to cron tasks.
Users can install the Scrutiny app for advanced monitoring or use custom solutions while TrueNAS continues to automatically alert on critical disk health indicators.
See Disk Management for details on the SMART monitoring transition.
Upgrading TrueNAS
Early releases of a major version are intended for testing and feedback purposes only.
Do not use early release software for critical tasks.
TrueNAS is an appliance built from specific Linux packages.
Updating TrueNAS using apt or any method other than the TrueNAS web interface can make the system inoperable.
Modifying the base OS can cause unexpected behavior during upgrades:
Users who manually installed Docker on TrueNAS 24.04 or earlier can experience TrueNAS Apps failure in 24.10 or later.
This occurs due to conflicts between the manually installed and native Docker configurations.
Affected systems can encounter app_lifecycle.compose_action errors, such as: 'group_add[0]' expected type 'string', got unconvertible type 'int', value: '568'
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.
TrueNAS Apps
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.
The TrueNAS REST API is removed in TrueNAS 27.
Systems still using the REST API must migrate to the WebSocket API before upgrading.
Starting with TrueNAS 25.10.1, the system displays alerts when deprecated REST API endpoints are accessed to help identify integrations that require migration to the JSON-RPC 2.0 over WebSocket API.
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 midclt and 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 laptopMy 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.
NVIDIA GPU Compatibility: TrueNAS 25.10 switches to open GPU kernel drivers that are incompatible with legacy NVIDIA GPUs (Pascal, Maxwell, Volta architectures).
See NVIDIA GPU Support for compatibility details.
Virtual Machine Startup Changes: VMs created in TrueNAS 25.04 (pre-25.04.2) and displayed on the Containers screen no longer automatically start on system boot to prevent conflicts with VMs on the Virtual Machines screen.
See Containers and Virtual Machines for more information.
Active Directory AUTORID IDMAP Backend Removal: TrueNAS 25.10 removes this option to improve consistency across multi-server environments (NAS-136630).
Existing configurations using AUTORID are automatically migrated to RID during upgrade.
Users should review their ACLs and permissions after upgrade and might need to reconfigure them in some edge cases.
TrueNAS 25.10 removes the built-in SMART test scheduling and monitoring interface. TrueNAS continues automated drive health monitoring through middleware-integrated SMART polling and ZFS failure detection. Existing scheduled SMART tests are automatically migrated to cron tasks during upgrade, and smartmontools binaries remain installed.
See Drive Health Management for more information on the SMART monitoring transition.
TrueNAS 25.10 removes the Certificate Authority (CA) functionality that allowed TrueNAS to create and sign certificates.
Users can continue to manage certificates by creating Certificate Signing Requests (CSRs) to be signed by external certificate authorities or and importing certificates that have been signed by external CAs or directory services.
These alternatives provide the certificate management capabilities most users need while ensuring proper certificate validation through established certificate authorities.
TrueNAS 25.10 improves SMB share configuration by displaying only options relevant to each purpose-based preset.
Existing shares that previously used the “No Preset” option are automatically migrated to the “Legacy Share” preset during upgrade.
New shares cannot access legacy configuration options.
The SMB recycle bin feature is no longer available for new shares due to security and usability concerns.
For file recovery and versioning, use ZFS snapshots, which provide more reliable and predictable data protection.
See Legacy Share Settings for more information.
Pool usage, disk temperature, and related metrics can have a short delay of no more than 10 minutes before displaying. This is typically seen when TrueNAS boots or in situations where the reporting system restarts.
Containers and Virtual Machines
TrueNAS Enterprise
Virtual Machines are now “Enterprise ready” with support for TrueNAS Enterprise High Availability (HA) systems and failover (NAS-136509).
Virtual Machines and Containers in TrueNAS 25.10
TrueNAS 25.04 introduced support for Containers (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in FreeBSD-based TrueNAS.
In TrueNAS 25.04.2 and later, virtual machines are created and appear on the Virtual Machines screen.
Legacy VMs created in 25.04.0 or 25.04.1 using the instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the Containers screen.
Legacy VMs on the Containers screen do not autostart in 25.10 or later.
Users with existing VMs on the Containers screen should consider migrating associated zvols to the Virtual Machines screen at this time to ensure compatibility with future TrueNAS releases.
For information on migrating your zvol storage volume to a new VM created in 25.10 or later, see Migrating Legacy VMs to Virtual Machines.
Due to backend technology changes in TrueNAS 27, containers on the Containers screen require migration when you upgrade from TrueNAS 25.10.
Containers migrate automatically at the first boot after upgrading, except on HA-capable TrueNAS Enterprise systems.
Containers on a passphrase-encrypted pool do not migrate, because the pool is still locked at first boot and the migration does not retry.
Switch the pool to key encryption before you upgrade.
Contact TrueNAS Enterprise Support if you have containers on a TrueNAS Enterprise system that does not migrate them.
Legacy VMs on the Containers screen are not migrated automatically and are removed from the Containers screen in TrueNAS 27.
Complete the steps in Preparing to Upgrade to TrueNAS 27 before you upgrade.
The Enable Secure Boot option is added to virtual machine configuration screens (NAS-136466).
Virtual machines created in 25.04 (pre-25.04.2) and displayed on the Containers screen do not automatically start on system boot to prevent conflicts with VMs on the Virtual Machines screen that might use the same zvols (NAS-136946).
Virtual machines created in 25.04.0 or 25.04.1 using the Instances (now Containers) screen can be migrated to conventional VMs in 25.10 and later using the process described in the Migrating Legacy VMs to Virtual Machines tutorial.
Resolves ZFS ARC memory management conflicts that were causing out-of-memory crashes in Virtual Machines due to memory fragmentation issues (NAS-135499).
TrueNAS Apps
TrueNAS Apps
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 25.10 adds an option to automatically migrate existing applications when changing apps pool locations (NAS-135720).
See Migrating Existing Applications for details.
25.10 supports configuring external container registry mirrors as alternative sources for Docker images (NAS-136553).
See PD-2125 for more information.
TrueNAS 25.10 changes how disk health monitoring works, transitioning from built-in SMART test scheduling to a flexible approach that better serves modern storage environments.
What Changed
In TrueNAS 25.04 and earlier:
SMART test scheduling was built into the TrueNAS UI
Tests were configured through Data Protection Tasks screens
SMART test results appeared on the Storage Dashboard and individual disk screens
In TrueNAS 25.10 and later:
SMART test scheduling UI is removed
TrueNAS continues automated drive health monitoring through middleware-integrated SMART polling and ZFS failure detection
Manual SMART testing can be scheduled via cron jobs or third-party apps
The smartmontools binaries remain installed and functional
Drive temperature monitoring uses the enhanced drivetemp kernel module, extended to include SCSI/SAS disk temperatures
Why This Changed
This transition addresses several limitations:
Modern Storage Realities: Traditional SMART tests (short and long) designed for mechanical hard drives are less relevant for SSDs and NVMe drives, which now represent an increasing percentage of deployments. These devices focus on different health metrics like write endurance rather than mechanical wear patterns.
Flexibility: The previous system was restrictive and difficult to customize for advanced users.
Reliability: The integrated SMART test scheduler had persistent bugs and maintenance challenges. Scheduled tests could produce false positives and were difficult to troubleshoot.
Better Tools Available: Dedicated monitoring applications like Scrutiny provide superior disk health tracking with historical data storage, customizable alerts, and automatic drive detection.
How Drive Health Management Works in 25.10
TrueNAS monitors the condition of installed HDD and SSD drives (SAS, SATA, and NVMe) through three integrated layers:
ZFS detects sudden failures in real time during active read and write operations and marks affected vdevs or disks as faulted immediately.
TrueNAS Middleware polls SMART data from every drive every 90 minutes. When a polled attribute crosses a failure threshold, TrueNAS generates an alert.
Alert logic filters incoming SMART and ZFS data to suppress known-benign attribute fluctuations, reducing false-positive alerts by approximately 50% compared to prior releases.
Drive health status is visible on the Disk Health card on the Storage dashboard. Active alerts appear in the Alerts panel with details on the affected disk and recommended next steps.
Community Edition users can supplement automated monitoring with manual SMART tests run via cron jobs or the smartctl command-line tool. Third-party tools such as Scrutiny are also available from the TrueNAS Apps catalog.
TrueNAS 25.10 introduces support for NVIDIA open GPU kernel module drivers, preparing TrueNAS to support the latest NVIDIA graphics cards including newer architectures like Blackwell.
This driver update ensures TrueNAS Apps and Containers can utilize modern GPU acceleration workloads.
The open GPU kernel drivers are compatible with Turing architecture and later GPUs, which includes GTX 16-series cards and all RTX series cards.
Newer architectures like NVIDIA Blackwell (RTX 50-series, RTX PRO Blackwell) require the nvidia-open driver to function, as this driver leverages the built-in NVIDIA GSP (GPU System Processor).
To verify your GPU is supported, check the installed NVIDIA driver version in Software Component Versions. Click the driver version number to view the NVIDIA release page, which includes a “Supported Products” tab listing all compatible GPUs for that driver version.
Users with compatible hardware can enable TrueNAS to install NVIDIA drivers.
See the TrueNAS Apps Market for installation instructions.
GPUs based on earlier architectures, including Pascal (GTX 10-series, Quadro P-series), Maxwell (GTX 700 and 900-series), and Volta (GTX Titan V) are not supported by the NVIDIA open drivers.
This is because these older GPUs lack the required GSP component.
Users with incompatible legacy cards can still utilize them by deploying a TrueNAS Virtual Machine and isolating the GPU to it.
This approach involves creating a VM, isolating the legacy GPU to that VM, installing the proprietary NVIDIA driver within the VM environment, and running GPU workloads from within the virtual machine.
However, this workaround requires a secondary GPU (such as integrated Intel graphics or an IPMI console) to handle system display duties, as isolating the only GPU in the system would leave TrueNAS without console access.
Upgrade Paths
Early releases of a major version are intended for testing and feedback purposes only.
Do not use early release software for critical tasks.
Upgrading to TrueNAS 25.10 (Goldeye) 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.
Update to the latest maintenance release of the current major version before upgrading to the next major version.
You can then upgrade directly from the latest maintenance release to the latest release of the next major version.
This chart shows the basic upgrade paths between TrueNAS major versions.
Depending on your use case and risk tolerance, you might prefer to delay upgrading to allow additional time for testing and stability.
See the TrueNAS Software Status for version recommendations tailored to different user types 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| J
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.4 (Electric Eel)"] -->|update| I
I["25.04.2.6 (Fangtooth)"] -->|update| J
J["25.10.8 (Goldeye)"] -->|"anticipated"| K
K["TrueNAS 26.0"]
flowchart LR
A["11.3-U5"] -->|update| B
B["12.0-U8.1"] -->|update| C
C["13.0-U6.8"] -->|ISO install| H
C -->|update| E
D["23.10.2 (Cobia)"] -->|update| E
E["24.04.2.5 (Dragonfish)"] -->|update| F
F["24.10.2.4 (Electric Eel)"] -->|update| G
G["25.04.2.6 (Fangtooth)"] -->|update| H
H["25.10.8 (Goldeye)"] -->|"anticipated"| I
I["TrueNAS 26.0"]
Permitted upgrade methods are:
update: Apply updates using the Update screen in the TrueNAS UI or install a manual update file.
Not all upgrade paths support automatic updates (see chart).
ISO install: Save your TrueNAS configuration file, perform a fresh install using an .iso file for the target version, then upload the saved configuration.
You can skip major versions using a fresh installation with configuration file restore.
Before skipping versions, review release notes for each major version to identify service deprecations or significant changes that might affect your configuration.
Consider upgrading incrementally through major versions with significant changes, or be prepared to manually reconfigure any incompatibilities after upgrading directly to the target version.
Migrating from TrueNAS 13.0 or 13.3
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 release version, 13.0-U6.7 (or 13.3-U1.2 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.
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.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
*TrueNAS 25.10 and later includes the NVIDIA open GPU kernel module drivers.
These drivers work with Turing and later GPUs.
Earlier architectures (Pascal, Maxwell, Volta) are not compatible.
See NVIDIA GPU Support for more information.
OpenZFS Feature Flags
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.3.0) are listed below:
This article tracks any TrueNAS features that are being deprecated in the latest nightly development versions.
Items are added and possibly removed as TrueNAS development continues to evolve.
TrueNAS Hardware Guide
From repurposed systems to highly custom builds, the fundamental freedom of TrueNAS is the ability to run it on almost any x86 computer.
Minimum Hardware Requirements
Processor
Memory
Boot Device
Storage
2-Core Intel 64-Bit or AMD x86_64 processor
8 GB memory
16 GB SSD boot device
Two identically-sized devices for a single storage pool
The TrueNAS installer recommends 8 GB of RAM.
TrueNAS installs, runs, and operates jails (in TrueNAS 13).
It also hosts SMB shares and replicates TBs of data with less.
The TrueNAS team recommends the above for better performance and fewer issues.
You do not need an SSD boot device, but we discourage using a spinner or a USB stick.
We do not recommend installing TrueNAS on a single disk or striped pool unless you have a good reason to do so.
You can install and run TrueNAS without any data devices, but we strongly discourage it.
TrueNAS does not require two cores, as most halfway-modern 64-bit CPUs likely already have at least two.
For help building a system according to your unique performance, storage, and networking requirements, keep reading.
Storage Considerations
The heart of any storage system is the symbiotic pairing of the file system and physical storage devices.
The ZFS file system in TrueNAS provides the best available data protection of any file system at any cost and makes effective use of spinning-disk storage, all-flash storage, or a mix of both.
ZFS is prepared for the eventual failure of storage devices and is highly configurable to achieve the perfect balance of redundancy and performance to meet any storage goal.
A properly configured TrueNAS system can tolerate multiple storage device failures and recreate its boot media with a copy of the configuration file.
Storage Device Quantities
TrueNAS can manage many storage devices as part of a single storage array.
With more enterprise-level tuning, TrueNAS can manage as many as 1,250 drives in a single storage array!
Storage Media
Choosing storage media is the first step in designing the storage system to meet immediate objectives and prepare for future capacity expansion.
Spinning Disks
Until the next scientific breakthrough in storage media, spinning hard disks are here to stay thanks to their balance of capacity and cost.
The arrival of double-digit terabyte consumer and enterprise drives provides more choices to TrueNAS users than ever.
TrueNAS Mini systems ship with Western Digital NAS and NL-SAS by default. Understanding the alternatives explains why.SATA NAS Disks
Serial Advanced Technology Attachment (SATA) is still the de facto standard disk interface found in many desktop/laptop computers, servers, and some non-enterprise storage arrays.
The first SATA disks offered double-digit gigabyte capacities. Newer SATA disks meet many size, reliability, and performance goals.
While consumer desktop SATA disks do not have the overall reliability issues they once had, they are still not designed or warrantied for continuous operation or use in RAID groups.
Enterprise SATA disks address the always-on factor, vibration tolerance, and drive error handling required in storage systems.
However, the price gap between desktop and enterprise SATA drives is so vast that many users push their consumer drives into 24/7 service pursuing cost savings.
Drive vendors, likely tired of honoring warranties for failed desktop drives used in incorrect applications, responded to this gap in the market by producing NAS drives.
NAS drives achieved fame from the original Western Digital (WD) Red™ drives with Conventional Magnetic Recording (CMR) technology (now called WD Red Plus).
Western Digital designed the WD Red™ Plus NAS drives (non-SMR) for systems with up to 8 hard drives, the WD Red™ Pro for systems with up to 16 drives, and the WD UltraStar™ for systems beyond 16 drives.
The TrueNAS Community prefers WD drives for TrueNAS builds due to their exceptional quality and reliability.
All TrueNAS Minis ship with WD Red™ Plus drives unless requested otherwise.
SMR drives offer greater storage density than their CMR equivalents, but slower write and overwrite performance and the potential for instability or data loss during resilver operations make them a poor fit for ZFS.
SMR drives come in three variants, and TrueNAS handles each differently:
Drive-Managed SMR (DM-SMR) and Host-Aware SMR (HA-SMR) drives function poorly with TrueNAS, and the TrueNAS team does not recommend them. Expect degraded write performance and longer, less reliable resilver operations.
Host-Managed SMR (HM-SMR) drives are not supported. ZFS cannot manage the zone semantics these drives require, so they do not work with TrueNAS.
Consult your drive manufacturer, such as Western Digital or Seagate, to determine whether a disk uses CMR or SMR technology and which SMR variant.
Nearline SAS Disks
Nearline SAS (NL-SAS) disks are 7200 RPM enterprise SATA disks with the industry-standard SAS interface in most enterprise storage systems.
SAS stands for serial attached SCSI, with the traditional SCSI disk interface in serial form.
SAS systems, designed for data center storage applications, have accurate, verbose error handling, predictable failure behavior, reliable hot swapping, and the added feature of multipath support.
Multipath access means that each drive has two interfaces and can connect to two storage controllers or one controller over two cables.
This redundancy protects against cable, controller card, or complete system failure in the case of the TrueNAS high-availability architecture in which each controller is an independent server that accesses the same set of NL-SAS drives.
NL-SAS drives are also robust enough to handle the rigors of systems with more than 16 disks.
So, capacity-oriented TrueNAS systems ship with Western Digital UltraStar NL-SAS disks thanks to the all-around perfect balance of capacity, reliability, performance, and flexibility that NL-SAS drives offer.SAS Disks
Enterprise SAS disks, built for the maximum performance and reliability that a spinning platter can provide, are the traditional heavy-lifters of the enterprise storage industry.
SAS disk capacities are low compared to NL-SAS or NAS drives due to the speed at which the platters spin, reaching as high as 15,000 RPMs.
While SAS drives might sound like the ultimate answer for high-performance storage, many consumer and enterprise flash-based options have come onto the market and significantly reduced the competitiveness of SAS drives.
For example, we almost completely replaced enterprise SAS drives discontinued from the TrueNAS product lines with flash drives (SSDs or NVMe) in 2016 due to their superior performance/cost ratio.SATA & SAS Flash Storage SSDs
Flash storage technology has progressed significantly in recent years, leading to a revolution in mobile devices and the rise of flash storage in general-purpose PCs and servers.
Unlike hard disks, flash storage is not sensitive to vibration and can be much faster with comparable reliability.
Flash storage remains more expensive per GB, but is becoming more common in TrueNAS systems as the price gap narrows.
The shortest path for introducing flash storage into the mainstream market was for vendors to use standard SATA/SAS hard disk interfaces and form factors that emulate standard hard disks without moving parts.
For this reason, flash storage Solid State Disks (SSDs) have SATA interfaces and are the size of 2.5" laptop hard disks, allowing using them as drop-in replacements for traditional hard disks.
Flash storage SSDs can replace HDDs for primary storage on a TrueNAS system, resulting in a faster, albeit smaller or more expensive storage solution.
If you plan to go all-flash, buy the highest-quality flash storage SSDs your budget allows, focusing on power, safety, and write endurance that matches your expected write workload.
NVMe
While SSDs pretending to be HDDs made sense for rapid adoption, the Non-Volatile Memory Express (NVMe) standard is a native flash protocol that takes full advantage of the flash storage non-linear, parallel nature.
The main advantage of NVMe is low-latency performance. NVMe is becoming a mainstream option for boot and other tasks.
At first, NVMe only came in expansion-card form factors such as PCIe and M.2.
The new U.2 interface offers a universal solution that includes the 2.5" drive form factor and an externally accessible (but generally not hot-swappable) NVMe interface.
NVMe devices can run quite hot and might need dedicated heat sinks.
Manual S.M.A.R.T. tests on NVMe devices are currently not supported.
USB Hard Disks
Avoid using USB-connected hard disks for primary storage with TrueNAS. You can use USB Hard Disks for very basic backups in a pinch.
While TrueNAS does not automate this process, you can connect a USB HDD, replicate at the command line, and then take it off-site for safekeeping.
Warning: USB-connected media (including SSDs) might report their serial numbers inaccurately, making them indistinguishable.
These storage device media arrange together to create powerful storage solutions.
Storage Solutions
Hybrid Storage & Flash Cache (SLOG/ZIL/L2ARC)
With hard disks providing double-digit terabyte capacities and flash-based options providing even higher performance, a best-of-both-worlds option is available.
With TrueNAS and OpenZFS, you can merge flash and disk to create hybrid storage that makes the most of both types.
Hybrid setups use high-capacity spinning disks to store data, while DRAM and flash perform hyper-fast read and write caching.
The technologies work together with a flash-based separate write log (SLOG). Think of it as a write cache keeping the ZFS-intent log (ZIL) that speeds up writes.
On the read side, flash is a level two adaptive replacement (read) cache (L2ARC) to keep the hottest data sets on the faster flash media.
Workloads with synchronous writes, such as NFS and databases, benefit from SLOG devices, while workloads with frequently-accessed data might benefit from an L2ARC device.
An L2ARC device is not always the best choice because the level one ARC in RAM always provides a faster cache, and the L2ARC table uses some RAM.
SLOG devices do not need a large capacity since they only need to service five seconds of data writes delivered by the network or a local application.
A high-endurance, low-latency device between 8 GB and 32 GB is adequate for most modern networks, and you can strip or mirror several devices for either performance or redundancy.
Pay attention to the published endurance claims for the device since a SLOG acts as the funnel point for most of the writes made to the system.
SLOG devices also need power protection.
The purpose of the ZFS intent log (ZIL), and thus the SLOG, is to keep sync writes safe during a crash or power failure.
If the SLOG is not power-protected and loses data after a power failure, it defeats the purpose of using a SLOG in the first place.
Check the manufacturer specifications for the device to ensure the SLOG device is power-safe or has power loss/failure protection.
The most important quality to look for in an L2ARC device is random read performance.
The device must support more IOPS than the primary storage media it caches.
For example, using a single SSD as an L2ARC is ineffective in front of a pool of 40 SSDs, as the 40 SSDs can handle far more IOPS than the single L2ARC drive.
As for capacity, 5x to 20x more than the RAM size is a good guideline.
High-end TrueNAS systems can have NVMe-based L2ARC in double-digit terabyte sizes.
Remember that for every data block in the L2ARC, the primary ARC needs a 96-byte entry.
Poorly-designed systems can cause an unexpected fill-up in the ARC and reduce performance.
For example, a 480 GB L2ARC filled with 4KiB blocks needs more than 10GiB of metadata storage in the primary ARC.
Self Encrypting Drives
TrueNAS supports two forms of data encryption at rest to achieve privacy and compliance objectives: native ZFS encryption and self-encrypting drives (SEDs).
SEDs do not experience the performance overhead introduced by software partition encryption but are not as readily available as non-SED drives (and thus can cost a little more).Boot Devices
Booting legacy FreeNAS systems from 8 GB or larger USB flash drives was once very popular.
We recommend looking at other options since USB drive quality varies widely, and modern TrueNAS versions perform increased drive writes to the boot pool.
For this reason, all pre-built TrueNAS Systems ship with either M.2 drives or SATA DOMs.
SATA DOMs, or disk-on-modules, offer reliability close to consumer 2.5" SSDs with a smaller form factor that mounts to an internal SATA port and does not use a drive bay.
Because SATA DOMs and motherboards with M.2 slots are not as common as the other storage devices mentioned here, users often boot TrueNAS systems from 2.5" SSDs and HDDs (often mirrored for added redundancy).
The recommended size for the TrueNAS boot volume is 8 GB, but 16 or 32 GB (or a 120 GB 2.5" SATA SSD) provides room for more boot environments.
Hot Swapability
TrueNAS systems come in all shapes and sizes.
Many users want external access to all storage devices for efficient replacement if issues occur.
Most hot-swap drive bays need a proprietary drive tray into which you install each drive.
These bay and tray combinations often include convenient features like activity and identification lights to visualize activity and illuminate a failed drive with sesutil(8) for FreeBSD-based TrueNAS versions or for Linux-based TrueNAS versions.
TrueNAS Mini systems ship with four or more hot-swap bays.
TrueNAS R-Series systems can support dozens of drives in their head units and external expansion shelves.
Pre-owned or repurposed hardware is popular among TrueNAS users. Pay attention to the maximum performance offered by the hot-swap backplanes of a given system.
Aim for at least 6 Gbps SATA III support.
Note that hot-swapping PCIe NVMe devices is not currently supported.
TrueNAS does not officially support T10-DIF drives. Users on our forums have developed a workaround for using T10-DIF drives in TrueNAS, but using unsupported storage devices imposes data-loss risks.
Storage Device Sizing
Pool layout (the organization of LUNs and volumes, in TrueNAS/ZFS parlance) is outside of the scope of this guide.
The availability of double-digit terabyte drives raises a question TrueNAS users now have the luxury of asking: How many should I use to achieve my desired capacity?
You can mirror two 16 TB drives to achieve 16 TB of available capacity, but that does not mean you should.
Mirroring two large drives offers the advantage of redundancy and balancing reads between the two devices, which could lower power draw, but little else.
The write performance of two large drives is similar to that of a single drive.
By contrast, an array of eight 4 TB drives offers a wide range of configurations to optimize performance and redundancy at a lower cost.
If configured as striped mirrors, eight drives can yield four times greater write performance with a similar total capacity.
You might also consider adding a hot-spare drive with any pool configuration, which lets the pool automatically rebuild itself if one of its primary drives fails.
Storage Device Burn-In
Spinning disk hard drives have moving parts that are highly sensitive to shock and vibration and wear out with use.
Consider pre-flighting every storage device before putting it into production, especially:
Start a long HDD self-test (smartctl -t long /dev/). After the test completes (could take 12+ hrs):
Check the results (smartctl -a /dev/)
Check pending sector reallocations (smartctl -a /dev/ | grep Current_Pending_Sector)
Check reallocated sector count (smartctl -a /dev/ | grep Reallocated_Sector_Ct)
Check the UDMA CRC errors (smartctl -a /dev/ | grep UDMA_CRC_Error_Count)
Check HDD and SSD write latency consistency (diskinfo -wS for FreeBSD-based or iostat or fio for Linux-based TrueNAS systems) Unformatted drives only!
Check HDD and SSD hours (smartctl -a /dev/ | grep Power_On_Hours)
Take time to create a pool before deploying the system.
Subject it to as close to a real-world workload as possible to reveal individual drive issues and help determine if an alternative pool layout is better suited to that workload.
Be cautious of used drives, as vendors might not be honest or informed about their age and health.
Verify vendors have not recertified drives by checking the hours using smartctl(8) for all new drives.
A drive vendor might also zero the hours of a drive during recertification, masking the drive age.
The TrueNAS team tests all storage devices it sells for at least 48 hours before shipment.
Storage Controllers
The uncontested most popular storage controllers used with TrueNAS are the 6 and 12 Gbps (Gigabits per second, sometimes expressed as Gb/s) Broadcom (formerly Avago, formerly LSI) SAS host bus adapters (HBA).
Controllers ship embedded on some motherboards but are generally PCIe cards with four or more internal or external SATA/SAS ports.
The 6 Gbps LSI 9211 and rebranded siblings with the LSI SAS2008 chip, such as the IBM M1015 and Dell H200, are legendary among TrueNAS users who build systems using parts from the second-hand market.
Flash using the latest IT or Target Mode firmware to disable the optional RAID functionality found in the IR firmware on Broadcom controllers.
For those with the budget, newer models like the Broadcom 9300/9400 series give 12 Gbps SAS capabilities and even NVMe to SAS translation abilities with the 9400 series.
TrueNAS includes the sas2flash, sas3flash, and storcli commands to flash or perform re-flashing operations on 9200, 9300, and 9400 series cards.
Onboard SATA controllers are popular with smaller builds, but motherboard vendors are better at catering to the needs of NAS users by including more than the traditional four SATA interfaces.
Be aware that many motherboards ship with a mix of 3 Gbps and 6 Gbps onboard SATA interfaces and that choosing the wrong one can impact performance.
If a motherboard includes hardware RAID functionality, do not use or configure it, but note that disabling it in the BIOS might remove some SATA functionality, depending on the motherboard.
Most SATA compatibility-related issues are immediately apparent.
There are countless warnings against using hardware RAID cards with TrueNAS.
ZFS and TrueNAS provide a built-in RAID that protects your data better than any hardware RAID card.
You can use a hardware RAID card if it is all you have, but there are limitations.
First and most importantly, do not use their RAID facility if your hardware RAID card supports HBA mode, also known as passthrough or JBOD mode (there is one caveat in the bullet list below). When used, it allows it to perform indistinguishably from a standard HBA.
If your RAID card does not have this mode, you can configure a RAID0 for every disk in your system.
While not the ideal setup, it works in a pinch.
If repurposing hardware RAID cards with TrueNAS, be aware that some hardware RAID cards can:
Mask disk serial number and S.M.A.R.T. health information
Perform slower than their HBA equivalents
Cause data loss if using a write cache with a dead battery backup unit (BBU)
SAS Expanders
A direct-attached system, where every disk connects to an interface on the controller card, is optimal but not always possible.
A SAS expander (a port multiplier or splitter) enables each SAS port on a controller card to service many disks.
You find SAS expanders only on the drive backplane of servers or JBODs with more than twelve drive bays.
For example, a TrueNAS JBOD that eclipses 90 drives in only four rack units of space is not possible without SAS expanders.
Imagine how many eight-port HBAs you need to access 90 drives without SAS expanders.
While SAS expanders, designed for SAS disks, can often support SATA disks via the SATA Tunneling Protocol or STP, we still prefer SAS disks for reasons mentioned above in the NL-SAS section (SATA disks function on a SAS-based backplane).
Remember that you cannot use a SAS drive in a port designed for SATA drives.
Storage Device Cooling
A much-cited study floating around the Internet asserts that drive temperature has little impact on drive reliability.
The study makes for a great headline or conversation starter, but carefully reading the report indicates that they tested the drives under optimal environmental conditions.
The average temperature that a well-cooled spinning hard disk reaches in production is around 28 °C, and one study found that disks experience twice the number of failures for every 12 °C increase in temperature.
Before adding drive cooling that often comes with added noise (especially on older systems), know that you risk throwing money away by running a server in a data center or closet without noticing that the internal cooling fans are at their lowest setting.
Pay close attention to drive temperature in any chassis that supports 16 or more drives, especially if they are exotic, high-density designs.
Every chassis has certain areas that are warmer for whatever reason. Watch for fan failures and the tendency for some models of 8 TB drives to run hotter than other drive capacities.
In general, try to keep drive temperatures below the drive specification provided by the vendor.
Memory, CPU, and Network Considerations
Memory Sizing
TrueNAS has higher memory requirements than many Network Attached Storage solutions for good reason: it shares dynamic random-access memory (DRAM or simply RAM) between sharing services, jails or apps, virtual machines, and sophisticated read caching.
RAM rarely goes unused on a TrueNAS system, and enough RAM is vital to maintaining peak performance.
You should have 8 GB of RAM for basic TrueNAS operations with up to eight drives. Other use cases each have distinct RAM requirements:
Add 1 GB for each drive added after eight to benefit most use cases.
Add extra RAM (in general) if more clients connect to the TrueNAS system.
A 20 TB pool backing many high-performance VMs over iSCSI might need more RAM than a 200 TB pool storing archival data.
If using iSCSI to back up VMs, plan to use at least 16 GB of RAM for good performance and 32 GB or more for optimal performance.
Add 2 GB of RAM for directory services for the Winbind internal cache.
Add more RAM for plugins and jails, as each has specific application RAM requirements.
Add more RAM for virtual machines with a guest operating system and application RAM requirements.
Add the suggested 5 GB per TB of storage for deduplication that depends on an in-RAM deduplication table.
Add approximately 1 GB of RAM (conservative estimate) for every 50 GB of L2ARC in your pool.
Attaching an L2ARC drive to a pool uses some RAM, too. ZFS needs metadata in ARC to know what data is in L2ARC.
Error Correcting Code Memory
Electrical or magnetic interference inside a computer system can cause a spontaneous flip of a single bit of RAM to the opposite state, resulting in a memory error.
Memory errors can cause security vulnerabilities, crashes, transcription errors, lost transactions, and corrupted or lost data.
So RAM, the temporary data storage location, is one of the most vital areas for preventing data loss.
Error-correcting code or ECC RAM detects and corrects in-memory bit errors as they occur.
If errors are severe enough to be uncorrectable, ECC memory causes the system to hang (become unresponsive) rather than continue with errored bits.
For ZFS and TrueNAS, this behavior virtually eliminates any chances that RAM errors pass to the drives to cause corruption of the ZFS pools or file errors.
To summarize the lengthy, Internet-wide debate on whether to use error-correcting code (ECC) system memory with OpenZFS and TrueNAS, most users strongly recommend ECC RAM as another data integrity defense. However:
Some CPUs or motherboards support ECC RAM but not all
Many TrueNAS systems operate every day without ECC RAM
RAM of any type or grade can fail and cause data loss
RAM failures usually occur in the first three months, so test all RAM before deployment.
Central Processing Unit (CPU) Selection
Choosing ECC RAM limits your CPU and motherboard options, but that can be beneficial.
Intel® limits ECC RAM support to workstation and server motherboards.
The 13th generation of their consumer CPUs, such as the Core i5 and i7, support ECC as long as they are paired with a workstation motherboard chipset, such as the W680.
Refer to Intel ARK for a full list of Intel CPUs with ECC support.
Which CPU to choose can come down to a short list of factors:
An underpowered CPU can create a performance bottleneck because of how OpenZFS compresses and encrypts (optional) data and performs checksums.
A higher-frequency CPU with fewer cores usually performs best for SMB-only workloads because of Samba, the lightly-threaded TrueNAS SMB daemon.
A higher-core-count CPU is better suited for parallel encryption and virtualization.
A CPU with AES-NI encryption acceleration support improves the speed of the file system and network encryption.
A server-class CPU is recommended for power and ECC memory support.
A Xeon E5 CPU (or similar) is recommended for software-encrypted pools.
An Intel Ivy Bridge CPU or later is recommended for virtual machine use.
Watch for VT-d/AMD-Vi device virtualization support on the CPU and motherboard to pass PCIe devices to virtual machines.
Be aware if a given CPU contains a GPU or requires an external one. Also note that many server motherboards include a BMC chip with a built-in GPU. See below for more details on BMCs.
AMD CPUs are becoming more popular thanks to the Ryzen and EPYC (Naples/Rome) lines.
Support for these platforms is limited on FreeBSD and, by extension, TrueNAS 13. However, Linux has more support, and TrueNAS 24.10 should work with AMD CPUs without issue.
SHA Extensions for x86 instruction set architecture
SHA Extensions in the x86 instruction set architecture support Secure Hash Algorithm family hardware acceleration.
Intel Goldmont (and later), Ice Lake (and later), and Rocket Lake (and later), as well as AMD Zen (and later) processors support the SHA instruction set.
Remote Management: IPMI
As a courtesy to further limit the motherboard choices, consider the Intelligent Platform Management Interface or IPMI (a.k.a. baseboard management controller, BMC, iLo, iDrac, and other names depending on the vendor) if you need:
Remote power control and monitoring of remote systems
Remote console shell access for configuration or data recovery
Remote virtual media for TrueNAS installation or reinstallation
TrueNAS relies on its web-based user interface (UI), but you might occasionally need console access to make network configuration changes.
TrueNAS administration and sharing use a single network interface by default, which can be challenging when you upgrade features like LACP aggregated networking.
The ideal solution is to have a dedicated subnet to access the TrueNAS web UI, but not all users have this luxury.
The occasional visit to the hardware console is necessary for global configuration and system recovery.
The latest TrueNAS Mini and R-Series systems ship with full-featured, HTML5-based IPMI support on a dedicated gigabit network interface.
Power Supply Units
The top criteria to consider for a power supply unit (or PSU) on a TrueNAS system are:
Power capacity (in watts) for the motherboard and the number of drives it must support
Reliability
Efficiency rating
Relative noise
Optional redundancy to keep critical systems running if one power supply fails
Select a PSU rated for the initial and a future load placed on it.
Have a PSU with adequate power to migrate from a large-capacity chassis to a fully-populated chassis.
Also, consider a hot-swappable redundant PSU to help guarantee uptime.
Users on a budget can keep a cold spare PSU to limit their potential downtime to hours rather than days.
A good, modern PSU is efficient and integrates into the IPMI management system to provide real-time fan, temperature, and load information.
Most power supplies carry a certified efficiency rating known as an 80 Plus rating.
The 80 plus rating indicates the PSU loses the power drawn from the wall as heat, noise, and vibration instead of powering your components.
If a power supply needs to draw 600 watts from the wall to provide 500 watts of power to your components, it operates at 500/600 = ~83% efficiency.
The other 100 watts get lost as heat, noise, and vibration.
Power supplies with higher ratings are more efficient but also far more expensive.
Do some return-on-investment calculations if you are unsure what efficiency to buy.
For example, if an 80 Plus Platinum PSU costs $50 more than the comparable 80 Plus Gold, it should save you at least $10 per year on your power bill for that investment to pay off over five years.
You can read more about 80 Plus ratings in this post.
Uninterruptible Power Supplies
TrueNAS allows the system to communicate with a battery-backed, uninterruptible power supply (UPS) over a traditional serial or USB connection to coordinate a graceful shutdown in the case of power loss.
TrueNAS works well with APC brand UPS, followed by CyberPower. Consider budgeting for a UPS with pure sine wave output.
Some models of SSD can experience data corruption on power loss.
If several SSDs experience simultaneous power loss, it could cause total pool failure, making a UPS a critical investment.
Ethernet Networking
The network in Network Attached Storage is as important as storage, but the topic has a few key points:
Simplicity - Simplicity is often the secret to reliability with network configurations.
Individual interfaces - Faster individual interfaces such as 10/25/40/100GbE are preferable to aggregating slower interfaces.
Interface support - Intel and Chelsio interfaces are the best-supported options.
Packet fragmentation - Only consider jumbo framesMTU with dedicated connections, such as between servers or video editors and TrueNAS that are unlikely to experience packet fragmentation.
LRO/LSO offload features - Interfaces with LRO and LSO offload features generally alleviates the need for jumbo frames, and their use can result in lower CPU overhead.
High-Speed Interconnects
Higher-band hardware is becoming more accessible as the hardware development pace increases and enterprises upgrade more quickly.
Home labs can now deploy and use 40 GB and higher networking components. Home users are now discovering the same issues and problems with these higher speeds found by Enterprise customers.
Use optical fiber over direct attached copper (DAC) cables for the high-speed interconnects listed below:
10Gb NICs: SFP+ connectors
25Gb NICs: SFP28 connectors
40Gb NICs: QSFP+ connectors
100Gb NICs: QSFP28 connectors
200Gb NICs: QSFP56 connectors
400Gb NICs: QSFP-DD connectors
Use optical fiber for any transceiver form factors mentioned when using fiber channels.
Direct attached copper (DAC) cables can create interoperability issues between the NIC, cable, and switch.
Virtualized TrueNAS
Finally, the ultimate TrueNAS hardware question is whether to use actual hardware or choose a virtualization solution.
At the heart of the TrueNAS design is OpenZFS. OpenZFS works best with physical storage devices. It is aware of their strengths and compensates for their weaknesses.
TrueNAS developers virtualize TrueNAS every day as part of their work, and it is intended only for use as a development environment.
While you can deploy TrueNAS in a virtual environment, we do not recommend doing so for regular deployment of TrueNAS when storing production or critical data.
Virtualizing TrueNAS and using virtual disks for your pool is fine for ad hoc proof-of-concept, but it is not a supported configuration and might result in data corruption.
When the need arises to virtualize TrueNAS (for ad hoc proof-of-concept):
Pass hardware disks or the entire storage controller to the TrueNAS VM if possible (requires VT-d/AMD-Vi support).
Disable automatic scrub pools on virtualized storage such as VMFS, and never scrub a pool while running storage repair tasks on another layer.
Use at least three vdevs to provide adequate metadata redundancy, even with a striped pool.
Provide one or more 8 GB or larger boot devices.
Provide the TrueNAS VM with adequate RAM per its usual requirements.
Consider jumbo frame networking if all devices support it.
Understand that the guest tools in FreeBSD might lack features other guest operating systems have.
Enable MAC address spoofing on virtual interfaces and enable promiscuous mode to use VNET jail and plugins.
Installation Instructions
This section provides instructions for users that are installing TrueNAS the first time on their own system hardware and for users that need to do a clean install of TrueNAS.
TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial set up and configuration of their systems.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
The installation process covers installing TrueNAS using an iso.
TrueNAS uses DHCP to provide the initial system IP address.
After that, either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the TrueNAS UI to make network changes and complete the initial configuration.
Finally, it covers backing up your system configuration to a file and saving an initial system debug file.
Installing TrueNAS: Provides the TrueNAS iso file installation instructions for physical hardware and virtual machines. Describes the iso verification process using an OpenPGP encryption application.
Installing TrueNAS Enterprise (HA): Provides a sequential process to complete the installation of a TrueNAS Enterprise (HA) dual controller NAS system using an iso file and the TrueNAS UI.
Using the Console Setup Menu: Provides information on using the Console Setup menu after installing TrueNAS from the iso file to configure network settings.
Preparing for TrueNAS UI Configuration
Users installing and configuring TrueNAS on their own servers should follow the instructions in this article to prepare for their deployment.
For support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.
If you are not the administrator responsible for network access in your company, contact your network administrator for assistance.
If your company obtains network hardware and support from an Internet or cable service provider, contact them for assistance with where to obtain this information.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from an .iso file.
IPMI Access
Intelligent Platform Management Interface (IPMI) servers provide access to servers and allow remote users to install software and configure or administrate systems at the console level, or as though you are in the room with the server when you are working remotely. Ensure IPMI is properly configured for secure remote management of TrueNAS servers.
To provide for remote administration of your TrueNAS system, assign access through an IPMI server to the TrueNAS server.
To make this possible assign an IP address to use for access and set up administrator credentials (user name and password) to access the TrueNAS IPMI connections.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address.
You can use this DHCP-provided address, or you can assign a static IP address.
You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller.
Either allow DHCP to assign the IP address or assign a static IP.
If you obtained network equipment and Internet service access from either an Internet or cable service provider, contact their support departments for assistance with network addresses.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses either SMTP to send mail from TrueNAS to administrator or designated individual email addresses for system alert notifications.
If you do not know this information and do not have a network administrator in your company, or if you are a home user, contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
Directory Service Access
This section does not apply to small companies with very few users or home deployments of TrueNAS.
TrueNAS works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap.
Active Directory and LDAP configuration settings have similar requirements.
Active Directory
Provide the following information to configure TrueNAS Active Directory access:
Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow TrueNAS to communicate with the server)
List of trusted domains TrueNAS should allow
LDAP
Provide the following information to configure TrueNAS LDAP access:
Host name where the LDAP sever is located and where TrueNAS accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for TrueNAS to use for authentication
Advanced Directory Services
When configuring Kerberos and/or IDmap, you might need to provide:
Kerberos realm and keytab information
IDmap schema information
Preparing for TrueNAS UI Configuration (Enterprise)
TrueNAS Enterprise
TrueNAS Enterprise customers, or those that purchased systems and service contracts from iXsystems, should use the information in this article to prepare for their TrueNAS system deployments.
The TrueNAS Enterprise Support department provides assistance with the configuration areas documented in this section.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Because there are many possible scenarios for network configurations, this section covers the basics of the access and information required to configure TrueNAS to work in your network environment.
If you are the individual tasked with installing and configuring the TrueNAS server but are not responsible for network services in your company, contact your network administrator to request they provision and verify new IP address assignments and provide the other information for access.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from an .iso file.
IPMI Access
The Intelligent Platform Management Interface (IPMI) provides a way for system administrators to remotely access their TrueNAS system.
Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server.
TrueNAS Enterprise systems sold by iXsystems provide IPMI network ports, but other hardware might not have IPMI ports.
iXsystems requires access through your IPMI server to access the TrueNAS server to provide remote administration support.
To make this possible:
Assign an IP address to the IPMI port of each controller in the TrueNAS array.
If you have a High Availability (HA) system, the server is equipped with two controllers so assign two IP addresses, one for each controller.
Create and provide administrator credentials (user name and password) for access to the TrueNAS IPMI connections.
Configure the administrator credentials to access both IP addresses assigned to the HA system controllers.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address.
You can use this DHCP-provided address, or you can assign a static IP address.
You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller.
Either allow DHCP to assign the IP address or assign a static IP.
If you have an HA system with two controllers, you must assign a total of three IP addresses:
A virtual IP for access to the UI when either controller is active
An IP address for the primary network port on controller A
An IP address for the primary network port on controller B
TrueNAS Enterprise Support can assist you with any questions you have with these network requirements.
Provide the information listed to iXsystems when requested to expedite configuring your system network settings.
The failover feature on TrueNAS Enterprise platforms with High Availability (HA) can malfunction in network environments that heavily use the Spanning Tree Protocol (STP).
When configuring or troubleshooting HA failover, if TrueNAS HA failover does not function properly, investigate STP use in the network and consider disabling STP on network switch ports connected to the TrueNAS platform.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses either SMTP to send mail from TrueNAS to administrator or designated individual email addresses for system alert notifications.
Have your network administrators provide the SMTP addresses to allow TrueNAS to send emails from your network.
Directory Service Access
TrueNAS works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap.
Active Directory and LDAP configuration settings have similar requirements.
Additionally, consider implementing two-factor authentication (2FA) for enhanced security when authenticating users against Active Directory or LDAP directory servers.
Active Directory
Provide the following information to configure TrueNAS Active Directory access:
Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow TrueNAS to communicate with the server)
List of trusted domains TrueNAS should allow
LDAP
Provide the following information to configure TrueNAS LDAP access:
Host name where the LDAP sever is located and where TrueNAS accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for TrueNAS to use for authentication
Advanced Directory Services
When configuring Kerberos and/or IDmap, you might need to provide:
Kerberos realm and keytab information
IDmap schema information
Preparing for TrueNAS UI Configuration (Home Users)
Users installing and configuring TrueNAS on their home server should follow the instructions in this article to prepare for their deployment.
For support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from .iso file.
IPMI Access
Intelligent Platform Management Interface (IPMI) servers provide a way for system administrators to remotely access and control systems.
Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server.
Home users with compatible hardware have the option to use an IPMI connection to remotely administer their system over the Internet.
To make this remote access possible you need an IPMI capable system or service:
Assign an IP address to access to the controller in the TrueNAS system.
Set up your administrator credentials (user name and password) for access through the TrueNAS IPMI connections.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address.
You can use this DHCP-provided address, or you can assign a static IP address.
You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller.
Either allow DHCP to assign the IP address or assign a static IP.
Home users obtaining network equipment and Internet service access from either an Internet or cable service provider can contact the provider support departments for assistance with network addresses.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses SMTP to send mail from TrueNAS to either the administrator or designated individual email addresses for system alert notifications.
Contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
Consider utilizing two-factor authentication (2FA) for enhanced security when accessing SMTP servers for email delivery from TrueNAS.
Installing TrueNAS
After you download the .iso file, you can start installing TrueNAS!
This article describes verifying the .iso file, then installing TrueNAS using that file, and selecting the type of installation as either on physical hardware or a virtual machine (VM).
TrueNAS Enterprise
TrueNAS Enterprise customers should receive their systems already installed and ready for UI configuration. If any issues require you to install or re-install TrueNAS, contact TrueNAS Enterprise Support for assistance.
Enterprise customers with High Availability (HA) systems should not attempt to re-install their systems on their own. The dual controller install process is complicated and the risk of causing serious network issues is high. Contact TrueNAS Enterprise Support for assistance!
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
The iXsystems Security Team cryptographically signs TrueNAS .iso files so that users can verify the integrity of their downloaded files.
This section demonstrates how to verify an .iso file using the Pretty Good Privacy (PGP) and SHA256 methods.
Performing PGP ISO Verification
You need an OpenPGP encryption application for this method of ISO verification.
Click here for the verification process.
Obtain an OpenPGP encryption application to use.
There are many free applications available. The OpenPGP group provides a list of available software for different operating systems at https://www.openpgp.org/software/.
The examples in this section show verifying the TrueNAS .iso using gnupg2 in a command prompt, but Gpg4win is also a good option for Windows users.
To verify the .iso source, go to https://www.truenas.com/download-tn-scale/, expand the Security option,
and click PGP Signature to download the Gnu Privacy Guard signature file. This is a (.gpg) file.
Open the PGP Public key link and note the address in your browser and Search results for string.
Use one of the OpenPGP encryption tools mentioned above to import the public key and verify the PGP signature.
Go to the .iso and the .iso.gpg download location and import the public key using the keyserver address and search results string:
user@ubuntu /tmp> gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 0xc8d62def767c1db0dff4e6ec358eaa9112cf7946
gpg: key 358EAA9112CF7946: public key "IX SecTeam <security-officer@ixsystems.com>" imported
gpg: Total number processed: 1
gpg: imported: 1
user@ubuntu /tmp>
Use gpg --verify with the .iso.gpg signature file first and the .iso file second:
user@ubuntu /tmp> gpg --verify TrueNAS-SCALE-25.10.7.iso.gpg TrueNAS-SCALE-25.10.7.iso
gpg: Signature made Wed Sep 2 08:35:50 2026 EDT
gpg: using RSA key C8D62DEF767C1DB0DFF4E6EC358EAA9112CF7946
gpg: Good signature from "IX SecTeam <security-officer@ixsystems.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: C8D6 2DEF 767C 1DB0 DFF4 E6EC 358E AA91 12CF 7946
user@ubuntu /tmp>
This response means the signature is correct but still untrusted.
Go back to the browser page that has the PGP Public key.
Open and manually confirm that the key is issued for IX SecTeam <security-officer@ixsystems.com> (iX Security Team) on October 15, 2019, and is signed by an iXsystems account.
Using SHA256 Verification
SHA256 verification uses the checksum to validate/verify the file.
The SHA256 checksum file for each TrueNAS release is published alongside the .iso file on the TrueNAS Download page and in the TrueNAS software CDN.
Click here for the verification process.
The command to verify the checksum varies by operating system:
BSD: use command sha256 isofile
Linux: use command sha256sum isofile
Mac: use command shasum -a 256 isofile
Windows: in PowerShell, use command Get-FileHash -Algorithm SHA256 isofile. PowerShell shows the value in uppercase, and the comparison ignores case.
The value produced by running the command must match the value in the .iso.sha256 checksum file for your release.
Different checksum values indicate a corrupted installer file that you should not use.
Installing TrueNAS
You can install TrueNAS on either physical hardware or a virtual machine.
Installing on Physical Hardware
TrueNAS is flexible and can run on any x86_64 compatible (Intel or AMD) processor.
TrueNAS requires at least 8 GB of RAM (more is better).
TrueNAS recommends a boot device of 20 GB or larger. The installer requires a drive of at least 8 GB and does not list smaller drives.
Preparing the Install File
Physical hardware requires writing the TrueNAS installer to a removable device, typically a USB drive.
This device is temporarily attached to the system to install TrueNAS to the system permanent boot device.
Writing the TrueNAS installer to a USB drive on Linux
To write the TrueNAS installer to a USB drive on Linux, plug the USB drive into the system and open a terminal.
Start by making sure the USB drive connection path is correct.
There are many ways to do this in Linux, but a quick option is to enter the command lsblk -po +vendor,model and note the path to the USB drive.
This shows in the NAME column of the lsblk output.
Next, use the dd command to write the installer to the USB drive.
Be very careful when using dd, as choosing the wrong of= device path can result in irretrievable data loss!
Enter this command dd status=progress if=path/to/.iso of=path/to/USB in the CLI.
If this results in a permission denied error, use the command sudo dd with the same parameters and enter the administrator password.
You can also use a tool to create the install media:
Rufus for Windows
balenaEtcher for Windows, macOS, and Linux
Ventoy for Windows and Linux, to keep multiple ISO files on one USB drive
The following sections provide more information on a few of these options.
Using Ventoy
Ventoy is an open-source tool that prepares a USB drive once, after which you copy one or more iso files onto the drive like regular files.
At boot, Ventoy shows a menu of the iso files on the drive.
This is convenient when you install or update TrueNAS often, because you only copy the new iso to the drive and do not rewrite it.
Insert the USB drive. Ventoy erases all data on the drive when you install it.
Install Ventoy to the drive.
In Windows, run Ventoy2Disk.exe, select the USB drive in Device, and click Install.
To update Ventoy on a drive that already has it, click Update, which keeps the iso files on the drive.
In Linux, run sudo sh Ventoy2Disk.sh -i /dev/sdX, replacing /dev/sdX with the path to the USB drive.
Be very careful to specify the correct device path!
Copy the TrueNAS iso file to the large data partition on the USB drive.
Boot the system from the USB drive, select the TrueNAS iso in the Ventoy menu, and press Enter.
If the installer does not start in the default mode, restart and try the GRUB2 mode option shown after you select the iso.
Ventoy does not boot with Secure Boot enabled unless you enroll the Ventoy key.
Disable Secure Boot or set it to Other OS in the system firmware (BIOS/UEFI) settings. See Installing From the Device Media.
If Ventoy fails to install from Windows, security software or other programs that lock the drive are often the cause.
Close those programs and try again, or refer to the Ventoy documentation for alternative installation methods.
Using Rufus
Rufus is a free Windows program that creates a bootable USB drive from an iso file.
Rufus formats and erases all data on the USB drive. Move any files you want to keep off the drive first.
Insert a USB drive in a free USB port. Rufus normally detects the drive and shows it in Device.
If more than one drive shows, check that you select the correct one.
Click SELECT and choose the TrueNAS iso file to populate the Boot selection field.
Set Partition scheme to GPT for systems that boot in UEFI mode, or MBR for systems that boot in legacy BIOS mode.
Check the system firmware (BIOS/UEFI) settings for the boot mode.
Click START.
If Rufus asks whether to write in ISO Image mode or DD Image mode, select DD Image mode, which copies the image to the drive as it is, like the dd command.
Wait for Rufus to finish, then close it and remove the drive.
Writing the TrueNAS installer to a USB drive on macOS
To write the TrueNAS installer to a USB drive on macOS, plug the USB drive into the system and open a terminal.
Start by identifying the USB drive.
Enter diskutil list and note the identifier of the USB drive (for example, /dev/disk4).
The USB drive shows as (external, physical) and matches the size of the drive. Check the size carefully, because writing to the wrong disk erases it.
Unmount the stick with diskutil unmountDisk /dev/disk4, replacing disk4 with your identifier.
Be very careful when using dd, as choosing the wrong of= device path can result in irretrievable data loss!
Next, use the dd command to write the installer to the USB drive.
Enter sudo dd if=path/to/.iso of=/dev/rdisk4 bs=1m, replacing path/to/.iso with the path to the downloaded .iso file and rdisk4 with your identifier, then enter the administrator password.
The rdisk4 device path writes to the raw device, which is faster than disk4.
Press Ctrl+T to show progress while the command runs.
When the command finishes, macOS might show a message that the disk is not readable.
Click Eject, then remove the USB drive.
Using balenaEtcher
balenaEtcher is a free, open-source application for Windows, macOS, and Linux that writes an iso file to a USB drive.
Download and install balenaEtcher.
Insert a USB drive. Etcher erases all data on the drive, so move any files you want to keep first.
Click Flash from file and select the TrueNAS iso file.
Click Select target and choose the USB drive. Check the drive name and size, because Etcher erases the selected target.
Click Flash! and wait for the write and validation to finish.
Installing From the Device Media
Before you begin:
Locate the hotkey defined by the manufacturer of your motherboard to use in this process.
Disable Secure Boot, or set it to Other OS if your firmware offers that option, so you can boot the install media.
With the installer added to a USB drive, install TrueNAS onto the desired system using the TrueNAS installer.
Insert the install media and restart or boot the system.
At the motherboard splash screen, use the hotkey defined by your motherboard manufacturer to boot into the motherboard UEFI/BIOS.
Choose to boot the install media in UEFI mode or legacy CSM/BIOS mode.
For Intel chipsets manufactured in 2020 or later, UEFI is likely the only option.
If your system supports Secure Boot and you have not disabled it or set it to Other OS, do it now, so you can boot the install media.
Select the install media in the boot menu, exit, and restart the system.
If the USB drive is not shown as a boot option, try a different USB slot.
Slots available for boot differ by hardware.
Using the TrueNAS Installer
If you are doing a clean install from the TrueNAS .iso file as part of migrating from a different TrueNAS version, or to recover from a serious issue that requires you to re-install TrueNAS from the .iso, have your network configuration information ready to use after the installation completes.
Also have your TrueNAS system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered TrueNAS clean-install system.
After the system boots into the installer, follow these steps.
Select the drive to use as the boot device. Press the Spacebar to select a drive, and select more than one drive to mirror the boot device for redundancy.
The installer recommends SATA, SAS, or NVMe flash media and discourages USB flash drives.
Select how to authenticate to the web interface. Select Administrative user (truenas_admin) then OK to create the truenas_admin user account and password during installation.
Select Configure using Web UI to set up the administrator account the first time you open the web interface.
TrueNAS has implemented an administrator login as a replacement for the root user login as a security hardening measure.
The system retains root as a fallback, but it is no longer the default.
The truenas_admin account has full control over TrueNAS and is used to log in to the web interface.
Select the boot mode. If you booted the installer in legacy BIOS mode, a Legacy Boot prompt asks whether to allow EFI boot. Select Yes for systems with newer components such as NVMe devices, or select No if your system hardware requires the legacy BIOS boot workaround.
This prompt does not show when you booted the installer in UEFI mode.
Press Enter to begin the installation.
Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.
After following the installation steps, restart the system, and then remove the install media.
Troubleshooting
If the system does not boot into the TrueNAS installer or into TrueNAS after the installation, there are several things you can check to resolve the situation:
Confirm that Secure Boot is disabled or set to Other OS in the system firmware settings.
Try a different USB port, preferably a USB 2.0 port directly on the motherboard, and a different USB drive.
Check the boot menu for two entries for the same USB drive, one for UEFI and one for legacy BIOS. Try the other entry.
Make sure the firmware boots in the same mode (UEFI or legacy BIOS) for the installer and for the installed system. If the system installed in legacy BIOS mode fails to boot on later restarts, check the boot mode and the Legacy Boot answer you gave during installation.
Verify the .iso file using the ISO verification methods and write the media again if the checksum does not match.
Remove the install media after installation so the system boots from the TrueNAS boot device.
If a USB drive that previously held another image fails to boot after writing the installer, clean the drive before writing it again.
In Windows, open a command prompt as an administrator, run diskpart, then enter list disk, select disk <number>, and clean.
Be very careful to specify the correct disk when using clean, as it erases the selected disk!
Installing on a Virtual Machine
Because TrueNAS is built and provided as an .iso file, it works on all virtual machine solutions (Proxmox, VMware, VirtualBox, Hyper-V, etc).
The procedure is similar for most hypervisors.
Minimum Virtual Machine Settings
Regardless of the virtualization application, use these minimum settings:
RAM: at least 8192 MB (8 GB).
DISKS: two virtual disks, one of at least 20 GB for the operating system and boot environments, and at least one additional virtual disk for data storage.
Add more data disks to create the storage pool layout you want to use.
See Pool Creation for descriptions of the various pool (“vdev”) types and layouts.
NETWORK: Use bridged networking so the VM is reachable from your network. Other modes, such as NAT or host-only, limit access to the VM from your network.
Networking Checks for VMware
When installing TrueNAS in a VMware ESXi VM, double-check the virtual switch and port group.
A misconfigured virtual switch or port group can cause network connection errors for apps and virtual machines hosted inside the TrueNAS VM.
Set Promiscuous Mode, MAC Address Changes, and Forged Transmits to Accept on the virtual switch first, and then on the port group the VM uses.
If not using static IP addresses, configure your VM to use DHCP to assign IP addresses for seamless network connectivity.
Installing on a Generic Virtual Machine
Generic VM Installation Instructions
Create a new virtual machine as usual, taking note of the following:
Point a bootable CD/DVD device in the virtual hardware to the TrueNAS installer image (this is usually an .iso).
Configure the virtual network card to allow your network to reach it.
Bridged mode is optimal, as it treats the network card as if it is plugged into a simple switch on the existing network.
Identify the OS you plan to install on the VM. This is required by some products.
TrueNAS is based on Debian, so select the latest Debian 64-bit option your hypervisor offers.
If not available, try Other Linux 64-bit or Other 64-bit.
Use UEFI firmware if your hypervisor offers it.
If you use legacy BIOS firmware, answer the Legacy Boot prompt in the installer accordingly.
Disable Secure Boot for the VM.
Ensure the VM has sufficient memory and disk space as described in Minimum Virtual Machine Settings.
Not all hypervisors allocate enough memory by default.
Add the additional virtual disks for data storage.
Boot the VM and install TrueNAS as described below.
After the installation completes, shut down the VM instead of restarting, and disconnect the CD/DVD from the VM before starting the VM again.
After restarting into TrueNAS, install guest tools if applicable for your hypervisor, or ensure they load on boot.
Using the TrueNAS Installer
Just as with installing TrueNAS on physical hardware, complete the installation in the VM by booting into the TrueNAS installer.
Using the TrueNAS Installer in a Virtual Machine
Start the virtual machine.
The machine boots into the TrueNAS installer.
Select the drive to use as the boot device. Press the Spacebar to select a drive, and select more than one drive to mirror the boot device for redundancy.
The installer recommends SATA, SAS, or NVMe flash media and discourages USB flash drives.
Select how to authenticate to the web interface. Select Administrative user (truenas_admin) then OK to create the truenas_admin user account and password during installation.
Select Configure using Web UI to set up the administrator account the first time you open the web interface.
TrueNAS has implemented an administrator login as a replacement for the root user login as a security hardening measure.
The system retains root as a fallback, but it is no longer the default.
The truenas_admin account has full control over TrueNAS and is used to log in to the web interface.
Select the boot mode. If you booted the installer in legacy BIOS mode, a Legacy Boot prompt asks whether to allow EFI boot. Select Yes for systems with newer components such as NVMe devices, or select No if your system hardware requires the legacy BIOS boot workaround.
This prompt does not show when you booted the installer in UEFI mode.
Press Enter to begin the installation.
Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.
After the TrueNAS installation completes, restart the system.
The Console Setup menu displays when the system boots successfully.
Congratulations, TrueNAS is now installed!
The next step is to configure TrueNAS network and general settings.
Experienced users can use the Console Setup Menu to configure network settings, but if you are unfamiliar with the Console setup menu and how network configuration works, we recommend using the TrueNAS UI to configure settings.
TrueNAS uses DHCP to assign an IP address to the primary system interface and displays it at the top of the Console Setup menu screen. Use this IP address to log into the web UI.
Installing TrueNAS Enterprise (HA)
TrueNAS Enterprise
Installing TrueNAS on High Availability (HA) systems is complicated and should be guided by Enterprise-level support.
Contact TrueNAS Enterprise Support for assistance whenever attempting to install TrueNAS on Enterprise HA hardware.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Do NOT use Linux or CLI commands to recover or clean-install the TrueNAS iso file or configure any initial configuration settings!
Incorrect use of CLI commands can further disrupt your system access and can potentially do greater damage to your system. Proceed at your own risk.
Installing TrueNAS for an Enterprise (HA) System
This article outlines a procedure to do a clean install of a TrueNAS Enterprise High Availability (HA) systems using an iso file.
HA systems are dual controller systems with the primary controller referred to as controller 1 (sometimes also as controller A) and controller 2 (or controller B).
For best results, we recommend executing this procedure on both controllers at the same time.
You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off.
When controller 1 is completely configured, power on controller 2 to install TrueNAS and restart the controller.
When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
TrueNAS includes features and functions to help with completing the configuration process after installing and getting access to the TrueNAS web interface. This includes utilizing numerous high availability (HA) features to ensure data integrity and availability.
Have this information handy to complete this procedure:
All the assigned network addresses and host names (VIP, controller 1 and 2 IP addresses).
Other network information including domain name(s), and DNS server, default gateway, alias, or other static IP addresses.
The IPMI access addresses for each controller and the administration credentials for IPMI access to these addresses.
TrueNAS license file provided by iXsystems.
TrueNAS Storage Controller 1 (A) and 2 (B) serial numbers (refer to contracts or documentation provided with the system or contact TrueNAS Enterprise Support and provide your contract number).
HA system controllers each have serial numbers, the lower number assigned is for controller 1 (e.g. of two controller serial numbers assigned A1-12345 and A1-12346, the A1-12345 is for controller 1 and A1-12346 is for controller 2).
When restoring after a clean install, also have ready:
Storage data backups to import into the Enterprise HA system.
System configuration file from the previous TrueNAS install.
Overview of the Installation Procedure
For best results, we recommend executing this procedure on both controllers at the same time.
You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off.
When controller 1 is completely configured, power on controller 2 to install TrueNAS and restart the controller.
When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
There are two ways to install the HA dual controller system to ensure controller 1 comes online as the primary controller:
Install both controllers simultaneously beginning with controller 1, then immediately starting the install on controller 2.
Installing each controller individually to specific points in the installation process.
Simultaneous installation must start with controller 1, so it comes online first.
Installing each controller individually follows a particular method to ensure controller 1 comes online as the primary controller.
The sections in this article cover the primary steps as a simultaneous installation:
Download the iso file from the TrueNAS website and prepare the USB flash drives if not using IPMI for remote access.
Log into your IPMI system using the network address assigned to controller 1, and then establish a second connection with controller 2 in a new browser session.
Install TrueNAS using the iso file and select the Fresh Install option.
Install on controller 1, then immediately begin installing on controller 2 in the other IPMI session to simultaneously install TrueNAS on both controllers.
Disable DHCP, then enter the network settings to controller 1 using the Console Setup Menu.
Enter the IP address and netmask assigned to controller 1, then enter the global network settings for host name, domain name, and nameservers.
Use the TrueNAS UI for system configuration as it has safety mechanisms in place to prevent disrupting network access that could require you to repeat the clean install to access your system.
However, if you are experienced with the Console Setup Menu and are using it to configure network settings you can configure the rest of the controller 1 network settings with the Console setup menu.
Log into the TrueNAS UI for controller 1 to sign the EULA agreement and apply the system HA license.
Disable failover to configure the rest of the network settings and edit the primary network interface on controller 1, and then enable failover.
Complete the minimum storage requirement by adding or importing one pool on controller 1.
Sign in using the Virtual IP (VIP) address.
With controller 2 powered up, on controller 1 sync to peer to complete the install and make controller 2 the standby controller.
The sections that follow describe these steps in detail.
Overview of the Alternative Installation Process
This process of installing each controller sequentially has two methods:
Install and configure controller 1 up to the point where you are ready to sync to controller 2.
When complete, install controller 2 and restart. After the console setup menu displays, switch back to controller 1 and sync to peer.
This synchronizes the completed configuration from controller 1 to controller 2 and keeps controller 1 designated as the primary controller.
Or
Begin installing controller 2 immediately after installing controller 1. When controller 2 finishes installing, power it off and keep it powered down.
When finished configuring controller 1, power up controller 2 and wait for it to finish booting up. Switch back to controller 1 and sync the configuration to controller 2.
This section provides an overview of the alternative method to clean install an HA system with controller 2 powered off while installing and configuring controller 1.
These steps are nearly identical to the section above but controller 2 is either powered off or not installed while you install and configure controller 1.
Use either the prepared USB flash drive inserted into a USB port for controller 1 or log into an IPMI session and install TrueNAS on controller 1.
Finish the installation and allow controller 1 to complete its first boot.
Use either the prepared USB flash drives inserted into a USB port for controller 2 or log into an IPMI session for controller 2 to install TrueNAS.
When the installation finishes, power down controller 2.
Configure the required network settings on controller 1 with the Console setup menu.
Log into controller 1 using the IP address assigned to controller 1.
Apply the HA license, sign the EULA, and complete the UI configuration to the point where you are ready to sync to peer on controller 1, but do not sync yet.
Power up controller 2 and wait for it to complete the boot process.
Log into controller 1, go to System > Failover, and click Sync to Peer.
This synchronizes controller 2 with controller 1 and restarts controller 2. Controller 2 becomes the standby controller when it finishes restarting.
If you are remote to the system and are installing through an IPMI connection you do not need to save the .iso file to a USB flash drive.
If you are physically present with the TrueNAS system, burn the .iso file to a USB flash drive and use that as the install media.
Using IPMI to Install the ISO on a Controller
Use this process to install the iso file on both controller 1 and controller 2. Best practice is to begin the install on controller 1, then immediately begin the install on controller 2.
Installing ISO Steps
Enter the IP address assigned to the controller 1 IPMI port into a web browser and log into your IPMI system with admin credentials.
Select Remote Control > iKVM/HTML5 to open the Console Setup window.
IPMI interfaces can vary but they generally have options for Remote Control and iKVM/HTML5 to open a console session on the platform.
Install the .iso file. Select the Virtual Media > CD-ROM image option in your IPMI system.
a. Enter the IP address of where you downloaded the .iso file into Share Host.
You might need assistance from your Network or IT department to obtain this address.
b. Enter the path to the .iso file.
For example, if you stored the file in an iso folder enter /iso/TrueNAS-SCALE-22.12.1.iso in Path to Image.
c. Click Save, then Mount. You should see the .iso file under Device 1 or the device name your IPMI configures.
Return to the Remote Control > iKVM/HTML5 window opened in step 2. Either use your keyboard or open the keyboard in the window then:
a. Type 8 to restart controller 1 (also repeat for controller 2), and type y to confirm and restart.
b. As the system restarts, be prepared to hit the F11 key when you first see the TrueNAS Open Storage splash screen.
Alternatively, you can start clicking on the F11 key on the online keyboard until you see the TrueNAS Installer screen.
c. Select the UEFI: ATEN Virtual CDROM device from the boot list. The bootstrap loader begins. When it ends the TrueNAS installer opens.
Using the TrueNAS Installer
If you are doing a clean install from the TrueNAS .iso file to recover from an issue that requires you to re-install TrueNAS from the .iso, have your network configuration information ready to use for controller 1 after the installation completes. Do not configure network settings on controller 2.
Also have your TrueNAS system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered TrueNAS clean-install system.
Select the drive to use as the boot device. Press the Spacebar to select a drive, and select more than one drive to mirror the boot device for redundancy.
The installer recommends SATA, SAS, or NVMe flash media and discourages USB flash drives.
Select how to authenticate to the web interface. Select Administrative user (truenas_admin) then OK to create the truenas_admin user account and password during installation.
Select Configure using Web UI to set up the administrator account the first time you open the web interface.
TrueNAS has implemented an administrator login as a replacement for the root user login as a security hardening measure.
The system retains root as a fallback, but it is no longer the default.
The truenas_admin account has full control over TrueNAS and is used to log in to the web interface.
Select the boot mode. If you booted the installer in legacy BIOS mode, a Legacy Boot prompt asks whether to allow EFI boot. Select Yes for systems with newer components such as NVMe devices, or select No if your system hardware requires the legacy BIOS boot workaround.
This prompt does not show when you booted the installer in UEFI mode.
Press Enter to begin the installation.
Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.
Select OK after the The TrueNAS installation on succeeded displays. The Console setup menu screen displays.
Enter 3 to Reboot System and immediately return to the IPMI Virtual Media > CD-ROM image screen to click Unmount. Click Save.
If you fail to unmount the iso image before the system completes the restart, the bootstrap install continues in a boot loop.
After installing the .iso file on both controller 1 and 2 and finishing the TrueNAS Installer process, use the Console setup menu to configure the required network settings on controller 1, so it can access the TrueNAS UI.
TrueNAS single controller systems use the DHCP-assigned IP address for the primary network interface to access the UI to complete the rest of the network and other configuration settings.
However, HA systems with dual controllers must use static IP addresses.
To allow controller 1 to access the UI, you must disable DHCP and add the controller 1 static IP address and netmask as an alias on the primary network interface, and then enter the network settings for host name, domain name, default gateway, and the name servers (1 and 2).
You can configure the rest of the HA global network settings in the TrueNAS web UI.
To use the Console setup menu to configure required network settings on controller 1:
Use either Tab or the arrow keys to select the interface assigned as your primary network interface.
If you have more than one interface installed and wired to your network, the primary interface is typically eno1.
With the interface highlighted, press Enter to open the Update Network Interface screen.
Tab or arrow down to ipv4_dhcp and change it to no.
Tab or arrow down to the aliases setting and enter the static IP address for controller 1.
Tab or arrow down to Save, and then press Enter. A pending network changes notice displays with additional options.
Type a to apply the change, then p to make it persist.
Type q to return to the main Console setup menu.
Type 2 and then press Enter to open the Network Configuration screen.
TrueNAS UI Enterprise customers see the End User License Agreement (EULA) screen the first time they log in.
Sign the agreement to open the main TrueNAS Dashboard.
Apply the system license next.
Go to System > General Settings and click Add License on the Support widget. Copy your license and paste it into the License field, then click Save License.
The Reload dialog opens. Click Reload Now. Controller 1 restarts, and displays the EULA for controller 2. Sign the EULA agreement for controller 2, and add the license.
The controller 1 and 2 (or a and b) serial numbers display on the Support widget on the System > General Settings screen.
Configuring Network Settings
Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready, click Sync to Peer to haveTrueNAS apply settings to controller 2.
TrueNAS Enterprise (HA) systems use three static IP addresses for access to the UI:
VIP to provide UI access regardless of which controller is active.
If your system fails over from controller 1 to 2, then fails back over to controller 1 later you might not know which controller is active.
IP for controller 1. Do not use DHCP to assign the IP address! If enabled, DHCP assigns an IP to the primary network interface on non-HA systems.
Disable DHCP, and then manually enter the Controller 1 static IP address your network administrator assigned for this controller.
IP for Controller 2. Manually enter the second IP address assigned for this controller.
Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.
TrueNAS safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes.
This is to prevent users from breaking their network connection in TrueNAS.
TrueNAS Enterprise
TrueNAS Support strongly discourages using the FAILOVER protocol setting when configuring Link Aggregation (bond) interfaces in HA systems.
Using this setting in HA systems might delay moving the virtual IP address from one controller to the other during a failover, causing network access delays.
Additionally, TrueNAS does not allow marking a bond interface in HA systems as Critical when the FAILOVER protocol is used but it is allowed in non-HA systems.
To configure network settings on controller 1:
Disable the failover service.
Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to clear the checkmark, then select Default TruNAS Controller to enable it, and then click Save to disable failover.
Go to System > Network and click Settings to edit the global network settings.
Add the controller and virtual host names and update any other network settings.
Edit the primary network interface to add failover settings.
Click on the more_vert to the right of the the primary interface eno1, and select Edit to open the Edit Interface screen for this interface.
a. Turn DHCP off if it is on by selecting Define Static Ip Addresses. Click Add to show IP address fields for each interface.
Enter the IP address assigned to controller 1 in IP Address (TrueNAS Controller 1), the IP address assigned to controller 2 in IP Address (This Controller), and the IP address assigned as the virtual IP in Virtual IP Address (Failover Address).
If Define Static IP Addresses is already selected, verify the three static IP addresses assigned to the system show in the correct fields.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
b. Add the failover settings. Select 1 on the Failover Group dropdown list.
Click Test Changes after editing the interface settings. Open a new browser window and enter the VIP IP address to access the web UI.
Go to System > Network and click Save Changes to make the changes permanent.
You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Enable failover. Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to re-enable failover, then click save.
Create or import a storage pool from a backup. You must have at least one storage pool on controller 1.
After saving the storage pool, controller 2 automatically restarts. Wait until it comes back online before syncing controller 1 with controller 2.
For more information on how to create a new pool click here.
For more information on how to import a pool click here.
Syncing Controller 1 and 2
Turn the failover service back on. Go to System > Services locate the Failover service and click edit.
Select Disable Failover to clear the checkmark and turn failover back on, then click Save.
The system might restart. Use IPMI to monitor the status of controller 2 and wait until the controller is back up and running.
Log out of the controller 1 UI, and log in using the VIP address.
Sync controller 1 and 2.
With controller 2 powered on, but not configured, from controller 1 click Sync To Peer.
Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation.
This sync controller 2 with controller 1 which adds the network settings and pool to controller 2.
When the system comes back up, log into TrueNAS using the virtual IP address.
The main Dashboard displays two System Information widgets. In standard configurations by iXsystems, Controller 1 shows its serial number and a host name that includes the letter a. Controller 2 is labeled as Standby Controller and shows its serial number and a host name that includes the letter b.
Take note of this information.
The failover feature on TrueNAS Enterprise platforms with High Availability (HA) can malfunction in network environments that heavily use the Spanning Tree Protocol (STP).
When configuring or troubleshooting HA failover, if TrueNAS HA failover does not function properly, investigate STP use in the network and consider disabling STP on network switch ports connected to the TrueNAS platform.
If controller 2 comes online as the primary and controller 1 as the standby, you installed and configured the controllers incorrectly.
Go to System > Failover, clear the Default TrueNAS Controller option, and click Save. The system restarts and fails over to the current standby controller (in this case, to controller 1).
Log back into the UI with the VIP address. Go to System > Failover and select Default TrueNAS Controller to make controller 1 the primary controller.
Select Sync to Peer. TrueNAS makes controller 2 the standby controller and syncs the configuration on controller 1 to controller
Click Save.
Using the Console Setup Menu
The Console Setup menu displays at the end of the iso installation process and after the system boots up.
You can access this menu to administer the TrueNAS system if it has a keyboard and monitor.
By default, TrueNAS does not display the Console Setup menu with SSH or web shell connections.
The admin user, the root user (if enabled), or another user with administrator or root-level permissions can start the Console Setup menu by entering this command:
For network configuration options 1, 2, and 3, we recommend using the TrueNAS UI to configure network interfaces, as it has safeguards to prevent breaking network access to TrueNAS.
1) Configure network interfaces
Use this to configure the primary network interface with a static IP.
This is for switching away from the DHCP-assigned IP address TrueNAS provides when the system boots after installing TrueNAS.
Also, use this to set up other network interfaces or to add alias IP addresses, also referred to as static IP addresses, for the primary interface.
2) Configure network settings
Use this to set up the network default gateway, host name, domain, IPv4 gateway and DNS name servers.
Configured options display in the Global Configuration widget in the web UI Network screen.
3) Configure static routes
Use this to set up static IP routes, but this is not required as part of the initial configuration setup.
4) Change local administrator password
Use to change the administrator user password.
If you selected option 1 on the iso installer menu, you have already configured the truenas_admin user and password.
You can use this to change the admin password before you log into the TrueNAS UI. Note that TrueNAS begins warning all local account types (administrator, full admin, read-only, and sharing-only) seven days before password expiration. After expiration, the account locks and requires administrative action to unlock.
This is not the password for the root user in the CLI or the root user login password for the web UI.
The root user password is disabled by default as part of security hardening.
Activating the root user is not recommended.
5) Create one-time password for “root”
Use to create a one-time password for the root user.
This is intended for quick authentication to the web interface to further set up secure log ins.
Once you generate a one-time password, it remains valid for one login within 24 hours and does not persist
across reboots.
You must set a new password after you log in.
6) Reset configuration to defaults
Use to wipe all system configuration settings and return the system to a fresh install state.
7) Open TrueNAS CLI Shell
Use to start a shell for running TrueNAS commands, or use the TrueNAS UI System Settings > Shell.
Type exit to leave the shell.
8) Open Linux Shell
Use to start a shell window for running Linux CLI commands.
Configuration changes made do not write to the database and reset on each system boot.
We do not recommend using the Linux shell unless you are an advanced user. Type exit to leave the shell.
9) Reboot
Restart the system by powering down and then automatically powering on the system.
10) Shut down
Use to power down the system.
During the first boot, TrueNAS attempts to connect to a DHCP server from all live interfaces.
If it receives an IP address, the Console Setup menu displays it under The web user interface is at: so you can access the TrueNAS web UI.
You might be able to access the web UI using a hostname.domain command at the prompt (default is truenas.local) if your system:
Does not have a monitor.
Is on a network that supports Multicast DNS (mDNS).
Console Setup Menu Network Settings
You can either use TrueNAS UI or the Console Setup menu to configure your network settings for the primary network interface or other interfaces such as a link aggregate (LAGG) or virtual LAN (VLAN), or aliases for an interface, and to configure other network settings such as the default gateway, host name, domain, and the DNS name servers, or add static routes.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the TrueNAS UI to configure your network interfaces and other network configuration settings.
The TrueNAS UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS if you make a mistake with network interface settings.
Enter 1 to display the Configure Network Interfaces screen and select the interface settings.
Follow the instructions on the screen to configure an IP for a network interface.
Type n to open the new interface screen or press Enter to edit the existing interface.
You can enter aliases for an interface when you create a new one or edit an existing interface.
Type q to return to the main Console Setup menu screen.
Enter 2 to display the Network Settings screen to set up the host name, domain, default gateway and name servers. You can also add these settings using the web UI.
TrueNAS uses DHCP to assign the IP address required to access the TrueNAS UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by TrueNAS, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure TrueNAS.
To use the Console Setup menu to change the network interface IP address:
Type 1 and then press Enter to open the Configure Network Interfaces screen.
Use either Tab or the arrow keys to select the interface to use as your primary network interface if you have more than one interface installed and wired to your network.
Enter in the IP address, then use either Tab or the arrow keys to move through the menu and down to select Save, and then press Enter.
After saving, enter q to return to the main Console Setup menu.
To configure the default gateway, host name, domain and DNS name severs using the Console Setup menu type 2 and then press Enter to open the Network Settings screen.
To configure network settings in the TrueNAS UI, enter the IP address displayed on the Console Setup menu screen in a browser URL field and press Enter.
Log in with the admin user name and password set for the administration user during the iso installation process, and then go to Network to edit an interface or global network configuration settings.
Configuring Home User Network Settings
Home users have a few options to allow Internet access using TrueNAS:
Use 8.8.8.8 as the DNS nameserver address
Use your ISP provider DNS servers (contact them for assistance with these addresses)
TrueNAS has implemented administrator account logins as replacements for the root user.
The truenas_admin user account is the default account, and the root password is now disabled by default.
If you migrate from FreeBSD- to Linux-based TrueNAS releases and need to upload the previous system configuration file, the root user password is not disabled but you must recreate the truenas_admin (or an admin) user account and disable the root password to comply with FIPS-compliance standards and security hardening practices.
Existing TrueNAS systems migrating from earlier TrueNAS release with the admin user retain this administrator account.
Only a clean install using a TrueNAS 24.10 iso creates the truenas_admin administrator account.
Both the earlier admin and new truenas_admin accounts have the same permissions and privileges.
You can change the admin user password in the UI or from the Console Setup menu.
You can set and enable the root user password in the UI, but for security hardening, we recommend leaving it disabled.
Changing an admin user (or root if you have not created the admin user) password disables 2FA (Two-Factor Authentication).
Disabling a password in the UI prevents the user from logging in with it.
If both the root and local admin user passwords are disabled and the web interface session times out with these passwords disabled, TrueNAS provides a temporary sign-in screen to allow logging into the UI.
Immediately go to the Credentials > Local User screen, select the admin user, click Edit and re-enable the password.
Resetting the System Configuration
Caution!
Resetting the configuration deletes all settings and reverts TrueNAS to default settings.
Before resetting the system, back up all data and encryption keys/passphrases!
After the system resets and restarts, you can go to Storage and click Import Pool to re-import pools.
Enter 5 in the Console Setup menu, then enter y to reset the system configuration. The system restarts and reverts to default settings.
Completing your System Setup
After setting up network requirements, log into the web UI to complete your system setup by:
[Completing network configuration] (/scaletutorials/network/) if not already set up using the Console Setup menu.
On March 20, 2024, the TrueNAS team announced that the FreeBSD-based TrueNAS CORE platform has entered “sustaining engineering phase within the TrueNAS project.”
With this transition, TrueNAS 13.0 continues to receive bug fixes related to stability and security.
New feature development and component improvement continues on Linux-based TrueNAS versions.
TrueNAS 13.3-U1.2, released April 29, 2025, is the final release for the TrueNAS CORE 13.3 software train.
We encourage TrueNAS 13.3 users to explore our newest TrueNAS Community Edition (25.04 or later) solutions.
If any security or data integrity issues do arise in 13,3-U1.2, we will notify the Community of these.
The expected resolution will be in the TrueNAS Community Edition.
Users looking for new feature development can sidegrade to the Linux-based TrueNAS platform at any time, preserving data and essential NAS functionality.
TrueNAS users wanting to migrate from the latest FreeBSD-based 13.0 or 13.3 CORE release to the Linux-based TrueNAS version 24.10 or later can migrate to 24.04 and earlier using the UI update process, but must clean install if migrating to later releases.
Attempting to migrate directly to 24.10 or later using the UI is not supported.
TrueNAS community users can download a copy of the iso for the latest maintenance release of the target major version, then follow the migration instructions in Performing a Clean Install or use the UI update screen or download a manual update file then follow the instructions in Updating to 24.04 to move from the FreeBSD-based to the Linux-based version of TrueNAS.
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.
Contents
Preparing to Migrate: Guides FreeBSD-based TrueNAS users through preparation elements and steps before beginning the one-way FreeBSD- to Linux-based TrueNAS migration process.
Community Migrations: Provides instructions for TrueNAS community users to migrate from FreeBSD- to Linux-based TrueNAS versions. Migration methods include using an ISO or manual update file.
Enterprise Migrations: Instructions for TrueNAS Enterprise users to migrate from FreeBSD- to Linux-based TrueNAS software.
Component Naming: Provides information on disk and interface naming changes related to the change from FreeBSD to Linux-based storage and sharing in TrueNAS.
(obsolete) ZFS Feature Flags Removed: (obsolete) Provides legacy information for users of a deprecated ZFS feature flag merged into TrueNAS 22.02 and removed in 22.12.
Preparing to Migrate
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 release version, 13.0-U6.7 (or 13.3-U1.2 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.
TrueNAS users wanting to migrate from the latest FreeBSD-based 13.0 or 13.3 CORE release to the Linux-based TrueNAS version 24.10 or later can migrate to 24.04 and earlier using the UI update process, but must clean install if migrating to later releases.
Attempting to migrate directly to 24.10 or later using the UI is not supported.
TrueNAS community users can download a copy of the iso for the latest maintenance release of the target major version, then follow the migration instructions in Performing a Clean Install or use the UI update screen or download a manual update file then follow the instructions in Updating to 24.04 to move from the FreeBSD-based to the Linux-based version of TrueNAS.
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.
What can or cannot migrate?
Although TrueNAS attempts to keep most of your configuration data when migrating, some items do not transfer.
These are the items that do not migrate:
Microsoft OneDrive Cloud Sync credentials and tasks. OneDrive compatibility is not available in TrueNAS.
FreeBSD GELI encryption.
If you have GELI-encrypted pools on your system that you plan to import, you must migrate your data from the GELI pool to a non-GELI encrypted dataset or zvol before migrating.
Malformed certificates.
TrueNAS validates the system certificates when a system migrates.
When a malformed certificate is found, TrueNAS generates a new self-signed certificate to ensure system accessibility.
Plugins and jails.
Save the configuration information for your plugin and back up any stored data.
After migrating, add the equivalent application using the Apps option.
If your plugin is not listed as an available application, use the Custom App option to add it and import data from the backup into a new dataset for the application.
NIS data.
System tunables.
ZFS boot environments.
SMB auxiliary parameters.
As of TrueNAS 23.10 (Cobia), the Auxiliary Parameters option is no longer available in the UI as a configurable option.
We recommend removing any auxiliary parameter settings before migrating.
AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
netcli utility.
A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI.
By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.
SAS multipath is not supported.
TrueNAS 13 account names beginning with a number are not supported in TrueNAS 24.04.
Usernames must begin with a letter or an underscore.
Before attempting migration, review the local user accounts and rename or replace any accounts that begin with a numeric character (0-9).
TrueNAS 13.X and earlier support VMs with UEFI and GRUB bootloaders.
TrueNAS 22.02 and later does not support the GRUB bootloader.
VMs configured with the UEFI bootloader can migrate.
VMs configured with the GRUB bootloader are unable to migrate.
It is important for all users to double-check the VM configuration and network interface settings before starting the VM.
If VMs need to access local NAS storage, you need to create a network bridge and assign it to the VM.
Applications or sandboxes that need access to local storage within the container must use a bridge or mount a local storage location as a host path for the application.
Init/shutdown scripts transfer, but can break. Review them before use.
Preparing for Migration
Read this article before you attempt to migrate your FreeBSD-based system to a Linux-based TrueNAS version.
We strongly recommend not using USB flash drives or USB-attached drives for backups, as these can have issues, including with recovering backed-up files.
For more information on using USB drives and devices in general, read the Hardware Guide.
If you must use a USB-type device, verify you can access files on the device before you migrate.
TrueNAS Enterprise
We strongly encourage Enterprise customers to contact Support for assistance moving from a FreeBSD-based (13.3 or earlier) to a Linux-based (22.12 or newer) TrueNAS version, especially customers with HA systems using iSCSI shares or fibre channel. Enterprise customers should not attempt to migrate their HA systems with iSCSI or fibre channel on their own!
Enterprise systems with iSCSI and fibre channel deployments require complex, special preparation and migration steps executed before and after migration to ensure data integrity.
Please contact Support for assistance!
Upgrade your system to either the latest 13.0 or 13.3 release.
TrueNAS Enterprise-licensed (or community systems that haven’t switched to 13.3) systems on 12.0x or earlier should upgrade to the latest 13.0 release before migration.
Community users with 13.3 installed should update to the latest maintenance release of that version before migration.
Either major version can use the iso upgrade method for migration.
Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from TrueNAS 12.0x or earlier releases!
If you do not migrate from GELI to ZFS encryption before upgrading to 13.0-U6.2 (or newer) or migrating to TrueNAS 24.04 (or newer), you permanently lose access to the data in the GELI-encrypted pool(s).
Verify the root user is not locked.
Go to Accounts > Users, select the root user, and click Edit to view current settings and confirm Lock User is not selected.
Write down, copy, or take screenshots of settings to duplicate after migrating or use in the event of a post-upgrade/migration issue.
Use the checklist below to guide you through this step:
System dataset - Identify your system dataset. If you want to use the same dataset for the system dataset after migrating, note the pool and system dataset.
When you set up the first required pool after migrating, import this pool first.
VMs - If you have virtual machines configured, write down or screenshot the network, bootloader, and other setting information.
Plugins or jails - Plugins and jails do not migrate. Record settings for each plugin/jail and back up the data associated with each.
CAs, certificates, CSRs - If you added certificate authorities, certificates, or certificate signing requests, they should migrate with the system config file, but as a precaution against possible malformed certificates, copy private and public certificate keys and save each, then copy or screenshot all CA, certificate, and CSR settings. Make sure you have backup copies of certificates used to import or configure after migrating.
Usernames beginning with (0-9) - Review local user account names and rename or replace these with a letter or underscore before migrating.
User-created accounts with UID or GID less than 1000 - The UID/GID range below 1000 is reserved for built-in system accounts. User-created accounts in this ID range can cause conflicts and undefined behavior after migration, including duplicate accounts with the same ID. Recreate any non-builtin accounts in this range to assign an ID of 1000 or higher, then delete the previous account and reconfigure ACLs as needed before migrating.
Tunables - Linux-based TrueNAS (22.12 or newer) does not use Tunables in the same way. Copy script configurations to add on the System > Advanced Settings screen, using the Sysctl widget, after migrating.
Init/shutdown scripts - If using init/shutdown scripts, copy them or take a screenshot to add them after migrating.
Cron jobs - If configured, copy or use screenshots of cron job scripts if you want to add the same jobs after migrating.
Global self-encrypting drive (SED) Password - Unlock these drives before migrating. Write down the SED password to use after migrating.
Credentials - Copy or write down the credentials for SSH connections and keypairs, and any configured cloud service backup providers if you do not have the credential settings saved in other files kept secured outside of TrueNAS.
Data protection tasks - Write down or take screenshots of replication, rsync tasks, periodic snapshots, cloud sync, or other task settings to reconfigure these after migrating.
SNMP v3 service settings - Write down or take a screenshot of the SNMP service V3 settings to use after migrating.
TrueNAS uses SSH connections in data protection tasks, so data protection tasks (especially replication tasks) might require reconfiguration in some cases.
After migrating to 25.10, SSH connections have failed with an authentication error in some cases.
There is no way to update the SSH connection manually, and creating a manual SSH connection might result in an authentication error.
When this occurs, you must set up a new replication task and a new SSH connection between systems on the migrated system (in 25.10).
After migrating and the system is online, check replication and data protection tasks that rely on SSH connections to verify they work as expected.
If you receive an authentication error, use the notes from the CORE system to reconfigure these tasks and the SSH connection between systems.
Community users with iSCSI deployments can migrate their systems without assistance. Note, unlike FreeBSD systems, Linux Debian systems require at least one LUN set to zero.
iSCSI portals in Linux Debian-based systems are defined globally instead of per port.
Enterprise systems with iSCSI shares and/or fibre channel deployments have special requirements, preparation, and migration steps to ensure data integrity and a smooth migration.
Other iSCSI differences only apply to Enterprise High Availability (HA) systems and those with Fibre Channel ports. Enterprise users must contact TrueNAS Customer Support for assistance with their migrations!
Remove all SMB auxiliary parameter settings before migrating.
In TrueNAS 23.10 (Cobia) or newer, the SMB Auxiliary Parameters option is unavailable in the UI.
Attempting to migrate with these settings can result in broken SMB shares post-upgrade that require CLI access to fix.
Write down or take screenshots of your network configuration information.
Capture the global network settings, interfaces (LAGG, VLAN, bridge settings), static IP addresses, and aliases.
FreeBSD and Linux use different nomenclature for network interfaces, bridges, LAGGs, and VLANs.
Because of the difference, network settings can either get lost or not transfer, which means you have no network connectivity.
See Component Naming for more information.
When using a TrueNAS Enterprise system from iXsystems, refer to the network port ID manuals of your TrueNAS Systems to find the network port assignments in TrueNAS.
When using custom hardware for TrueNAS, refer to the manual or documentation provided with your system or locate this information on your server hardware and take note of it.
If there are issues after a clean install from an iso file, or if you are not using DHCP for network and interface configuration, use the recorded information from your previous settings to configure your network settings and reconfigure your static IPs or aliases after migrating.
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address.
You can use this DHCP-provided address, or you can assign a static IP address.
You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller.
Either allow DHCP to assign the IP address or assign a static IP.
Offline the deprecated S3 MinIO™ service (if in use).
This might require a manual data backup and restore strategy.
Enterprise customers can contact iX Support to discuss migration and backup strategies.
Back up any critical data.
Verify AD is in a healthy state, if TrueNAS is joined to AD. Migrating with AD healthy and joined should not result in desynchronization issues.
The stored secret should move forward to the upgraded release without issues.
Download your system configuration file and a debug file.
After updating to the latest publicly available release of TrueNAS 13.0 (or 13.3 for community users) and making any changes to user accounts or any other settings, download these files and keep them in a safe place and where you can access them if you need to revert with a clean install using the TrueNAS 13.0 or 13.3 iso file.
TrueNAS Enterprise
Enterprise customers using iSCSI with ALUA or fibre channel ports should contact Support for assistance with migrating their systems.
These features require careful configuration to avoid data corruption or loss of data.
After completing the steps listed above that apply to your existing system, download the latest TrueNAS ISO file and save it to your computer.
See Software Releases for currently recommended update paths to make sure you download and migrate to and from the correct TrueNAS versions.
Burn the iso to a USB drive (see Installing on Physical Hardware) when upgrading a physical system.
Deprecated Services
The built-in services listed in this section are available in 13.0 but deprecated in 22.12.3 (Bluefin) and removed in later TrueNAS releases.
They require attention before attempting to migrate to 24.04 or later.
Each of the sections has information that can help you determine the best steps forward to secure any critical data before attempting to migrate.
They provide details on transitioning from that service to an application with the functionality of the deprecated service.
TrueNAS has apps you can deploy as replacements for these services.
TrueNAS provides the option to force an upgrade without converting deprecated services to apps.
The force option is not recommended for the S3 service as forcing the upgrade results in losing access to and the ability to recover the MinIO S3 data.
Review and write down or take screenshots of your Dynamic DNS service provider, domain, IP address, port number, URL, and credential (username and password) settings to use when you reconfigure in a replacement app.
If establishing a new provider, create the user account before proceeding. Otherwise, use the existing provider details.
To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user.
Note the UID and GID for this new user to enter in the application configuration screen.
Install a replacement application, such as DDNS-Updater, using the service settings from your notes.
Migrating from OpenVPN Service
Review your OpenVPN client and server service settings.
Take note of all certificates, device type, port, protocol, TLS crypt authentication, and additional parameter settings to use in a replacement app.
A configured certificate should migrate, but as a precaution, record the certificate authority (CA) and certificate settings, and make a copy of the private and public keys the CA and certificate uses.
Install a replacement application, such as WG Easy, using the service settings from your notes.
Migrating from Rsync Service
Review your rsync and module service settings.
Take note of all host path, access mode type, number of simultaneous connections, user and group IDs, allow and deny host addresses, and any auxiliary parameter settings.
Before you configure a new rsync application like Rsyncd, validate that it is needed.
When rsync is configured externally with SSH or using an rsync task in Data Protection > Rsync Tasks, and when Rsync Mode is set to SSH, the deprecated rsync service is not used or necessary for rsync to function.
Install a replacement application such as Rsync Daemon using the 13.0 service settings from your notes.
TrueNAS 24.10 suggests other applications to consider other than the Rsync Daemon application.
Migrating from TFTP Service
Review your TFTP service settings.
Take note of all directory, host, auxiliary parameter, permission, and credential (username and password) settings.
To grant access to a specific user (and group) other than using the default admin user UID and GID, add the new non-root administrative user.
Note the UID and GID for this new user to enter in the application configuration screen.
To use a specific dataset or storage volume for files, create a new dataset before installing the application.
Install the replacement application, such as TFTP Server (TFTP-HPA), using the service settings from your notes.
Migrating from WebDAV Service and Shares
Disable both the WebDAV share and service.
Also, disable the Start Automatically option to prevent the service from re-enabling after a system restart.
Review any existing WebDAV service authentication settings.
Take note of all IP addresses, port numbers, URLs, and credentials (username and password).
Remove any existing WebDAV shares. Go to Shares > WebDAV and use Edit to view any existing configurations.
Take note of the share name, path, and read-only settings. Delete the WebDAV share configuration.
In Bluefin:
To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user for the share(s).
Note the UID and GID for this new user to enter in the application configuration screen.
After disabling the WebDAV service and clearing any existing share configurations from the Shares > WebDAV screen in Bluefin, install the WebDAV application to recreate your shares using the service settings from your notes. Use the webdav user and group in control, and the UID and GID (666) in the application.
MinIO is a trademark of the MinIO Corporation.
Community Migrations
Migration Overview
This article provides information and instructions for migrating non-Enterprise FreeBSD-based TrueNAS versions (13.0 or 13.3) to Linux-based TrueNAS (22.12 and later).
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 process requires an extended maintenance window, requires executing steps in the correct order to prevent issues with system configuration and operation, and additional system review post-migration to catch and correct any configuration issues.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Review the Migration Preparation article for detailed recommendations and preparation steps before attempting to migrate.
Depending on system configuration, migrating can be more or less complicated.
If your FreeBSD based system is joined to Active Directory, leave AD before migrating to a Debian-based release to avoid desynchronization issues that can result between release types.
Migration Methods
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 release version, 13.0-U6.7 (or 13.3-U1.2 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.
TrueNAS users wanting to migrate from the latest FreeBSD-based 13.0 or 13.3 CORE release to the Linux-based TrueNAS version 24.10 or later can migrate to 24.04 and earlier using the UI update process, but must clean install if migrating to later releases.
Attempting to migrate directly to 24.10 or later using the UI is not supported.
TrueNAS community users can download a copy of the iso for the latest maintenance release of the target major version, then follow the migration instructions in Performing a Clean Install or use the UI update screen or download a manual update file then follow the instructions in Updating to 24.04 to move from the FreeBSD-based to the Linux-based version of TrueNAS.
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.
For all migration methods, you must upgrade to the latest maintenance release of TrueNAS 13.0 or 13.3 before attempting to migrate.
See Software Releases to confirm the latest version.
Performing a Clean Install
To migrate directly from TrueNAS 13.0 or 13.3 to the latest TrueNAS Community Edition release (24.10 or later), perform a clean install using an iso file for the target version.
After obtaining a file from the Software Releases page or Download TrueNAS Community Edition follow the instructions in Installing TrueNAS to install TrueNAS Community Edition.
You can migrate from TrueNAS 13.0 or 13.3 to 24.04 using either the update train method or a manual update file.
After migrating, you can follow the standard update process to step through each major release until you reach the latest version.
Select Update Train
This method is only available for non-Enterprise community systems.
To migrate to TrueNAS 24.04 using the UI Update screen and Train selector:
Go to System > Update
From the Train dropdown, choose the latest stable TrueNAS release, 24.04 (Dragonfish) or newer.
Review the TrueNAS migrations warning and verify the system is ready to migrate before confirming and continuing.
When the latest update for that chosen TrueNAS release is loaded, click Apply Pending Update or Download Updates to begin the update process documented in Updating TrueNAS.
It is strongly recommended to download the system configuration backup prior to starting the update.
After the system installs the update and restarts, log in and review the system configuration to ensure the migration was successful.
Manual Update
To migrate to TrueNAS 24.04 using the UI Update screen and a TrueNAS 24.04 update file:
If this process fails, retry using the iso file method above.
Confirm that the system is on the latest public release of TrueNAS 13.0 or 13.3.
Select a Temporary Storage Location (either Memory Device or a Pool) for the manual update file.
Click Choose File and select the update file you downloaded.
After gaining access to the UI, sign in with the admin user credentials created during installation.
Go to System > Advanced Settings and upload the system config file.
Uploading a previously-saved system config file migrates your settings, including accounts, directory services, networking, services, shares, storage configuration, system setting, data protection tasks, and more.
The system restarts to apply the uploaded configuration.
After TrueNAS restarts, sign in with the root user credentials from the previous configuration.
Uploading the config file deletes the truenas_admin user account created during a clean install and therefore requires you to recreate an administrative user.
After uploading the config file, review each area of the UI previously configured to validate pools imported and settings migrated correctly. Begin with your network settings.
TrueNAS automatically renames components, such as disks and interfaces, migrated from TrueNAS 13.0 (or 13.3 for community users), but does not modify the component Description.
For example, the Name of an interface identified as igb0 in TrueNAS 13 is updated to eno1 after migration to TrueNAS 24.04, but the Descriptionigb0 is retained.
This difference is purely cosmetic and does not affect functionality.
Use the information gathered during your preparation to migrate to restore settings, tasks, VMs configured using the GRUB bootloader, credentials, etc. not present after uploading the config file.
Do I need to upload a config file?
Uploading a config file after a TrueNAS migration or fresh install makes it easy to migrate most system settings with one click. However, you can choose to manually recreate the previous configuration if desired or if some part of the previous configuration causes conflicts with a later TrueNAS version.
If you choose to manually recreate settings, carefully document your original configuration and ensure each setting is recreated exactly.
For example, re-creating a user account named bob after migration does not restore access to existing datasets for the bob user account unless the new account uses the same UID or you manually update the dataset ACLs to grant access.
Recreating the Admin User Account
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
Reverting Back to FreeBSD-Based Releases
In the event you need to revert to the FreeBSD-based release and you are joined to Active Directory, first leave AD, then clean-install the FreeBSD-based version, and upload the system config file to recover. Rejoin AD. Verify the system is configured as desired, and AD is healthy.
Save a new debug file, then save the system configuration file with the secret seed. Use the procedures above to migrate to the latest Debian-Linux version of TrueNAS.
SNMP v3 Service Migration
It is possible for SNMP v3 service settings to not fully migrate from FreeBSD-based releases to a Debian-Linux version, and then not carry over after upgrading from release 25.10.4 to later releases.
To resolve this, go to System > Services in the Debian-Linux TrueNAS UI:
Stop the SNMP service.
Edit the SNMP service by re-entering the SNMP v3 service values you recorded when Preparing to Migrate, and then click Save.
Toggle the SNMP service Start Automatically to on.
Start the SNMP service.
Enterprise Migrations
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 process requires:
Backing up critical data.
An extended maintenance window.
Executing the migration process in a precise order.
Additional system configuration to update network interfaces and add new administrator accounts.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
The Linux-based TrueNAS OS incorporates all the major FreeBSD-based TrueNAS storage and sharing features with a web interface based on Debian GNU/Linux.
Users might notice similarities between the Linux-based TrueNAS UI and the FreeBSD-based TrueNAS UI.
However, the switch from FreeBSD to Linux results in some differences, primarily in component naming.
TrueNAS automatically renames components, such as disks and interfaces, migrated from TrueNAS 13.0 (or 13.3 for community users), but does not modify the component Description.
For example, the Name of an interface identified as igb0 in TrueNAS 13 is updated to eno1 after migration to TrueNAS 24.04, but the Descriptionigb0 is retained.
This difference is purely cosmetic and does not affect functionality.
Disks
TrueNAS 13.3 or earlier utilizes a numerical listing of drives in a system.
TrueNAS 22.12 or newer uses a lettered format for drive identification.
TrueNAS 22.12 or newer still labels NVMe drives with a numeric value.
Interfaces
TrueNAS 13.3 or earlier enumerates interface names using interface drivers, such as igb for Intel devices, followed by a number.
TrueNAS 13.3 or earlier Enterprise systems use ix followed by a number.
TrueNAS 22.12 or newer enumerates interface names using PCI locations. By default, systems identify their network ports with eno or enp followed by a number.
TrueNAS 13.3 or earlier identifies bonded interfaces or link aggregations with lagg followed by a number (lagg1).
TrueNAS 22.12 or newer uses bond followed by a number (bond1).
See the Products section for lists of the default port names for each platform.
(obsolete) ZFS Feature Flags Removed
This content is obsolete and no longer relevant to TrueNAS users.
Please refer to major version release notes for updates concerning ZFS feature flags.
Third-Party Data Migration
Users of TrueNAS 24.04 (Dragonfish) or newer can migrate data from a third-party NAS solution onto TrueNAS using the Syncthing Enterprise application.
The Syncthing Enterprise application can mount remote SMB shares in a manner that preserves relevant metadata.
TrueNAS 24.10 (Electric Eel) also adds migration support for SMB alternate data streams (ADS), used to store application-specific metadata.
Syncthing Overview
TrueNAS Enterprise
Third-party data ingest is available to TrueNAS Enterprise customers with TrueNAS 24.04 (Dragonfish) and newer deployed, as well as the appropriate applications license.
TrueNAS Enterprise Support staff are available to assist with deploying the Syncthing Enterprise Application and migrating data.
Please contact TrueNAS Enterprise Support to learn more and schedule a time to deploy the app and begin migration.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Data migration from a third-party NAS requires advanced configuration of both the remote source and TrueNAS target.
Ensure the source NAS supports the SMB protocol version 3 or newer.
Older versions of the SMB protocol are not supported.
Plan for one-way migration of data from the source to the TrueNAS target.
Remote shares must be mounted read-only.
Read-write configuration or bidirectional synchronization is not supported.
Configure both source and target systems with directory services and synchronize accounts.
All accounts referenced in NFSv4 ACLs and Windows Security Descriptors must be available on the TrueNAS server.
The remote NAS must not have any security information that references local NAS accounts rather than domain accounts.
Remove ACL entries that reference local accounts or non-domain users and groups before migration.
Mounting a remote NAS for data ingest purposes without a common identity source and agreement in place for handling local accounts is an unsupported configuration.
Process Overview
The process of setting up data migration from an external NAS to TrueNAS consists of:
Installing two instances of the Syncthing Enterprise app, configuring the first instance to ingest data from the external source and the second instance to write data to a local dataset on the target system.
Creating the target dataset for the data ingest on TrueNAS.
Configuring a Syncthing marker folder on the remote source.
Connecting the two Syncthing instances and initiating data sync.
Setting Up Data Migration
Install the first instance of the Syncthing Enterprise app on TrueNAS.
a. Go to Apps > Discover Apps, locate the Syncthing enterprise app widget.
Ensure the widget reflects the Enterprise train version of the app.
If the Enterprise version is not available, add the Enterprise train to the TRUENAS catalog.
Adding Enterprise Train Apps
Click on the widget to open the Syncthing details screen.
Click Install to open the Install Syncthing screen.
b. To avoid name conflicts, use a unique name to indicate this Syncthing instance is mounting the remote share. For example Syncthing-ingest.
c. Accept the defaults in Version, Syncthing Configuration, and User and Group Configuration.
d. Disable Host Network under Network Configuration. Default ports can be used for this Syncthing instance.
e. Select ixVolume (Dataset created automatically by the system) or configure an existing host path for Syncthing Home Storage under Storage Configuration.
f. Select SMB Share (Mounts a persistent volume claim to an SMB share) from the Type dropdown for Additional Storage.
Enter a clear identifying name, such as INGEST, and click Save.
Create a new dataset on TrueNAS to be the target for the data ingest, for example, /mnt/tank/ingest.
This dataset serves as the migration destination for both Syncthing instances.
Click Advanced Options and set ACL Type to SMB/NFSv4.
Set ACL Mode to Restricted.
These ACL settings are required on the migration target dataset. If using an existing dataset, verify these settings are configured before proceeding.
Install the second instance of the Syncthing Enterprise app on TrueNAS.
a. Go to Apps > Discover Apps, locate the Syncthing enterprise app widget.
Ensure the widget reflects the Enterprise train version of the app.
b. To avoid name conflicts, use a unique name to indicate this Syncthing instance is writing to a local dataset. For example Syncthing-migrate.
c. Accept the defaults in Version, Syncthing Configuration, and User and Group Configuration.
d. Disable Host Network under Network Configuration.
Use non-default ports for this Syncthing instance that differ from the configured ports on the first instance.
e. Select ixVolume (Dataset created automatically by the system) or configure an existing host path for Syncthing Home Storage under Storage Configuration.
f. Select Host Path (Path that already exists on the system) from the Type dropdown for Additional Storage.
Enter or browse to select the Host Path for the target dataset created in step 3.
Enter a clear identifying name, such as MIGRATE, and click Save
Configure a Syncthing marker folder on the remote source.
By default, Syncthing places a hidden folder, called .stfolder, on the root of each share.
This folder allows Syncthing to confirm that the volume is properly mounted.
Syncthing cannot sync without a marker folder.
As the remote SMB share is mounted read-only, Syncthing is not be able to create this marker folder.
There are two ways to manually configure a marker folder:
Manually create a hidden folder named .stfolder at the root level of the remote share.
Access the root directory of the remote source from a client that has read-write access to create the folder.
or
Access the Syncthing UI for the ingest instance.
Click Actions in the top toolbar and select Advanced to open the Advanced Configuration screen.
Select the ingest folder and change Marker Name from .stfolder to another folder or file that is present on the remote source.
a. Copy the device ID from the first Syncthing instance UI.
Click Actions in the top toolbar and select Show ID to open the Device Identification screen.
Click Copy.
b. Add a remote device on the UI of the second Syncthing instance.
Click Add Remote Device and paste in the device ID copied from the first instance.
Click Advanced.
Enter the device address and port for the first Syncthing instance, in the format
tcp://ip:port.
The address requires // after tcp:. Entering tcp:*ip*:*port* without the slashes fails with a misleading error.
c. Repeat steps a and b in the opposite direction to add a remote device to the first Syncthing instance using the device ID, IP address, and port of the second instance.
Initiate migration.
Access the Syncthing UI for the first instance.
Click Edit on the remote SMB folder created during step 2.
Click Sharing and select the migrate instance. Click Save.
Syncthing begins syncing data from the remote source to the ingest dataset on TrueNAS.
Configuration Instructions
This section provides instructions for users that are configuring TrueNAS for the first time.
TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial set up and configuration of their systems.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
After completing the installation process, you can either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the TrueNAS UI to make network changes and complete the initial configuration.
Configuring your system includes:
Setting up your first pool
Setting up data sharing
Setting up backup for the system and your stored data
Configuration Articles
Logging In for the First Time: Describes the web interface, logging in to the TrueNAS web interface for the first time, changing from root to the admin user, and navigating through the UI.
Setting Up Storage: Provides basic instructions for setting up your first storage pool and dataset or zvol.
Setting Up Data Sharing: Provides general information on setting up basic data sharing on TrueNAS.
Backing Up TrueNAS: Provides general information and instructions on setting up data storage backups, saving the system configuration and initial system debug files, and creating a boot environment.
Now that you have installed TrueNAS, or migrated from an earlier version, you can log into the web user interface (UI) to complete your initial system configuration and begin managing data!
Use only the web user interface (UI) to make configuration changes to the system.
By default, using the LINUX shell command-line interface (CLI) to modify the system does not modify the settings database.
After a system restart, changes made in the CLI revert to the original database settings, wiping away any user-made command line changes.
Web Interface Access
TrueNAS automatically creates several ways to access the UI, but you might need to adjust the default settings for your network environment.
By default, a fresh install of TrueNAS provides a default address for logging in to the web interface.
To view the web interface IP address or reconfigure web interface access, either connect a monitor and keyboard to your TrueNAS system or connect with IPMI for out-of-band system management.
When powering on a TrueNAS system, the system attempts to connect to a DHCP server from all live interfaces to access the web UI.
On networks that support Multicast Domain Name Services (mDNS), the system can use a host name and domain to access the TrueNAS web interface.
By default, TrueNAS uses the host name and domain truenas.local.
To change the host name and domain in the web interface, go to Network and click Settings on the Global Configuration widget.
To access the web interface using an IP address, either use the DHCP-assigned IP address displayed at the top of the Console Setup menu after installing TrueNAS or use the static IP address you assigned using the Console Setup menu.
TrueNAS Enterprise
TrueNAS Enterprise (HA) systems have specific network configuration requirements.
Installing TrueNAS on High Availability (HA) systems and configuring networking is complicated and should be guided by Enterprise-level support.
Contact TrueNAS Enterprise Support for assistance whenever attempting to install TrueNAS on Enterprise HA hardware or configure network settings.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Use a computer with access to the same network as the TrueNAS system.
Enter the host name and domain or IP address assigned to the primary network interface in a web browser to connect to the TrueNAS web interface.
The browser used to access the TrueNAS UI can impact the quality of your user experience. We generally recommend using Firefox, Edge, or Chrome.
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
With the implementation of administrator accounts, the root user is no longer the default administrator username.
Based on the method used to install TrueNAS, you can be presented with different first-time login scenarios, each described below.
Clean Installing TrueNAS
When installing TrueNAS from an iso file, and based on the authentication method selected in step 4 of the TrueNAS installer process, you can see a different sign-in screen for the web UI and need to use different login credentials.
Selecting 1. Administrative user (truenas_admin) opens the standard TrueNAS sign-in screen where you enter the new truenas_admin username and password created during installation.
The root user password is disabled by default. We recommend this option, as it creates the required administrative user and disables the root user password, and which brings the system into compliance with FIPS security hardening standards.
The root user still exists but with the password disabled by default, which means only the truenas_admin user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Selecting 2. Configure using Web UI opens a TrueNAS sign-in screen with two options. Select the option to either create the admin or root user and password.
If creating and logging in as the admin user, after logging in you must immediately disable the root user password to comply with FIPS security hardening standards.
If creating and logging in as the root user, after logging in you must create the admin user and then immediately disable the root user password to comply with FIPS security hardening standards.
The root user still exists but with the password disabled by default, which means only the admin user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Upgrading from TrueNAS Early Releases
Early Linux-based releases of TrueNAS (Angelfish and pre-22.12.3 Bluefin release) use the root user credentials to log into the system.
After upgrading from an earlier release, use the existing root user credentials to log into TrueNAS.
After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.
The root user still exists but with the password disabled by default.
This means only an administrative user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Migrating/Upgrading from FreeBSD- to Linux-based TrueNAS Versions
TrueNAS Enterprise
Customers with a TrueNAS Enterprise High Availability (HA) system should review Migration Preparation, Enterprise HA Migrations, and consult with TrueNAS Enterprise Support prior to migrating.
For non-HA systems, there are two possible scenarios when migrating:
Clean installing TrueNAS using the iso file and then uploading the previous configuration file.
Using the 13.0 (or 13.3 for community users) Update UI option to upgrade.
If performing a clean install using the TrueNAS iso file, after installing TrueNAS and uploading the configuration file, your network settings get overwritten by the config file, so you cannot use the new IP address and admin user to access to the web UI.
Use the previous address and root credentials to access the UI.
See TrueNAS Migrations for instructions on recovering the new network settings and access to the UI, and recreating the administrator account.
If using the Update UI option, log into TrueNAS with the existing root user credentials.
After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.
The root user still exists but with the password disabled by default.
This means only an administrative user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Logging In as Truenas_Admin
After setting up the truenas_admin user from one of the scenarios documented above, enter truenas_admin and the password to log in.
To modify user credentials, go to Credentials > Users, click anywhere on the user row, then click Edit.
For more information, see Managing Users.
Logging In as Root
If logging in with the root user credentials, enter root as the user and the root password.
After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.
The root user still exists but with the password disabled by default.
This means only an administrative user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Follow the directions in Managing Users to create an administration user with all required settings.
For environments requiring specific configurations, such as non-AD environments or those using LDAP, ensure that your admin user is properly set up to manage all aspects of the system.
Creating an Administrator Account at First Log in
If you selected the installation option 2. Configure using Web UI, the sign-in screen shows two authentication methods.
One allows you to log in as root or you can create the administration account.
Select either the Administrative user or Root user (not recommended) option, then enter the password to use with that user.
If you choose Root user (not recommended) as the TrueNAS authentication method, go to the Credentials > Users screen and create the admin account immediately after you enter the UI.
Enter the admin user name and password, make sure the password is enabled, and click Save.
After setting up the admin user, click on the root user and then click Edit. Disable the root user password and then click Save.
This brings the system into compliance with FIPS system security-hardening standards.
Troubleshooting Accessing the Web UI
If you cannot remember the administrator password to log in to the web interface, connect a keyboard and mouse to the TrueNAS system and open the Console Setup menu to reset the administrator account password.
UI is not accessible by IP address
If the user interface is not accessible by IP address from a browser, check the following:
If the browser configuration has proxy settings enabled, disable them and try connecting again.
If the page does not load, ensure a ping reaches the TrueNAS system IP address.
If the IP address is in a private range, you must access it from within that private network.
UI displays but seems unresponsive
If the web interface displays but seems unresponsive or incomplete:
Make sure the browser allows cookies, Javascript, and custom fonts from the TrueNAS system.
Try a different browser. We recommend Firefox, Edge, or Chrome.
If the UI becomes unresponsive after an upgrade or other system operation, clear the site data and refresh the browser (Shift+F5).
Introducing the TrueNAS Dashboard
After logging in for the first time, the main system Dashboard screen displays.
The Dashboard shows different system information cards (widgets) with basic information about the installed version, systems component usage, network traffic, and configured pools or storage usage.
The dashboard includes configurable widgets that include a text-only Custom widget and an Apps widget you can configure to monitor your installed applications.
TrueNAS Enterprise users with an iXsystems-provided server also see an image of the system in the System Information widget.
Click on the system image to open the System > View Enclosure screen.
The Dashboard for non-Enterprise systems displays the TrueNAS logo on the System Information widget.
To customize the dashboard , click Configure to put the Dashboard into configuration mode.
Use the drag bar to move widget groups to new positions on the screen.
Click Add to create new widgets or the Edit option in the widget group to change the look or information included in a widget.
The top row (toolbar) has links to outside resources and buttons to control the system.
The left-hand panel lists the main feature and functional areas and lets users navigate to the various TrueNAS configuration screens.
Top Toolbar
The TrueNAS top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI.
Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens.
It also shows the name of the user currently logged into the system to the left of the Settings icon.
You can also collapse or expand the main function menu on the left side of the screen.
The Search UI global search bar allows users to search for screens and elements within the TrueNAS UI or to redirect search terms to the TrueNAS Documentation Hub.
Searching UI Fields
Click the Search UI bar or type Ctrl + / to select the UI global search.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
TrueNAS
The TrueNAS logo returns to the Dashboard from any other screen.Send Feedback
TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.
To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window.
Alternatively, go to System > General Settings and click File Ticket on the Support widget.
Rating a UI Screen
Click Rate this page to send feedback on a UI page.
You can include a screenshot of the current page and/or upload additional images with your comments.
You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.
Click Report a bug to create an engineering ticket when a TrueNAS screen or feature is not working as intended.
This submits the ticket directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click Report a bug to see the fields to create an engineering ticket for system errors, bugs, or unexpected behavior.
For example, report a bug where a middleware error and traceback occurred while saving a configuration change.
Enter a descriptive summary in the Subject.
For example, if a configuration change does not update after clicking Save and you get an error message or traceback after attempting the change, enter XYZ setting fails to save with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
I clicked the edit XYZ settings option, modified the XYZ setting, and clicked Save. The operation failed and showed the following traceback message: [include the traceback text]. My system is running TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to speed up the issue resolution.
Select Attach debug.
To attach a screenshot of the current page, select Take screenshot of the current page.
Or, before using this form, take screenshots of the screen, traceback or other error message, copy a log into a text file, or create any other file to attach.
Open this form and attach those files by selecting Attach additional images and clicking Choose File to open a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
TrueNAS displays a message telling users to check their email for verification instructions.
Status of TrueNAS Connect
TrueNAS provides quick access to TrueNAS Connect from the top toolbar in your TrueNAS system.
The Status of TrueNAS Connect icon opens the TrueNAS Connect dialog.
Before you sign up for TrueNAS Connect, the dialog shows it is waiting to connect.
After connecting to TrueNAS Connect and registering the system, the Status of TrueNAS Connect icon shows an active status indicator.
The TrueNAS Connect dialog shows the status of the active connection.
Click Open TrueNAS Connect to open the TrueNAS Connect management interface.
Click cloud_offDisable Service to disconnect the system from TrueNAS Connect.
Click on either service to go to its configuration screen.
Jobs
The Running Jobsassignment icon button opens the Running Jobs window showing a minimized view of all running, waiting, and failed jobs/processes.
Hover the mouse over an error job to view a pop-up window with the error message for that failed job.
Click the minus (-) at the top right corner of any dialog or pop-up window to minimize a job/process.
Click on a running job to open a dialog for that job.
A running job shows a progress bar and a stop_circle button to the right of the job. Click on this to show the Abort dialog.
Click Abort to stop the job and abort the process.
Beginning in 25.04, the Abort option is only available for select jobs. Jobs that are unable to be aborted are listed without the stop_circle button as an option.
Click on Go to Jobs to open the Jobs screen with tabs to screens listing all successful, active, or failed and aborted jobs.
Click on the All, Active, or Failed button at the top of the screen to show the log of jobs that fit that classification.
Click View next to a task to see the log information and error message for that task.
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Settings
The Settingsaccount_circle icon opens a dropdown list of options to change passwords, modify two-factor authentication settings (when configured), create and manage API keys, access the TrueNAS documentation, and to log out of the TrueNAS UI.
Change Password
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
My API Keys
Click on My API Keyslaptop to go to the User API Keys screen.
API keys identify an outside resource or application without a principal.
For example, when adding a new system to TrueCommand if you are required to add an API key to authenticate the system.
Use this function to create an API key for this purpose.
Click API Docs to access the API documentation portal with information on TrueNAS API commands.
See API Keys for more information on adding or managing API keys.
See API Keys for more information on adding or managing API keys.
Guide
Click on Guidelibrary_books to open the TrueNAS Documentation Hub in a new tab.
Log Out
Log Out logs the current user out of the TrueNAS UI, but does not power off the system.
The Read-Only Admin and Sharing Admin roles only have access to the Log Out option.Power Options
Click the Powerpower_settings_new button to open the dropdown list of power options.
Restart logs you out of the TrueNAS UI and restarts the server. Shut Down logs you out of the TrueNAS UI and powers off the system as though you pressed the power button on the physical server.
TrueNAS Enterprise
Please consult your specific hardware documentation to find notes about possible hardware-specific controls for power-on or off behaviors.
With the implementation of administrator roles, the power options are locked based on the level of privileges for the administrator role.
The full administrator has access to both power options, but read-only and sharing admin roles do not.
The power options that show a lock icon indicate the function is not permitted.
Managing Sessions
To monitor and manage all active sessions, go to System > Advanced Settings and locate the Access widget.
Next Steps
With access to the TrueNAS web interface and all the management options, you can begin configuring your system!
Configuring TrueNAS Using the UI
TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support after their system(s) arrive to receive additional guidance on the next steps.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS users should follow the instructions provided below to complete the initial system setup and configuration.
Use the information mentioned in the installation preparation instructions article for your TrueNAS installation type (Enterprise, non-Enterprise, or home use) to configure your network, SMTP, or directory service settings.
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
After logging into TrueNAS, you can begin configuring TrueNAS using the web interface.
Enterprise Licenses and Proactive Support
TrueNAS Enterprise
Applying Enterprise Licenses
TrueNAS Enterprise customers should contact Support to obtain their TrueNAS system license information.
To apply the license information, go to the System > General Settings screen and use the Update License option on the Support widget (system information card).
Setting up Proactive Support
TrueNAS Enterprise customers with Silver or Gold Coverage support contracts can configure proactive support.
Customers with appropriate support contracts can configure Proactive Support after they apply their system license, and after acknowledging and signing the End User License Agreement (EULA).
After entering your system license, the Proactive Support option shows on the Support widget on the System > General Settings screen.
Setting Up Networking
TrueNAS uses DHCP to assign the IP address required to access the TrueNAS UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by TrueNAS, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure TrueNAS.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the TrueNAS UI to configure your network interfaces and other network configuration settings.
The TrueNAS UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS if you make a mistake with network interface settings.
If you are unfamiliar with network services, devices, or configurations, you can find more information here to help guide you through this important and required configuration area.
TrueNAS Enterprise
You must disable failover in the UI on TrueNAS Enterprise HA systems to add or change any network setting. Complete network changes and test them, then re-enable failover.
Adding Network Interfaces
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (LAGG) or network bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
If your system has more than one network interface card (NIC) connected to your internal network (wired to your router or Internet access point), you can add an interface in TrueNAS.
DHCP is only available for a single interface; all other physical interfaces must be manually configured with static IP addresses.
TrueNAS allows configuring virtual network interfaces such as a bridge, link aggregate (LAGG), or virtual LAN (VLAN) interface.
TrueNAS Enterprise
TrueNAS Support strongly discourages using the FAILOVER protocol setting when configuring Link Aggregation (bond) interfaces in HA systems.
Using this setting in HA systems might delay moving the virtual IP address from one controller to the other during a failover, causing network access delays.
Additionally, TrueNAS does not allow marking a bond interface in HA systems as Critical when the FAILOVER protocol is used but it is allowed in non-HA systems.
Static IP addresses and aliases provide support for various network applications.
TrueNAS Enterprise
TrueNAS Enterprise HA systems use a virtual IP (VIP) to maintain access to the UI when the system fails over to the standby controller.
This VIP address might experience a minor blip at failover, but you do not need to log in with the standby controller IP address to gain access to the UI after a failover.
The Add Interface screen allows configuring a network interface with a static IP address or adding an alias IP address.
For more information on when to use an alias or a static IP address, see Managing Interfaces.
Setting Up Storage
TrueNAS requires at least one storage pool.
We recommend creating the required pool, then planning the rest of your storage needs before adding sharing, container applications, virtual machines, or storing data.
When planning your data storage, consider the type of data sharing you want to do, any container applications you might want to deploy, and how you want to organize stored data.
The storage creation process begins with creating a pool, then adding datasets or zvols as needed.
Creating your initial storage is explained here.
Setting the System Dataset
TrueNAS assigns the root (parent) dataset of the first created pool as the system dataset.
If your system has enough disks to add more pools, you can change the system dataset to a root dataset of another pool.
Setting Up Shares
After setting up system storage, configure data sharing using one of the sharing protocols available in TrueNAS.
These articles provide more information on the three built-in share types available in TrueNAS and configuring data sharing:
Set the service to allow SSH login for administration users (admin or, if also enabled, the root user) on all TrueNAS systems.
All TrueNAS systems that need SSH access should enable SSH service as part of the initial UI configuration, but this is an area of security vulnerability.
To security-harden your system, do not enable SSH and leave it activated at all times.
Enable the service when SSH access is needed and then disable it until needed again.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
Failover service on TrueNAS Enterprise High Availability (HA) systems
The failover service enables an HA system to fail over to the standby system controller after a disruption to the primary controller.
This service is not included in non-Enterprise and non-HA systems.
Enterprise customers should not change failover settings or the service on their own, except when disabling failover to make network settings changes.
Contact TrueNAS Enterprise Support for assistance before making changes to other failover settings.
When adding data sharing, the system prompts you to enable the appropriate sharing service as part of the configuration and setup process.
If your installation includes a UPS, configure and enable the UPS service.
Exiting Configuration Screens Without Saving
TrueNAS allows exiting a configuration screen without saving, but asks if you want to exit without saving before closing it.
After opening a configuration screen and changing or entering a setting, when you click away from the screen or on the X at the top right of the screen, a dialog opens and asks if you are sure you want to exit the screen.
To close without saving, click Yes or No to continue making changes or entering values.
Setting Up Backup Solutions
After completing your initial system configuration and before beginning day-to-day operations, we recommend configuring the system and data storage backup methods.
The best practice for critical data is to use more than one solution or method to back up your data in case one method fails. Recommended minimum system backup options:
Save or create a new boot environment before upgrading the system to create a restore point if system issues cause lost access to the TrueNAS UI.
Download a system debug to capture system information before and after an upgrade or major change for comparison against future debug files.
Downloading System Files
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.
When downloading the configuration (config) file, select the Export Password Secret Seed option to include the secret seed in the config file.
Downloading the config file allows you to restore the system to a different operating system device where the secret seed is not already present.
Why should I save the secret seed?
The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database.
TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields.
Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps.
Always select the Export Password Secret Seed option when you download the system config file.
What happens if I do not save the secret seed?
You can still log into the web UI with your existing password.
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.
TrueNAS disables SMB authentication for all local user accounts.
To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password.
TrueNAS requires a new password before it re-enables SMB authentication for that account.
TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs.
It empties the values of others, such as SED passwords, certificate private keys, and service passwords.
Reconfigure these settings after you log in.
After you log in, recheck all system settings to verify the configurations are correct.
Then test the system to verify it works as desired.
When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.
Always save the secret seed with the system configuration file after you change the system configuration.
This gives you a current backup copy to use if you need it.
Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.
We recommend backing up the system configuration regularly.
Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues.
Save the configuration file each time the system configuration changes.
To download the configuration file:
Go to System > Advanced Settings and click on Manage Configuration.
Select Download File.
Select Export Password Secret Seed and then click Save. The system downloads the system configuration.
Keep this file in a safe location on your network where files are regularly backed up.
Keep downloaded system configuration files and initial or interim system debug files in a safe location where important files are regularly backed up.
You can use the boot environment in an SSH session to restore your system to the point where you completed your system configuration, and then import data or pools to recover stored data.
TrueNAS Enterprise
For Enterprise customers with High Availability (HA) systems, the HA restore process requires recovering both controllers.
Contact TrueNAS Enterprise Support for assistance before attempting to recover your system.
If you choose to restore access to the active controller 1 and the TrueNAS UI, contact TrueNAS Enterprise Support for assistance with properly recovering your second standby controller.
Enterprise HA customers should not start issuing CLI commands to recover the system!
Contact TrueNAS Enterprise Support after restoring access to controller 1 to request further assistance and before taking actions that can disrupt or damage system access and might result in a complete reinstall to recover.
Contact TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
After saving system configuration and debug files, we recommend setting up data storage backups using any or all of the following methods:
Taking regular snapshots or creating periodic snapshot tasks
Setting up replication to another system (remote replication)
Adding a cloud storage provider service and setting up a cloud sync task
You can take single snapshots or schedule periodic snapshot tasks to capture changes to stored data without the storage overhead that comes with backing up through data replication, or you can use one of the replication options TrueNAS provides.
Another option is to create a cloud storage service provider account and then let TrueNAS manage the backups to that account.
Use the Backup Credentials screen Cloud Credentials to add authentication credentials for a supported cloud service provider, and go to Data Protection to schedule a Cloud Sync Tasks that regularly backs up your storage data to the cloud.
Having a secondary backup solution for critical data is a best practice!
When backing up critical data to a cloud service provider, consider backing up the data to a remote server or a secondary cloud storage service as a protection against unforeseen failures with the primary backup solution.
Checking System Alert Settings and Services
You can view system alerts, configure an alert service, and enter an email account to receive alerts from TrueNAS from the Alerts screen accessed by clicking the Alerts icon on the top toolbar.
Configuring Alerts
The alert icon on the top toolbar shows a red circle with a number in it if TrueNAS encounters a configuration error or exceeds a threshold that you set (such as a temperature or a usage level).
The number indicates how many new alerts occurred.
Click on the alert icon to open the Alerts panel.
The Alerts panel Settings (gear) icon opens the Alert Settings screen where you configure the alert types and thresholds. The system email option opens a configuration screen where you enter an address to receive messages for a system event triggered by an alert.
Click Alert Settings to configure an alert service such as PagerDuty or customize alert settings such as type and threshold for triggering an alert.
Click Email to assign an email address to receive system alert notifications.
TrueNAS Enterprise
The Alert Settings screen includes access to Enterprise HA setting options that customize HA-related event thresholds that produce alerts or send emails.
Enterprise systems with FIPS and STIG enabled include alert settings to customize the event thresholds that produce alerts or send emails.
Setting Up Directory Services
TrueNAS allows configuring an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings.
TrueNAS allows configuring either directory server but not both.
We do not recommend switching between directory services. This can result in configuration issues that can disrupt your system!
However, it is possible to change from one directory service to another.
To migrate from LDAP to Active Directory, first, disable LDAP in TrueNAS, and then remove the current directory server settings.
To change from Active Directory to LDAP, use the Leave Domain option, and then disable the service before attempting to configure and enable LDAP.
TrueNAS Enterprise
TrueNAS Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the information customers provide, but do not configure customer Active Directory system settings.
Non-enterprise users can find support for configuring directory services in the TrueNAS Documentation Hub tutorials or the community forums.
Using Enclosure Management
TrueNAS Enterprise
The TrueNAS main Dashboard displays an image of the TrueNAS system server on the System Information widget for TrueNAS Enterprise customers with compatible hardware.
Click on the image to open the View Enclosure screen, or select the System > Enclosure option on the main menu navigation panel.
The View Enclosure screen provides details on system disks, pool and VDEV disks, disk hardware details, and disk status.
Click on a drive to view disk details.
If the TrueNAS system has an expansion shelf, the Enclosure screen also shows an image of the expansion shelf populated with disks.
If using TrueNAS on hardware not provided by TrueNAS, the System Information widget on the Dashboard displays the TrueNAS logo, and the System > Enclosure option does not exist on the menu navigation panel.
Using Applications in TrueNAS
TrueNAS shows a list of deployable applications on the Apps > Discover screen.
See the TrueNAS Apps Market for information on deploying and managing apps, app catalogs and images, including custom apps, and specific catalog app resources.
Updating TrueNAS
You can update your system with an iso file using the system Console Setup menu or with an update file installed through the TrueNAS UI.
There are a few ways to find available updates for your instance of TrueNAS:
The Software Releases article in the TrueNAS Documentation Hub shows upgrade paths, and provides links to available releases and updates.
The main Dashboard > System Information widget shows when a TrueNAS update is available to download and install.
Click the update option to open the System > Updates screen.
Go to System > Updates to check if an update is available.
For all update options and procedures using the TrueNAS UI see Updating TrueNAS.
Always save a system configuration file and a new boot environment for your current release and configuration before updating to a new incremental or full release.
It is also good practice to download a debug file before and after a system update.
Setting Up Storage
Now that you are logged in to the web interface, it is time to set up TrueNAS storage.
These instructions describe a simple mirrored pool setup, where half the selected disks are used for storage and the other half for data protection.
However, there are many configuration possibilities for your storage environment!
At minimum, the system needs at least two disks of identical size to create a mirrored storage pool.
While a single-disk pool is technically allowed, it is not recommended.
The disk used for the TrueNAS installation does not count toward this minimum.
You can configure data backups in several ways and have different requirements.
Backing data up in the cloud requires a 3rd party cloud storage provider account.
Backing up with replication requires you to have additional storage on the TrueNAS system or (ideally) another TrueNAS system in a different location.
This approach leverages persistent storage for overall data protection.
Setting Up Storage
Your system must have at least one storage pool configured.
After installing TrueNAS, enter the IP address assigned by DHCP (displayed in the Console Setup Menu) into a browser window to access the TrueNAS sign-in splash screen.
Log in to TrueNAS.
Begin by configuring your first storage pool.
See Creating Storage Pools for more information on how to plan for and create pools in TrueNAS.
If you want to create additional pools with other disks not assigned to a pool, you can do that now or as you have a need for them.
Creating a Storage Pool
Click Create Pool to open the Pool Creation Wizard.
Pool Creation Wizard
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Enclosure Option only shows for TrueNAS Enterprise systems with connected expansion shelves.
You can rename your enclosure on the Enclosure screen to include the rack and U number in the name, which helps identify the physical location while in the pool creation screen.
Enter a name of up to 50 lowercase alpha-numeric characters.
Use only the permitted special characters that conform to ZFS naming conventions.
The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
You cannot change the pool name after creation.
(Enterprise systems only) Select the Enclosure Option to apply the dispersal strategy of your choice.
This option only shows for TrueNAS Enterprise systems with connected expansion shelves.
The dispersal strategy sets how the system adds disks by size and type to the pool VDEVs created using the Automated Disk Selection option. Enclosures mentioned in the options below refer to the disk enclosures in the expansion shelves and main system chassis.
No Enclosure Dispersal Strategy does not apply a dispersal strategy, and does not show additional options.
Disks added to the pool VDEVs are assigned in sequence based on disk availability and are not balanced across all enclosures.
Maximum Dispersal Strategy applies a maximum dispersal strategy.
This option balances disk selection across all enclosures and available disks and does not show additional options.
Disks added to the pool VDEVs are spread across all available enclosure disks.
Limit Pool To A Single Enclosure applies a minimum dispersal strategy.
Select the expansion shelf option on the Enclosure dropdown.
Disks added to the pool VDEVs are spread across the enclosure disks that align with the selection in Enclosure.
Select the layout from the Layout dropdown list, then use the Automated Disk Selection fields to select and add the disks, or click Manual Disk Selection to add specific disks to the chosen Layout.
dRAID layouts do not show the Manual Disk Selection button but do show additional Automated Disk Selection fields.
When configuring a dRAID data VDEV, first, choose a Disk Size then select a Data Devices number.
The remaining fields update based on the Data Devices and dRAID layout selections.
ZFS allows groups to span multiple rows, which means it does not require each row to contain a whole number of redundancy groups. This layout has several advantages over requiring whole groups in each row:
Group count - Group count is not a relevant parameter when defining a dRAID layout. ZFS only needs the group width and all groups will have the desired size.
Group widths - ZFS can support all possible group widths (greater than or equal to the physical disk count).
ZFS determines the number of groups by the least common multiple (LCM) of the group width (D+P) and the number of physical drives minus spares (C-S). The logic within dRAID is simplified when the group width is the same for all groups, although some aspects, such as computing permutation numbers and drive offsets, are more complex. This flexible layout ensures even distribution of data and parity while maintaining high performance and resilvering efficiency.
Click Save And Go To Review if not adding other VDEV types to the pool or click Next to move forward to the next wizard screen.
Add optional VDEVs to suit your storage redundancy and performance requirements.
Click Create Pool on the Review wizard screen to add the pool.
The root dataset of the first pool you create automatically becomes the system dataset.
After adding your first pool, you can move on to creating datasets for data sharing, applications you plan to deploy, or other use cases.
Adding Datasets or Zvols
New pools have a root dataset that allows further division into new non-root parent and child datasets or into storage volumes (zvols).
A dataset is a file system that stores data and has specific permissions.
A zvol is a virtual block device (like a virtual disk drive) that has a predefined storage size.
Zvols are generally used with the iSCSI sharing protocol and also virtual machines (VMs) for their data storage needs.
To create a dataset or zvol, you can click Datasets on the main navigation panel or go to Storage and click Manage Datasets on the Usage widget for a specific pool to open the Datasets screen.
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
Organize the pool with as many datasets or zvols you need according to your access and data sharing requirements before moving data into the pool.
TrueNAS provides the option to create the dataset and share at the same time.
The Add Dataset screen allows you to create the new dataset and use a preset to configure an SMB, NFS, or multi-mode share.
The Shares screen also provides options to add an SMB or NFS share and create the dataset at the same time.
Do not set up sharing on the root dataset!
Creating a share that uses the root dataset causes all types of problems with permissions, and is not a best practice.
Rather, create or select a dataset that is a child of the root dataset and that is specifically created to share.
To create a dataset and share from the Add Dataset screen:
First click on the parent dataset row, then click Add Dataset.
Enter the name for the dataset.
Select the Dataset Preset option to use.
Based on the option selected, for example, selecting SMB, the screen populates the Share Name field with the name give to the dataset.
Click Save. TrueNAS creates the dataset and the share.
Configure permissions for the share. If you have created the share user, set up the share ACL permissions when prompted.
If you are not ready to configure the share permissions, exit to the main Datasets screen.
You can modify share dataset permissions later after adding the share user(s) by either selecting the dataset row, then clicking Edit on the Permissions widget. See Editing Permissions for more information.
You can also set permissions for the share from the Shares screen by selecting the share, then selecting the option to Edit Filesystem ACL for SMB, or set up NFS share permissions from the Add NFS share screen.
To create a dataset while adding the share, see Setting Up Sharing which covers the process of setting up the share and creating the dataset at the same time from the Shares screen.
See Manage SMB Shares or Manage NFS Shares for more information on adding and managing SMB or NFS shares.
Taking the Next Step
After you finish creating your initial pool and the datasets or zvols, you can continue building and organizing your TrueNAS pools and datasets or move on to configuring how the system shares data.
If you do not plan to set up data sharing, you can set up backup solutions for your system and stored data.
Setting Up Data Sharing
After setting up storage on your TrueNAS, it is time to begin sharing data!
There are several sharing solutions available in TrueNAS, but in this article we discuss the options to create the share and dataset from the Shares screens.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
Sharing Data Methods
TrueNAS provides three types of sharing methods:
SMB for Windows shares
NFS for Unix-like shares
ISCSi block shares
For more information on TrueNAS shares, see the Shares tutorials.
Regardless of what type of share you create, you need to create the user and dataset for the share.
Creating Share Users
Share users have permissions to access the share. You can create the user before or after you create the share.
Administrators can provision SMB share users from Active Directory, or non-SMB share users from LDAP.
The administration user can create a limited administration user with only the ability to manage shares.
See Using Administration Logins for more information on administration roles.
To add non-SMB share users or edit users, go to Credentials > Users to add or edit the user(s).
Click Add to create a new or as many new user accounts as you need.
Enter the values in each required field, verify SMB User is selected for SMB share users, then click Save.
For more information on the fields and adding users, see Creating User Accounts.
By default, all new users are members of a built-in group called builtin_users.
You can use a group to grant access to all users on the server or add more groups to fine-tune permissions for large numbers of users.
This approach is particularly useful for high availability (HA) configurations and efficient data sharing across multiple users.
Why not just allow anonymous access to the share?
Anonymous or guest access to a share is possible, but it is a security vulnerability and not recommended for Enterprise or systems with more than one share administrator account.
Using a guest account also increases the likelihood of unauthorized users gaining access to your data.
After creating the share user account(s), next create the share and dataset.
For iSCSI shares, create the dataset then the share.
You can create an SMB or NFS share while creating the dataset or create the dataset while creating the share.
This article provides instructions on creating the share and adding the dataset from Shares screens.
Setting up SMB Shares for Windows
For more detailed information on adding SMB shares, see Adding SMB Shares.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled.
You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To set up a basic SMB share from the Add SMB screen:
Create the share and dataset.
a. Go to Shares, then click Add on the Windows (SMB) Shares widget to open the Add SMB configuration screen.
b. Populate the Path screen by either selecting the path to an existing dataset mount path, or entering the path to the dataset location.
You can use an existing dataset or create a new dataset.
To browse to the location, click on the to the left of mnt, and then at the pool to expand the options.
Continue expanding until reaching the storage location of the existing dataset or where you want to create a new dataset for the share.
Click on the exiting dataset to populate the field with the full path, or click Create Dataset to enter a name for a new dataset and the share.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Clicking Create Dataset opens the Create Dataset dialog. Enter a name and then click Create.
The system creates the share and dataset, and populates both the Path and share Name fields with the name given the dataset.
The dataset name becomes the share name.
c. (Optional) Customize the share properties.
You can make changes to any share using the Advanced Options option.
For example, to turn on auditing, click Enable to set up audit logging.
d. Click Save. TrueNAS creates the share and the dataset.
e. Start the SMB service when prompted, or select the option to start the service if not prompted.
Edit the SMB share permissions to set the share owner and/or group. You can edit access permissions at the share or dataset level.
a. Click on shareEdit Share ACL icon to open the Edit Share ACL screen.
b. Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
c. (Optional) Click Add then select Group, then the group name, and set the group permissions.
d. Click Save.
Edit the dataset for the SMB share permissions to set the share owner and/or group.
You can edit share dataset permissions from either the Shares or Datasets screen. This step covers editing permissions from the Shares screen.
a. Click on shareEdit Filesystem ACL icon to open the Edit ACL screen for the dataset.
b. Select the Owner and Group and click Apply Owner and Apply Group.
With Who set to Owner, set the permission level using Permissions and Type.
c. Click Save. TrueNAS creates the share and the dataset.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
d. Start the share service when prompted.
Connect to the share. On a Windows 10 or later system, open the File Browsers and then:
a. Enter \\ followed by the TrueNAS system name or IP address in the navigation bar. A login credentials dialog displays.
b. Enter the TrueNAS user account credentials created on the TrueNAS system.
You can create an NFS share from either the Add Dataset screen while creating the dataset, or from the Add NFS share screen. Both options allow creating the dataset and the share at the same time.
To set up NFS sharing from the Add NFS screen:
Add additional packages like nfs-common to any client systems that require them.
Create the NFS share and dataset.
a. Go to Shares, then click Add on the UNIX (NFS) Share Targets to open the Add NFS configuration screen.
b. Populate the Path screen by either selecting the path to an existing dataset mount path, or entering the path to the dataset location.
You can use an existing dataset or create a new dataset.
To browse to the location, click on the to the left of mnt, and then at the pool to expand the options.
Continue expanding until reaching the storage location of the existing dataset or where you want to create a new dataset for the share.
Click on the exiting dataset to populate the field with the full path, or click Create Dataset to enter a name for a new dataset and the share.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Clicking Create Dataset opens the Create Dataset dialog. Enter a name and then click Create.
The system creates the share and dataset, and populates both the Path and share Name fields with the name given the dataset.
The dataset name becomes the share name.
c. (Optional) Customize the share properties.
You can make changes to any share using the Advanced Options option.
For example, mapping users or groups, click Enable to set up audit logging.
d. Click Save. TrueNAS creates the share and the dataset.
e. Start the NFS service when prompted, or select the option to start the service if not prompted.
Access the dataset.
On a Unix-like system, open a command line and enter command showmount -e {IPADDRESS} where {IPADDRESS} is your TrueNAS system IP address.
tmoore@ChimaeraPrime:~$ showmount -e 10.238.15.194
Export list for 10.238.15.194:
/mnt/pool1/testds (everyone)
Make a local directory for the NFS mount. Enter command sudo mkdir nfstemp/.
tmoore@ChimaeraPrime:~$ sudo mkdir nfstemp/
Mount the shared directory.
Enter command sudo mount -t nfs {IPADDRESS:dataset path} where {IPADDRESS} is your system IP address and {:dataset path} is the full path displayed in step 3.b. above.
tmoore@ChimaeraPrime:~$ sudo mount -t nfs 10.238.15.194:/mnt/pool1/testds nfstemp/
From here, cd into the local directory and view or modify the files as needed.
Setting up an iSCSI Block Share
Setting up block sharing is a complicated scenario that requires detailed configuration steps and knowledge of your network environment.
A simple configuration is beyond the scope of this getting started guide, but detailed articles are available in the Tutorials section.
With simple sharing now set up, you can back up your configuration and set up data backup.
Backing Up TrueNAS
After configuring your TrueNAS storage and data sharing or any other function, service, or application, it is time to ensure an effective data backup.
TrueNAS provides several options to set up a data storage backup method, including using a cloud sync provider and a scheduled task or configuring a replication task.
Backing Up the System Configuration
After setting up TrueNAS, first, back up your system configuration by downloading the system configuration file.
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.
When downloading the configuration (config) file, select the Export Password Secret Seed option to include the secret seed in the config file.
Downloading the config file allows you to restore the system to a different operating system device where the secret seed is not already present.
Why should I save the secret seed?
The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database.
TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields.
Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps.
Always select the Export Password Secret Seed option when you download the system config file.
What happens if I do not save the secret seed?
You can still log into the web UI with your existing password.
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.
TrueNAS disables SMB authentication for all local user accounts.
To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password.
TrueNAS requires a new password before it re-enables SMB authentication for that account.
TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs.
It empties the values of others, such as SED passwords, certificate private keys, and service passwords.
Reconfigure these settings after you log in.
After you log in, recheck all system settings to verify the configurations are correct.
Then test the system to verify it works as desired.
When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.
Always save the secret seed with the system configuration file after you change the system configuration.
This gives you a current backup copy to use if you need it.
Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.
We recommend backing up the system configuration regularly.
Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues.
Save the configuration file each time the system configuration changes.
To download the configuration file:
Go to System > Advanced Settings and click on Manage Configuration.
Select Download File.
Select Export Password Secret Seed and then click Save. The system downloads the system configuration.
Keep this file in a safe location on your network where files are regularly backed up.
Downloading the Initial System Debug File
After saving the system configuration, save an initial system debug file by going to System > General Settings and clicking Save Debug. After the download completes, save this initial debug file with your system configuration file.
Why download the initial system debug file?
Downloading and storing the initial system debug after completing the system configuration is a recommended best practice to have a point of reference for your system if a problem arises. Save a debug file after a major system upgrade or reconfiguration to provide Support or Engineering if requested.
Create a Boot Environment
After installing and completing your system configuration, create a boot environment to use as a restore point.
If you lose access to the TrueNAS UI, you can establish an SSH session and restore it from the boot environment.
You can clone the boot environment listed after the initial-install environment and rename the clone to something you recognize, such as the release number with date and time.
Backing Up TrueNAS Storage Data
TrueNAS has several options that allow you to back up data:
TrueCloud backup and cloud sync tasks require setting up a cloud service provider account and adding the credentials in TrueNAS before configuring and scheduling the tasks.
Replication requires setting up SSH credentials before configuring and scheduling the task. Rsync tasks can be configured with SSH credentials or set to use a module.
Using TrueCloud Backup or Cloud Sync
Cloud sync requires an account with a cloud storage provider and a storage location created with that provider, like an Amazon S3 bucket.
TrueNAS supports major providers like Storj, Amazon S3, Google Cloud, Box, and Microsoft Azure, along with a variety of other vendors.
These providers can charge fees for data transfer and storage, so please review the policies of your cloud storage provider before transferring your data.
Cloud sync and TrueCloud backup tasks can be configured to send, receive, or synchronize data with a cloud storage provider.
The simplest way to set up a TrueCloud backup task is using a Storj iX account.
See Managing TrueCloud Backup Tasks for a full tutorial.
See Adding Cloud Credentials for information on connecting TrueNAS to other cloud storage providers.
Using Replication
Replication takes a moment-in-time snapshot of data and then copies that snapshot to another location.
Snapshot technology typically uses less storage than full file backups and has more management and snapshot storage options.
Setting Up a Simple Replication Task
To create a simple replication task with the TrueNAS replication wizard:
Replication needs an existing periodic snapshot task** to run before the replication task runs or the replication task fails.
You can define a periodic snapshot before manually configuring the replication task, or let the system create the snapshot task by selecting the replication wizard Replicate Custom Snapshots option. When using the wizard, TrueNAS automatically creates the periodic snapshot task and then runs the replication task.
Create a periodic snapshot task using the replication wizard Replicate Custom Snapshots replication option.
If scheduling a task, TrueNAS creates the periodic snapshot task when it runs the replication task according to the scheduled time.
Create the replication task.
Go to Data Protection, and click Add on the Replication Tasks widget to open the Replication Task Wizard configuration screen.
Select the Source Location and Destination Location using the dropdown list options.
You can back up your data on the same or a different system.
If selecting A different system, you must have an SSH connection to that system. Have your destination and source information ready.
Set the Source and Destination paths, either enter the full path to the data you want to back up or click on the caret to the left of mnt and at the pool and dataset levels to expand the options. Click on the dataset or directory to narrow the backup down to that level.
The task name populates from the values in Source and Destination.
Select Replicate Custom Snapshots.
Click Next.
Define when to run this task.
Select the radio button for Run On a Schedule and select the schedule you want to use. Select Run Once to run the task manually.
When using this option, you must have defined a periodic snapshot task. If running on a schedule, you do not need to pre-defined a snapshot task.
Select the radio button to specify the destination snapshot lifetime.
Click START REPLICATION. The task appears on the Replication Tasks widget with the status PENDING.
You can monitor created backup tasks from the Dashboard widget.
Configuring Virtualization and Apps
Configuring TrueNAS to work with virtualized features, such as virtual machines (VMs) and applications, is part of the setup process that, when optimized, takes advantage of the network storage capabilities that TrueNAS offers.
Before You Begin
This article assumes you have the latest release version of TrueNAS installed on your system.
The following steps are a list of configuration prerequisites you have completed and are familiar with before beginning VM and application installations.
Network Configuration
The primary network interface is configured as part of the installation process.
Go to Network > Global Configuration screen in the TrueNAS web UI to determine if the default gateway, host name, domain, and DNS name servers have been configured correctly.
See Console Setup Menu Configuration for more information on network settings.
If VMs need to access local NAS storage, you need to create a network bridge and assign it to the VM.
Applications or sandboxes that need access to local storage within the container must use a bridge or mount a local storage location as a host path for the application.
VLAN Configuration (Optional)
You can configure a virtual LAN (VLAN) to route traffic for your VMs.
VLAN benefits include the reduction of broadcast traffic and the ability to group resources in different physical locations into a broadcast domain.
VLANs virtually segment a network.
Different VLANs can communicate with each other using layer 3 devices.
See Setting Up a Network VLAN for more information on creating virtual LANs (VLAN).
Storage Configuration
Storage pool creation is part of the initial process of setting up storage.
A TrueNAS dataset is a file system within a data storage pool.
See Setting Up Storage to review storage pool creation and Adding and Managing Datasets for information on dataset configuration.
Shares Configuration
After creating the pool and datasets, set up shares to enable data access and sharing.
Different types of data sharing methods are discussed in Setting Up Data Sharing.
You should investigate more specific coverage of each share based on your use case.
See Adding NFS Shares for information on creating a basic NFS share.
Adjust access permissions using the advanced options.
Directory Services Configuration
Certain directory services must be set up as part of SMB and NFS share configuration.
See Active Directory Screen for a better understanding of how to configure Active Directory and Configuring Kerberos for an outline of required Kerberos information.
For LDAP best practices see Configuring LDAP.
Virtual Machine and Container Configuration
Virtual Machines and Containers in TrueNAS 25.10
TrueNAS 25.04 introduced support for Containers (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in FreeBSD-based TrueNAS.
In TrueNAS 25.04.2 and later, virtual machines are created and appear on the Virtual Machines screen.
Legacy VMs created in 25.04.0 or 25.04.1 using the instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the Containers screen.
Legacy VMs on the Containers screen do not autostart in 25.10 or later.
Users with existing VMs on the Containers screen should consider migrating associated zvols to the Virtual Machines screen at this time to ensure compatibility with future TrueNAS releases.
For information on migrating your zvol storage volume to a new VM created in 25.10 or later, see Migrating Legacy VMs to Virtual Machines.
Due to backend technology changes in TrueNAS 27, containers on the Containers screen require migration when you upgrade from TrueNAS 25.10.
Containers migrate automatically at the first boot after upgrading, except on HA-capable TrueNAS Enterprise systems.
Containers on a passphrase-encrypted pool do not migrate, because the pool is still locked at first boot and the migration does not retry.
Switch the pool to key encryption before you upgrade.
Contact TrueNAS Enterprise Support if you have containers on a TrueNAS Enterprise system that does not migrate them.
Legacy VMs on the Containers screen are not migrated automatically and are removed from the Containers screen in TrueNAS 27.
Complete the steps in Preparing to Upgrade to TrueNAS 27 before you upgrade.
TrueNAS includes built-in virtualization capabilities that enable you to run multiple operating systems and containerized applications on a single system, maximizing hardware utilization and consolidating workloads.
Virtual Machines
Virtual machines provide complete isolation by running full operating systems with dedicated virtualized hardware including network interfaces, storage, graphics adapters, and other components. VMs are ideal for running legacy applications, different operating systems, or services that require dedicated environments.
TrueNAS assigns a portion of system RAM and a new zvol to each VM.
While a VM is running, these resources are not available to the host computer or other VMs.
Virtualization requires:
x86 machine running a recent Linux kernel
Intel processor with VT (Virtualization Technology) extensions, OR
AMD processor with SVM extensions (AMD-V)
Users cannot create VMs unless the host system supports these features.
Users with multiple GPUs who wish to pass a GPU to a VM must first isolate a GPU for VM use.
One GPU is always required by TrueNAS.
Linux containers, powered by LXC, offer lightweight, isolated environments that share the host system kernel while maintaining separate file systems, processes, and network settings. Containers start quickly, use fewer system resources than VMs, and scale efficiently, making them ideal for deploying applications with minimal overhead.
Containers are lightweight and share the host kernel, requiring fewer resources than virtual machines.
However, proper resource allocation ensures optimal performance and system stability.
You can leave CPU and memory settings blank to allow containers access to all available host resources, or configure specific limits based on your needs.
Key considerations for container deployment:
Storage Pool: Containers require a storage pool for volume creation and image storage.
SSD drives provide optimal performance.
CPU: No virtualization extensions required.
Multiple containers run efficiently on fewer resources than equivalent VMs.
Memory: More efficient than VMs with no guest OS overhead.
Memory allocated to containers reduces available memory for TrueNAS ZFS caching.
See Containers for Linux container configuration and management information.
Application Configuration
The first time you open the Applications screen, it displays an Apps Service Not Configured status on the screen header.
Click Settings > Choose Pool to choose a storage pool for Apps.
A storage pool for applications must be chosen before application installation can begin.
Select a pool with enough space for all the application containers you intend to use.
Set up a new dataset before installing your applications if you want to store your application data in a separate location from other storage on your system.
After an Apps storage pool is configured, the status changes to Apps Service Running.
For custom applications, Install Custom App details each field on the Install Custom App screen.
Before beginning a custom application installation, determine the following information:
Container host networking requirements, including host interface
IP address management: DHCP or static IP
DNS policy and nameservers
Container entrypoint (executables run when the container is started): commands or arguments
Container environment variables: names and values
Port forwarding
Storage: host path and mount path configuration
You can find additional options for configuring general network interfaces and IP addresses for application containers in Apps > Settings > Advanced Settings.
Getting Support
About TrueNAS Support
TrueNAS Enterprise
TrueNAS Enterprise hardware customers with support contracts can contact TrueNAS Support using either this Enterprise Support link or through one of the contact options listed below.
Contacting TrueNAS Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Community users are also welcome to report bugs in the TrueNAS Jira project instance directly (issue reporting guide).
When reporting an issue, download a system debug file taken immediately following the issue occurrence.
This captures the system configuration information and logs the TrueNAS team needs to help resolve your issues.
How to download a debug file
On TrueNAS systems, go to System > General Settings, then click Save Debug and wait for the file to download to your local system.
Generating the debug file might take a few minutes to complete. After that, it downloads to your system.
If your browser download shows a dialog asking for confirmation, click Keep to continue the download process.
To generate a debug from the TrueNAS CLI, enter system debug > debugname.tgz, replacing debugname with your chosen file name.
You must use SFTP or a similar method to connect to TrueNAS and download the file from the /home/username location, replacing username with the account name that generated the debug.
SFTP Example:
PS C:\Users\tester> sftp admin@exampletruenas.net
Connected to exampletruenas.net.
sftp> cd /home/admin
sftp> get testdebug.tgz
Fetching /home/admin/testdebug.tgz to testdebug.tgz
/home/admin/testdebug.tgz 100% 7110KB 4.1MB/s 00.01
sftp> exit
Upload this debug to the private attachments area using the link provided when you open a Jira ticket.
After uploading the file, link the attachment to the Jira ticket number before you click Save.
Support is also available through the TrueNAS community forums, blog, and Discord.
These options are accessible on the top header of the TrueNAS Documentation Hub website and from the links at the bottom of all articles.
Using the TrueNAS Community Forum
The TrueNAS Community is an active online resource for asking questions, troubleshooting issues, and sharing information with other TrueNAS users.
You must register to post.
Community Resources are user-contributed articles about every facet of using TrueNAS.
They are organized into broad categories and incorporate a community rating system to better highlight content that the whole community has found helpful.
Users can also suggest and vote for new TrueNAS features through the Community Forum!
Using TrueNAS Social Media
You are always welcome to network with other TrueNAS users using the various social media platforms!
We encourage TrueNAS users to report bugs and to vote for or suggest new TrueNAS features in the project Jira instance.
You must have an Atlassian account and join the TrueNAS Jira instance to create a bug ticket.
Signing in to your Atlassian account does not give you access to the TrueNAS instance.
For the steps to join the instance, see Joining the TrueNAS Jira Instance.
If you encounter a bug or other issue while using TrueNAS, you can report issues in one of two ways:
Log into Jira and use Create to open a new ticket details.
Use the Send Feedback icon or File Ticket option on the System > General Settings screen to create a bug report in the TrueNAS Jira Project.
The web interface provides a form to report issues without logging out of TrueNAS.
The form prompts you to provide the information and attachments we need to assist users.
New Jira tickets are publicly viewable so it is possible to search the project first to see if another user already reported the issue.
Each Jira ticket sends a link to a private file attachment area to safeguard user personal and private data.
We encourage users to use the link in the automated report response to keep the debug file secure and restrict access to only those that require the information to diagnose the cause of the issue reported.
If the attached files do not require privacy, attach them to the Jira ticket.
All incoming tickets are triaged.
If private files are attached to a new ticket, the ticket or files can be made private at that time.
System debugs contain log files which can include personal information such as usernames, and other identifying information about your system such as networking configuration, device serial numbers, etc.
Users can use a file archiver utility, such as 7-Zip File Manager, to open compressed debug archives and review log contents.
Redact any personal data you have concerns about sharing and save the debug file before attaching and linking it to a Jira ticket in the TrueNAS project.
Using the Send Feedback Window
TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.
To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window.
Alternatively, go to System > General Settings and click File Ticket on the Support widget.
Rating a UI Screen
Click Rate this page to send feedback on a UI page.
You can include a screenshot of the current page and/or upload additional images with your comments.
You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.
Click Report a bug to create an engineering ticket when a TrueNAS screen or feature is not working as intended.
This submits the ticket directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click Report a bug to see the fields to create an engineering ticket for system errors, bugs, or unexpected behavior.
For example, report a bug where a middleware error and traceback occurred while saving a configuration change.
Enter a descriptive summary in the Subject.
For example, if a configuration change does not update after clicking Save and you get an error message or traceback after attempting the change, enter XYZ setting fails to save with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
I clicked the edit XYZ settings option, modified the XYZ setting, and clicked Save. The operation failed and showed the following traceback message: [include the traceback text]. My system is running TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to speed up the issue resolution.
Select Attach debug.
To attach a screenshot of the current page, select Take screenshot of the current page.
Or, before using this form, take screenshots of the screen, traceback or other error message, copy a log into a text file, or create any other file to attach.
Open this form and attach those files by selecting Attach additional images and clicking Choose File to open a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Filling out the entire form with precise details and accurate contact information ensures a prompt response from the TrueNAS Customer Support team.
Making Feature Suggestions
Want to see a new feature added to TrueNAS?
You can see and vote for community-proposed features in the TrueNAS Community Forum Feature Requests category.
This is the place to suggest improvements and feature functionality to be considered for addition to the TrueNAS development roadmap.
Submitting and Voting for Requests
A TrueNAS forums account is required to submit or vote for feature suggestions.
To submit a new feature request, click New Topic in the top right of any forum screen
Enter a title that describes the requested improvement or new functionality.
Change the category tag to Feature Requests.
The body of the post populates a template.
Describe the Problem/Justification, Impact, and provide User Story for your request.
Click Create Topic to submit the request.
Each forum user can cast a limited number of votes for items at any given time.
The higher your trust level, the more votes you can cast.
The number of votes based on trust level is as follows:
Trust Level
Votes
0
2
1
4
2
6
3
8
4
10
Votes on a topic are kept until either you remove the vote manually or the topic is closed.
Topics are closed periodically after they are reviewed and either accepted or rejected based on their merit and feasibility.
What is a good feature request?
Before creating a new feature request, it is important to take some time to think through the implementation and user story.
A good feature request includes details about the functionality requested, if it involves a UI component, and a detailed user story describing how a TrueNAS user might interact with the proposed feature.
What is a bad feature request?
Items which are completely unrealistic (i.e. Can you base TrueNAS on Windows) or feature requests which are outside of the scope of typical NAS functionality (i.e. I want a full desktop with Gnome on TrueNAS).
PLEASE CAREFULLY READ THIS END USER LICENSE AGREEMENT (EULA) BEFORE CLICKING THE AGREE BUTTON. THIS AGREEMENT SERVES AS A LEGALLY BINDING DOCUMENT BETWEEN YOU AND IXSYSTEMS, INC. BY CLICKING THE AGREE BUTTON, DOWNLOADING, INSTALLING, OR OTHERWISE USING TRUENAS SCALE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS AGREEMENT). IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS IN THIS AGREEMENT, DO NOT USE OR INSTALL TRUENAS SCALE SOFTWARE.
This agreement is provided in accordance with the Commercial Arbitration Rules of the American Arbitration Association (the “AAA Rules”) under confidential binding arbitration held in Santa Clara County, California. To the fullest extent permitted by applicable law, no arbitration under this EULA will be joined to an arbitration involving any other party subject to this EULA, whether through class arbitration proceedings or otherwise. Any litigation relating to this EULA shall be subject to the jurisdiction of the Federal Courts of the Northern District of California and the state courts of the State of California, with venue lying in Santa Clara County, California. All matters arising out of or relating to this agreement shall be governed by and construed in accordance with the internal laws of the State of California without giving effect to any choice or conflict of law provision or rule.
1.0 Definitions
1.1 “Company”, “iXsystems” and “iX” means iXsystems, Inc., on behalf of themselves, subsidiaries, and affiliates under common control.
1.2 “TrueNAS SCALE Software” means the TrueNAS SCALE storage management software.
1.3 “TrueNAS Device” means the TrueNAS storage appliances and peripheral equipment provided by iXsystems or a third party.
1.4 “Product” means, individually and collectively, the TrueNAS SCALE Software and the TrueNAS Device provided by iXsystems.
1.5 “Open Source Software” means various open source software components licensed under the terms of applicable open source license agreements, each of which has its own copyright and its own applicable license terms.
1.6 “Licensee”, “You” and “Your” refers to the person, organization, or entity that has agreed to be bound by this EULA including any employees, affiliates, and third party contractors that provide services to You.
1.7 “Agreement” refers to this document, the TrueNAS End User License Agreement.
2.0 License
Subject to the terms set forth in this Agreement, iXsystems grants You a non-exclusive, non-transferable, perpetual, limited license without the option to sublicense, to use TrueNAS SCALE Software on Your TrueNAS Device(s). This use includes but is not limited to using or viewing the instructions, specifications, and documentation provided with the Product.
TrueNAS SCALE software is made available as Open Source Software, subject to the license conditions contained within that Open Source Software.
3.0 License Restrictions
TrueNAS SCALE Software is authorized for use on any TrueNAS Device. TrueNAS Devices can include hardware provided by iXsystems or third parties. TrueNAS Devices may also include virtual machines and cloud instances. TrueNAS SCALE software may not be commercially distributed or sold without an addendum license agreement and express written consent from iXsystems. .
The TrueNAS SCALE Software is protected by copyright laws and international treaties, as well as other intellectual property laws, statutes, and treaties. The TrueNAS SCALE Software is licensed, not sold to You, the end user. You do not acquire any ownership interest in the TrueNAS SCALE Software, or any other rights to the TrueNAS SCALE Software, other than to use the TrueNAS SCALE Software in accordance with the license granted under this Agreement, subject to all terms, conditions, and restrictions. iXsystems reserves and shall retain its entire right, title, and interest in and to the TrueNAS SCALE Software, and all intellectual property rights arising out of or relating to the TrueNAS SCALE Software, subject to the license expressly granted to You in this Agreement.
The TrueNAS SCALE Software may contain iXsystems’ proprietary trademarks and collateral. By agreeing to this license agreement for TrueNAS SCALE, You agree to use reasonable efforts to safeguard iXsystems’ intellectual property and hereby agree to not use or distribute iXsystems’ proprietary intellectual property and collateral commercially without the express written consent of iXsystems. Official iXsystems Channel Partners are authorized to use and distribute iXsystems’ intellectual property through an addendum to this license agreement.
By accepting this Agreement, You are responsible and liable for all uses of the Product through access thereto provided by You, directly or indirectly.
The TrueNAS SCALE software includes Open Source components and some proprietary extensions which are available through additional licences You agree to not alter the source code to take advantage of the proprietary extensions without a license to those proprietary extensions, including the TrueNAS Enterprise features sets.
4.0 General
4.1 Entire Agreement - This Agreement, together with any associated purchase order, service level agreement, and all other documents and policies referenced herein, constitutes the entire and only agreement between You and iXsystems for use of the TrueNAS SCALE Software and all other prior negotiations, representations, agreements, and understandings are superseded hereby. No agreements altering or supplementing the terms hereof may be made except by means of a written document signed by Your duly authorized representatives and those of iXsystems.
4.2 Waiver and Modification - No failure of either party to exercise or enforce any of its rights under this EULA will act as a waiver of those rights. This EULA may only be modified, or any rights under it waived, by a written document executed by the party against which it is asserted.
4.3. Severability - If any provision of this EULA is found illegal or unenforceable, it will be enforced to the maximum extent permissible, and the legality and enforceability of the other provisions of this EULA will not be affected.
4.4 United States Government End Users - For any TrueNAS SCALE Software licensed directly or indirectly on behalf of a unit or agency of the United States Government, this paragraph applies. Company’s proprietary software embodied in the Product: (a) was developed at private expense and is in all respects Company’s proprietary information; (b) was not developed with government funds; (c) is Company’s trade secret for all purposes of the Freedom of Information Act; (d) is a commercial item and thus, pursuant to Section 12.212 of the Federal Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202, Government’s use, duplication or disclosure of such software is subject to the restrictions set forth by the Company and Licensee shall receive only those rights with respect to the Product as are granted to all other end users.
4.5 Title - iXsystems retains all rights, titles, and interest in TrueNAS SCALE Software and all related copyrights, trade secrets, patents, trademarks, and any other intellectual and industrial property and proprietary rights, including registrations, applications, registration keys, renewals, and extensions of such rights.
Contact Information - If You have any questions about this Agreement, or if You want to contact iXsystems for any reason, please email legal@ixsystems.com.
4.6 Maintenance and Support - You may be entitled to support services from iXsystems after purchasing a Product or a support contract. iXsystems will provide these support services based on the length of time of the purchased support contract. This maintenance and support is only valid for the length of time that You have purchased with Your Product. iXsystems may from time to time and at their sole discretion vary the terms and conditions of the maintenance and support agreement based on different business environmental and personnel factors. Any variations will be notified via email and the support portal. For more information on our Maintenance and Support contract, refer to https://www.ixsystems.com/support/.
4.7 Force Majeure - iXsystems will not be deemed to be in default of any of the provisions of this Agreement or be liable for any delay or failure in performance due to Force Majeure, which shall include without limitation acts of God, earthquake, weather conditions, labor disputes, changes in law, regulation or government policy, riots, war, fire, epidemics, acts or omissions of vendors or suppliers, equipment failures, transportation difficulties, malicious or criminal acts of third parties, or other occurrences which are beyond iXsystems’ reasonable control.
4.8 Termination - iXsystems may cease any and all support, services, or maintenance under this Agreement without prior notice, or liability, and for any reason whatsoever, without limitation, if any of the terms and conditions of this Agreement are breached. Other provisions of this Agreement will survive termination including, without limitation, ownership provisions, warranty disclaimers, indemnity, and limitations of liability.
4.9 Open Source Software Components - iXsystems uses Open Source Software components in the development of the TrueNAS SCALE Software. Open Source Software components that are used in the TrueNAS SCALE Software are composed of separate components each having their own trademarks, copyrights, and license conditions.
4.10 Assignment - Licensee shall not assign or otherwise transfer any of its rights, or delegate or otherwise transfer any of its obligations or performance, under this Agreement, in each case whether voluntarily, involuntarily, by operation of law, or otherwise, without iXsystems’ prior written consent. No delegation or other transfer will relieve Licensee of any of its obligations or performance under this Agreement. Any purported assignment, delegation, or transfer in violation of this Section is void. iXsystems may freely assign or otherwise transfer all or any of its rights, or delegate or otherwise transfer all or any of its obligations or performance, under this Agreement without Licensee’s consent. This Agreement is binding upon and inures to the benefit of the parties hereto and their respective permitted successors and assigns.
5.0 Export Control Regulations
“The Product may be subject to export control laws. You shall not, directly or indirectly, export, re-export, or release the Product to, or make the Product accessible from, any jurisdiction or country to which export, re-export, or release is prohibited by law, rule, or regulation. You shall comply with all applicable laws, regulations, and rules, and complete all required undertakings (including obtaining any necessary export license or other governmental approval).”
6.0 Data Collection and Privacy
TrueNAS SCALE Software may collect non-sensitive system information relating to Your use of the Product, including information that has been provided directly or indirectly through automated means. Usage of TrueNAS SCALE Software, device status and system configuration are allowed according to iXsystems’ privacy policy.
TrueNAS SCALE Software will not collect sensitive User information including email addresses, names of systems, pools, datasets, folders, files, credentials.
By accepting this Agreement and continuing to use the Product, you agree that iXsystems may use any information provided through direct or indirect means in accordance with our privacy policy and as permitted by applicable law, for purposes relating to management, compliance, marketing, support, security, update delivery, and product improvement.
7.0 Limitation of Liability and Disclaimer of Warranty
THE PRODUCT IS PROVIDED “AS IS” AND WITH ALL FAULTS AND DEFECTS WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED UNDER APPLICABLE LAW, IXSYSTEMS, ON ITS OWN BEHALF AND ON BEHALF OF ITS AFFILIATES AND ITS AND THEIR RESPECTIVE LICENSORS AND SERVICE PROVIDERS, EXPRESSLY DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO THE PRODUCT, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, AND WARRANTIES THAT MAY ARISE OUT OF COURSE OF DEALING, COURSE OF PERFORMANCE, USAGE, OR TRADE PRACTICE. WITHOUT LIMITATION TO THE FOREGOING, IXSYSTEMS PROVIDES NO WARRANTY OR UNDERTAKING, AND MAKES NO REPRESENTATION OF ANY KIND THAT THE PRODUCT WILL MEET THE LICENSEE’S REQUIREMENTS, ACHIEVE ANY INTENDED RESULTS, BE COMPATIBLE, OR WORK WITH ANY OTHER SOFTWARE, APPLICATIONS, SYSTEMS, OR SERVICES, OPERATE WITHOUT INTERRUPTION, MEET ANY PERFORMANCE OR RELIABILITY STANDARDS OR BE ERROR FREE, OR THAT ANY ERRORS OR DEFECTS CAN OR WILL BE CORRECTED.
TO THE FULLEST EXTENT PERMITTED UNDER APPLICABLE LAW: (A) IN NO EVENT WILL IXSYSTEMS OR ITS AFFILIATES, OR ANY OF ITS OR THEIR RESPECTIVE LICENSORS OR SERVICE PROVIDERS, BE LIABLE TO LICENSEE, LICENSEE’S AFFILIATES, OR ANY THIRD PARTY FOR ANY USE, INTERRUPTION, DELAY, OR INABILITY TO USE THE PRODUCT; LOST REVENUES OR PROFITS; DELAYS, INTERRUPTION, OR LOSS OF SERVICES, BUSINESS, OR GOODWILL; LOSS OR CORRUPTION OF DATA; LOSS RESULTING FROM SYSTEM OR SYSTEM SERVICE FAILURE, MALFUNCTION, OR SHUTDOWN; FAILURE TO ACCURATELY TRANSFER, READ, OR TRANSMIT INFORMATION; FAILURE TO UPDATE OR PROVIDE CORRECT INFORMATION; SYSTEM INCOMPATIBILITY OR PROVISION OF INCORRECT COMPATIBILITY INFORMATION; OR BREACHES IN SYSTEM SECURITY; OR FOR ANY CONSEQUENTIAL, INCIDENTAL, INDIRECT, EXEMPLARY, SPECIAL, OR PUNITIVE DAMAGES, WHETHER ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, REGARDLESS OF WHETHER SUCH DAMAGES WERE FORESEEABLE AND WHETHER OR NOT IXSYSTEMS WAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES; (B) IN NO EVENT WILL IXSYSTEMS’ AND ITS AFFILIATES’, INCLUDING ANY OF ITS OR THEIR RESPECTIVE LICENSORS’ AND SERVICE PROVIDERS’, COLLECTIVE AGGREGATE LIABILITY UNDER OR IN CONNECTION WITH THIS AGREEMENT OR ITS SUBJECT MATTER, UNDER ANY LEGAL OR EQUITABLE THEORY, INCLUDING BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, AND OTHERWISE, EXCEED THE TOTAL AMOUNT PAID TO IXSYSTEMS PURSUANT TO THIS AGREEMENT FOR THE PRODUCT THAT IS THE SUBJECT OF THE CLAIM; (C) THE LIMITATIONS SET FORTH IN THIS SECTION SHALL APPLY EVEN IF THE LICENSEE’S REMEDIES UNDER THIS AGREEMENT FAIL OF THEIR ESSENTIAL PURPOSE.
You hereby acknowledge that you have read and understand this Agreement and voluntarily accept the duties and obligations set forth herein by clicking accept on this Agreement.
Software Development Life Cycle
The TrueNAS Software Development Life Cycle (SDLC) is the process of planning, creating, testing, deploying, and maintaining TrueNAS releases.
Determine the objectives, nature, and scope of future versions of the software.
This involves gathering feedback and interpreting customer needs and requirements, diagnosing existing problems, and weighing the pros and cons of potential solutions.
The end result is a list of recommended improvements to be integrated into a future TrueNAS version.
Required and planned changes are investigated in detail and development steps are determined.
Proposed alterations are reviewed by peers for completeness, correctness, and proper coding style.
TrueNAS developers then begin implementing proposed TrueNAS changes.
Code is integrated into the existing TrueNAS source tree, then built and tested by multiple TrueNAS teams and those Community users willing to experiment with early development TrueNAS builds.
TrueNAS documentation contributors also begin evaluating these early builds and write public-facing content about the changes to TrueNAS in the new version.
These teams verify all requirements and objectives are properly met and the updated software is reliable and fault-tolerant, according to the predetermined requirements.
If issues are found, TrueNAS features are reworked to meet the development requirements.
Simultaneously, a security evaluation of the TrueNAS code is completed, with any discovered issues sent to the TrueNAS development team for resolution.
Any security notices, errata, or best practices are also drafted for inclusion on the TrueNAS Security website.
The new release of TrueNAS is evaluated to determine further feature development, bug fixes, or security vulnerability patches.
During this stage, security patches and software erratum are corrected, updated versions of existing branches are pushed, and feedback is solicited for future versions of the software.
This life cycle is generally applied to TrueNAS major versions released to the Community.
For Enterprise customers, releases are evaluated for Enterprise deployment suitability according to different criteria of internal testing on commercial hardware, security topics, upgradability, and general software stability as derived from Community usage.
A formal software End of Life (EoL) is not defined, as TrueNAS releases can be used in a stable manner for extended lengths of time, depending on use case and security risk factors.
However, general guidance advises users to evaluate the latest major version point release against your usage mindset.
The TrueNAS Team provides TrueNAS Software Status for specific recommendations on which software version to use, according to generalized user mindsets.
TrueNAS Data Collection Statement
TrueNAS collects non-sensitive system data and relays the data to a collector managed by the TrueNAS team.
This system data collection is enabled by default and can be disabled in the web interface under System > General > GUI > Usage collection & UI error reporting.
The protocol for system data collection uses the same TCP ports as HTTPS (443) and passes through most firewalls as an outgoing web connection.
If a firewall blocks the data collection or the data collection is disabled, there is no adverse impact to the TrueNAS system.
When Usage collection & UI error reporting is disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g. TrueNAS 24.04.0, 55 TB) are still collected.
Information about system configuration and usage is not collected.
When enabled, anonymous usage statistics and WebUI errors are reported to TrueNAS engineering team. No personally identifiable information is collected.
TrueNAS collects this data and uses it to identify the quality and operational trends in the fleet of TrueNAS systems used by the entire community, to identify issues, plan for new features, and determine where to invest resources for future software enhancements.
The non-sensitive system data collected is clearly differentiated from sensitive user data that is explicitly not collected by TrueNAS.
This table describes the differences:
Sensitive User Data (NOT COLLECTED)
Non-Sensitive System Data (Optionally Collected)
Description
Any data that includes user identity or business information
Data that only includes information about the TrueNAS system and its operation
Frequency
NEVER
Daily
Examples
Usernames, passwords, email addresses
Anonymous hardware inventory, faults, statistics, Pool configuration
User-created System and dataset names
Software versions, firmware versions
Directory, files names, user data
Services and features enabled, Usage and Performance statistics, WebUI errors
Reviewing Usage Collection
To review system usage data collected by TrueNAS, access the system shell via SSH or the console and enter midclt call usage.gather.
This command returns the same statistics that are transmitted to the TrueNAS team when Usage collection is enabled.
TrueNAS does not collect any user-defined names for servers, pools, datasets, shares, files, applications/jails, processes, and similar.
Applications do transmit chart release names for deployed applications (e.g. “minio/2.0.6”) but not user-defined names.
While usage collection gathers only non-sensitive system data, sensitive user data is included in a TrueNAS-generated debug file, such as those requested for a bug report, feature request, or other troubleshooting.
Always store debug files in a secure location.
Please review debugs and redact any sensitive information before sharing with external entities.
The TrueNAS Privacy Policy contains a detailed statement of our commitment to data privacy.
TrueNAS Tutorials
This guide collects various how-tos for both simple and complex tasks using primarily the TrueNAS web interface.
Tutorials are organized parallel to the TrueNAS web interface structure and grouped by topic.
Tutorials are living articles and continually updated with new content or additional in-depth tutorials that guide in unlocking the full potential of TrueNAS.
To display all tutorials in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
TrueNAS Tutorials
⎙ Download or Print: View all TrueNAS Tutorials as a single page for download or print.
Top Toolbar: Tutorials about options available from the TrueNAS top toolbar.
Using UI Global Search: This tutorial shows how to use the Global Search feature to explore the TrueNAS UI and documentation.
Managing API Keys: This tutorial shows how to add, create, or edit an API key in TrueNAS and access API Documentation.
Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.
Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.
Storage Encryption: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.
Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.
Shares: Tutorials for configuring the various data sharing features in TrueNAS.
AFP Migration: Provides information on migrating AFP shares from FreeBSD- to Linux-based TrueNAS versions.
Block Shares (iSCSI): Describes the iSCSI protocol and has tutorials for various configuration scenarios.
Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.
Multiprotocol Shares: Provides instructions on setting up SMB and NFSv4 mixed-mode shares.
Windows Shares (SMB): Provides information on SMB shares and instructions on creating a basic share and setting up various specific configurations of SMB shares.
NVMe-oF Subsystems: Provides information on NVMe-oF subsystems and instruction on creating a subsystem and setting up enterprise configurations of subsystems.
Data Protection: Tutorials related to configuring data backup features in TrueNAS.
Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.
Cloud Sync Tasks: Tutorials for configuring and managing data backups to from TrueNAS to various 3rd party Cloud Service Providers.
Configuring Rsync Tasks: Provides instructions on adding rsync tasks with two methods, SSH connection and module.
Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.
Configuring Static Routes: Provides instructions on configuring a static route using the TrueNAS web UI.
Setting Up IPMI: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.
Accessing NAS from VMs and Containers: Provides instructions on how to create a bridge interface for virtual machines or applications and provides Linux and Windows examples.
Credentials: Tutorials for configuring the different credentials needed for TrueNAS features.
Using Administrator Logins: Explains role-based administrator logins and functions. Provides instructions on configuring SSH and working with the admin and root user passwords.
Managing Users: Provides instructions on adding and managing administrator and user accounts.
Managing Groups: Provides instructions on adding and managing groups.
Backup Credentials: Backup credential tutorials for integrating TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about adding and managing certificates, CSRs, CAs, and ACME DNS-Authenticators in TrueNAS.
Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.
Containers: Tutorials for configuring the TrueNAS Containers feature, creating, and managing containers.
Virtual Machines: Tutorials for configuring TrueNAS SCALE virtualization features and creating virtual machines.
Reporting: Provides information on changing settings that control how TrueNAS displays report graphs, how to interact with graphs, and configuring reporting exporters.
System Settings: Tutorials for configuring the system management options in the System Settings area of the TrueNAS web interface.
Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.
Using Shell: Provides information on using the TrueNAS shell.
Using Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.
Top Toolbar
The TrueNAS top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI.
Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens.
It also shows the name of the user currently logged into the system to the left of the Settings icon.
You can also collapse or expand the main function menu on the left side of the screen.
The Search UI global search bar allows users to search for screens and elements within the TrueNAS UI or to redirect search terms to the TrueNAS Documentation Hub.
Searching UI Fields
Click the Search UI bar or type Ctrl + / to select the UI global search.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
TrueNAS
The TrueNAS logo returns to the Dashboard from any other screen.Send Feedback
TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.
To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window.
Alternatively, go to System > General Settings and click File Ticket on the Support widget.
Rating a UI Screen
Click Rate this page to send feedback on a UI page.
You can include a screenshot of the current page and/or upload additional images with your comments.
You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.
Click Report a bug to create an engineering ticket when a TrueNAS screen or feature is not working as intended.
This submits the ticket directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click Report a bug to see the fields to create an engineering ticket for system errors, bugs, or unexpected behavior.
For example, report a bug where a middleware error and traceback occurred while saving a configuration change.
Enter a descriptive summary in the Subject.
For example, if a configuration change does not update after clicking Save and you get an error message or traceback after attempting the change, enter XYZ setting fails to save with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
I clicked the edit XYZ settings option, modified the XYZ setting, and clicked Save. The operation failed and showed the following traceback message: [include the traceback text]. My system is running TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to speed up the issue resolution.
Select Attach debug.
To attach a screenshot of the current page, select Take screenshot of the current page.
Or, before using this form, take screenshots of the screen, traceback or other error message, copy a log into a text file, or create any other file to attach.
Open this form and attach those files by selecting Attach additional images and clicking Choose File to open a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
TrueNAS displays a message telling users to check their email for verification instructions.
Status of TrueNAS Connect
TrueNAS provides quick access to TrueNAS Connect from the top toolbar in your TrueNAS system.
The Status of TrueNAS Connect icon opens the TrueNAS Connect dialog.
Before you sign up for TrueNAS Connect, the dialog shows it is waiting to connect.
After connecting to TrueNAS Connect and registering the system, the Status of TrueNAS Connect icon shows an active status indicator.
The TrueNAS Connect dialog shows the status of the active connection.
Click Open TrueNAS Connect to open the TrueNAS Connect management interface.
Click cloud_offDisable Service to disconnect the system from TrueNAS Connect.
Click on either service to go to its configuration screen.
Jobs
The Running Jobsassignment icon button opens the Running Jobs window showing a minimized view of all running, waiting, and failed jobs/processes.
Hover the mouse over an error job to view a pop-up window with the error message for that failed job.
Click the minus (-) at the top right corner of any dialog or pop-up window to minimize a job/process.
Click on a running job to open a dialog for that job.
A running job shows a progress bar and a stop_circle button to the right of the job. Click on this to show the Abort dialog.
Click Abort to stop the job and abort the process.
Beginning in 25.04, the Abort option is only available for select jobs. Jobs that are unable to be aborted are listed without the stop_circle button as an option.
Click on Go to Jobs to open the Jobs screen with tabs to screens listing all successful, active, or failed and aborted jobs.
Click on the All, Active, or Failed button at the top of the screen to show the log of jobs that fit that classification.
Click View next to a task to see the log information and error message for that task.
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Settings
The Settingsaccount_circle icon opens a dropdown list of options to change passwords, modify two-factor authentication settings (when configured), create and manage API keys, access the TrueNAS documentation, and to log out of the TrueNAS UI.
Change Password
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
My API Keys
Click on My API Keyslaptop to go to the User API Keys screen.
API keys identify an outside resource or application without a principal.
For example, when adding a new system to TrueCommand if you are required to add an API key to authenticate the system.
Use this function to create an API key for this purpose.
Click API Docs to access the API documentation portal with information on TrueNAS API commands.
See API Keys for more information on adding or managing API keys.
See API Keys for more information on adding or managing API keys.
Guide
Click on Guidelibrary_books to open the TrueNAS Documentation Hub in a new tab.
Log Out
Log Out logs the current user out of the TrueNAS UI, but does not power off the system.
The Read-Only Admin and Sharing Admin roles only have access to the Log Out option.Power Options
Click the Powerpower_settings_new button to open the dropdown list of power options.
Restart logs you out of the TrueNAS UI and restarts the server. Shut Down logs you out of the TrueNAS UI and powers off the system as though you pressed the power button on the physical server.
TrueNAS Enterprise
Please consult your specific hardware documentation to find notes about possible hardware-specific controls for power-on or off behaviors.
With the implementation of administrator roles, the power options are locked based on the level of privileges for the administrator role.
The full administrator has access to both power options, but read-only and sharing admin roles do not.
The power options that show a lock icon indicate the function is not permitted.
Content
Using UI Global Search: This tutorial shows how to use the Global Search feature to explore the TrueNAS UI and documentation.
Managing API Keys: This tutorial shows how to add, create, or edit an API key in TrueNAS and access API Documentation.
TrueNAS 24.10 (Electric Eel) introduces global search function that allows users to quickly access screens and management functions across the TrueNAS UI.
Global search also allows users to redirect queries to the TrueNAS Documentation Hub to retrieve relevant documentation.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
User-linked API keys allow administrators to configure per-user access to the TrueNAS API.
Keys are revocable. You can also configure them to expire on a preset date.
Click laptopMy API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen.
The User API Keys screen shows a table listing API keys added to the system, and allows adding, searching for, editing, or deleting keys.
Click API Docs to view API Documentation embedded within the system.
TrueNAS Connect API Keys
TrueNAS Connect automatically creates an API key when you register your system in the TrueNAS Connect service. TrueNAS uses this key, shown on the User API Key screen, to authenticate with the TrueNAS Connect service.
There are instances where you might see more than one tnc key listed.
If you delete a tnc API key, the TrueNAS Connect prompts you to re-authenticate the next time you connect to the service.
Adding an API Key
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
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.
Select My API Keys from the Settings dropdown on the top toolbar.
Alternatively, you can go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.
If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.
Enter a descriptive name for the key.
Select an administrative user to associate with this key from the Username dropdown.
To add a user API key token that does not expire (no expiration date), leave Non-expiring enabled.
A non-expiring key remains active until it is manually revoked or changed to expire.
To create a key with a scheduled expiration, disable Non-expiring by clearing the checkbox.
Click on the calendar icon in the Expires On field and select the expiration date. The field does not allow typing a date.
The token only shows in the API Key dialog.
To save the key for use as an authentication token, click Copy to Clipboard, paste it into a text file, then save the fle in a secure location.
Can I view the API Key again after closing the API Key dialog?
You cannot view the API key string after closing the API Key dialog.
If you close the dialog before copying the key, select the user row and click Edit to open the Edit API Key screen.
Select Reset. TrueNAS opens the API Key dialog showing a new key string. Copy the key before closing the dialog.
Remember to update settings using the API key token.
Click Close to return to the User API Keys screen.
Migrating API Keys
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.
Editing an API Key
Select the user row and then click edit edit to open the Edit API Key screen.
To remove the existing API key string and generate a new random key, select Reset.
The API Key dialog opens, showing a new key string.
Click Copy to Clipboard to copy the token, then paste it into a text file and save it in a secure location.
Update any clients using the reset API Key with the new key string.
Deleting an API Key
Click delete delete for any API key on the list to remove that key.
TrueNAS opens a Delete API Key dialog.
Click API Docs on the User or User API Keys screen to access the TrueNAS API documentation built into the system.
A new browser window opens, showing the API documentation Table of Contents.
Click the link for the content you want to access:
JSON-RPC 2.0 over WebSocketAPI shows an overview of the JSON-RPC 2.0 format with example objects.
API Methods shows a table of contents listing TrueNAS API methods
API Events shows the list of API methods with query call options
Jobs shows an overview of the job options, uploading/downloading file example scripts, and information on running a query for job status.
Query Methods shows query basic usage, supported operators, and information on query operations and syntax.
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 midclt and 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.
For more information on the API documentation see API Reference.
Shutting Down TrueNAS Enterprise HA
TrueNAS Enterprise
This procedure applies to TrueNAS Enterprise High Availability (HA) systems only.
Some TrueNAS models do not support using the UI Shutdown option on the power menu.
Instead of shutting down the server, it only reboots.
To shut down a TrueNAS Enterprise HA system, log into the IPMI connections for each controller and use the Console Setup menu option to shut down the system.
Selecting the TrueNAS UI Shutdown option in the power menu to shut down the HA system only causes the system to fail over to the standby controller.
Shutting Down a TrueNAS HA System
Disabling failover in the TrueNAS UI is unnecessary and only creates uncertainty about which controller comes up as the active controller when you power up the HA system.
Sign in to the IPMI connections to both the active and standby controllers.
Shut down the standby controller using the Console Setup menu Shutdown option.
Shut down the active controller.
Powering Up a TrueNAS HA System
After shutting down the TrueNAS System, use the IPMI remote controls to power up the servers, starting with the active controller.
Log in to the IPMI connections for both servers.
Use the remote power control options to start controller 1 (active controller).
Use the remote power control options to start controller 2 (standby controller).
Wait for the TrueNAS UI to come up, then use the VIP IP address or hostname to log into the UI.
Check the main dashboard to see which controller is active. Controller 1 should be the active controller, but if not, fail over the system and recheck to make sure it is the active controller.
Click on the layout image you want to use. The image on the screen show the new card layout.
If adding a new card, the default layout is full size with the category and type set to Empty.
If editing an existing card, the current layout changes to show the existing category and type in the first card of the new layout.
An error shows in the selected card of the group if the card size does not support the selected category and type.
Select the card in the group you want to add or change.
If the layout includes half and/or quarter size cards, the first card in the group is selected by default.
To configure another card in the layout, select the position in the group you want to configure.
Select the Card Category and Card Type to apply to the selected card.
For example, if configuring a network card, you can use one full size layout or select one with half and quarter size cards.
The example below shows two layout options for configuring a network card.
If the selected category is not supported for the selected card, either select a new layout or change the Card Category and/or Card Type to one the card supports.
To show an installed app, select Apps as the Card Category, select a Card Type, and then select the app from the Application dropdown list.
The Application card type needs a full-size layout.
(Optional) Edit the next card in the selected layout.
After adding or changing the card category and type, either click on the next card in the group to configure it.
Click Save to close the Card Editor and return to the Dashboard.
Edit or add as many cards as you want.
Click Save at the top right of the Dashboard screen to save all changes and exit configuration mode.
To exit configuration mode without saving changes, click Cancel.
Deleting a Card
To delete a card from the Dashboard screen, click Configure to put the screen into configuration mode.
Click the Delete icon on the card to delete it and remove it from the screen.
Click Save at the top right of the screen. The screen exits configuration mode and the Dashboard no longer shows the card.
Managing Apps from the Dashboard
App cards include buttons in the card header that let you open and manage an app without leaving the Dashboard.
Click the web portal button to open the main web portal for the app in a new browser tab.
If the app has more than one web portal, click the Other Portals arrow next to it and select the portal you want to open.
Click Restart App to restart the app. The button is not available while the app is deploying.
Click Check App Details to open the details for the app on the Installed apps screen.
Storage
The TrueNAS Storage section has controls for pools, snapshots, and disk management.
This section also provides access to datasets, zvols, quotas, and permissions.
Use the Import Pool button to reconnect pools exported/disconnected from the current system or created on another system.
This also reconnects pools after users reinstall or upgrade the TrueNAS system.
Use the Disks button to manage, wipe, and import storage disks that TrueNAS uses for ZFS data storage.
Use the Create Pool to create ZFS data storage “pools” from physical disks. Pools efficiently store and protect data.
The Storage screen displays all the pools added to the system.
Each pool shows statistics and status, along with buttons to manage the different elements of the pool.
The articles in this section offer specific guidance for the different storage management options.
Storage Articles
Import Pool: Provides information on ZFS importing for storage pools in TrueNAS. It also addresses GELI-encrypted pools.
Disks: Articles with instructions for managing, replacing, and wiping disks.
Replacing Disks: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.
Wiping a Disk: Provides instructions for wiping a disk.
Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.
Create Pool: Provides background considerations and a simple tutorial on creating storage pools in TrueNAS.
Fusion Pools: Provides information on setting up and using fusion pools.
Managing Pools: Provides instructions on managing storage pools, VDEVs, and disks in TrueNAS.
Import Pool
ZFS pool importing works for pools exported or disconnected from the current system, those created on another system, and for pools you reconnect after reinstalling or upgrading the TrueNAS system.
The import procedure only applies to disks with a ZFS storage pool.
TrueNAS supports pool imports using the WebUI or API only.
Manual pool import via command line can cause unexpected behavior and system issues.
Do I need to do anything different with disks installed on a different system?
When physically installing ZFS pool disks from another system, use the zpool export poolname command in the Linux command line or a web interface equivalent to export the pool on that system.
Shut down that system and move the drives to the TrueNAS system.
Shutting down the original system prevents an in use by another machine error during the TrueNAS import.
To import a pool, go to the Storage Dashboard and click Import Pool at the top of the screen.
TrueNAS detects the pools that are present but not connected and adds them to the Pools dropdown list.
Select a pool from the Pool dropdown list, then click Import.
Can I import GELI-encrypted pools?
GELI encryption is specific to FreeBSD so Linux-based TrueNAS cannot import GELI-encrypted pools.
See the GELI Pool Migrations section in the TrueNAS 13.0 Storage Encryption article.
The Preparing to Migrate article provides information on what you can and cannot migrate and a checklist of actions to take before migrating from TrueNAS 13.0 (or 13.3 for community users) with GELI-encrypted pools to 24.04.
Disks
To manage disks, go to Storage and click Disks on the top right of the screen to open the Disks screen.
To view details on a disk, click on the disk to expand it. Select Edit to open the Edit Disk screen.
The Disks screen lets users edit disks or delete obsolete data off an unused disk.
Contents
Replacing Disks: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.
Wiping a Disk: Provides instructions for wiping a disk.
Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.
Hard drives and solid-state drives (SSDs) have a finite lifetime and can fail unexpectedly.
When a disk fails in a Stripe (RAID0) pool, you must recreate the entire pool and restore all data backups.
We always recommend creating non-stripe storage pools that have disk redundancy.
To prevent further redundancy loss or eventual data loss, always replace a failed disk as soon as possible!
TrueNAS integrates new disks into a pool to restore it to full functionality.
TrueNAS requires you to replace a disk with another disk of the same or greater capacity as a failed disk.
You must install the disk in the TrueNAS system.
It should not be part of an existing storage pool.
TrueNAS wipes the data on the replacement disk as part of the process.
Disk replacement automatically triggers a pool resilver.
This tutorial includes instructions for replacing a failed disk in TrueNAS systems with and without an available hot spare.
To replace a disk in a pool without a hot spare available:
If you configure your main TrueNAS Dashboard to include an individual Pool or the Storage widgets, they show the status of your system pools as on or offline, degraded, or in an error condition.
From the main Dashboard, you can click the on either the Pool or Storage widget or you can click Storage on the main navigation menu to open the Storage Dashboard screen and locate the pool in the degraded state.
My disk is faulted. Should I replace it?
If a disk shows a faulted state, TrueNAS has detected an issue with that disk and you should replace it.Can I use a disk that is failing but still active?
There are situations where you can leave a disk that has not completely failed online to provide additional redundancy during the replacement procedure.
We do not recommend leaving failed disks online unless you know the exact condition of the failing disk.
Attempting to replace a heavily degraded disk without offlining it significantly slows down the replacement process.
Taking a Failed Disk Offline
We recommend users off-line a disk before starting the physical disk replacement.
Offlining a disk removes the device from the pool and can prevent swap issues.
To offline a disk:
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click next expand the VDEV, then look for the disk with the REMOVED status.
Click on the failed disk, then click Offline in the ZFS Info widget to take the disk offline.
The disk status changes to OFFLINE.
The offline failed?
If the off-line operation fails with a Disk offline failed - no valid replicas message, go to Storage Dashboard and click Scrub on the ZFS Health widget for the pool with the degraded disk. The Scrub Pool confirmation dialog opens. Select Confirm and then click Start Scrub.
When the scrub operation finishes, return to the VDEVs screen, expand the VDEV, then click the disk, and try to offline it again.
After offlining the failed disk, physically remove it from the system.
Replacing a Failed Disk Without a Hot Spare
After taking the failed disk offline and physically removing it from the system, insert the replacement disk now.
The new disk must have the same or greater capacity as the failed disk.
If replacing a failed disk with an available disk in the system, proceed to the next step.
Click Replace on the Disk Info widget on the Devices screen for the disk you off-lined.
Select the new drive from the Member Disk dropdown list on the Replacing disk dialog.
Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
Preserve disk description maintains any descriptions associated with the original disk, which prevents you from needing to copy descriptors to the new disk manually. This option is enable by default. Select to clear the checkmark if you want the replacement disk to use descriptors that differ from those attached to the original disk.
Click Replace Disk to add the new disk to the VDEV and bring it online.
Disk replacement fails when the selected disk has partitions or data present.
To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.
When the disk wipe completes, TrueNAS starts replacing the failed disk.
TrueNAS resilvers the pool during the replacement process.
For pools with large amounts of data, this can take a long time.
When the resilver process completes, the pool status returns to Online on the Devices screen.
Refresh the screen to ensure the replacement disk appears in the pool as expected.
Replacing a Failed Disk With a Hot Spare
A Hot Spare vdev sets up drives as reserved to prevent larger pool and data loss scenarios.
TrueNAS automatically inserts an available hot spare into a Data vdev when an active drive fails.
TrueNAS resilvers the pool after the hot spare is activated.
Detaching a Failed Disk
After taking the failed disk offline and physically removing it from the system, go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click next to the VDEV to expand it, then look for the disk with the REMOVED status.
Click Detach on the ZFS Info widget on the VDEVs screen for the disk you off-lined.
Select Confirm, then click Detach.
TrueNAS detaches the disk from the pool and promotes the hot spare disk to a full member of the pool.
Refresh the screen to ensure the promoted hot spare appears in the pool as expected.
Recreating a Hot Spare
After promoting the hot spare, recreate the Spare vdev and assign a disk to it.
Do I really need to promote the hot spare and then recreate the spare vdev?
If you have a hot spare inserted into the pool and then follow the instructions in Replacing a Failed Disk Without a Hot Spare, TrueNAS automatically returns the hot spare disk to the existing Spare vdev and ONLINE status.
However, we do not recommend this method because it causes two resilver events: one when activating the hot spare and again when replacing the failed disk.
Resilvering degrades system performance until completed and causes unnecessary strain on the disk.
To avoid unnecessary resilvers, promote the hot spare by [detaching the failed disk]](#detaching-a-failed-disk) then recreate the hot spare vdev.
If recreating the spare with a replacement in place of the failed disk, insert the replacement disk now.
The new disk must have the same or greater capacity as the failed disk.
If recreating the spare with an available disk in the system, proceed to the next step.
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click Add VDEV to open the Add Vdevs to Pool screen.
Select a disk size equal to or greater than the failed disk or click Manual Disk Selection to choose the replacement disk.
Click Save And Go To Review.
Review changes, then click Update Pool.
Select Confirm, then click Continue.
After completing the job, TrueNAS returns to the Storage Dashboard screen.
Review Spare VDEVs on the VDEVs widget to confirm the hot spare is added.
Wiping a Disk
The disk wipe option deletes obsolete data from an unused disk.
Wipe is a destructive action and results in permanent data loss!
Back up any critical data before wiping a disk.
TrueNAS only shows the Wipe option for unused disks.
Ensure you have backed-up all data and are no longer using the disk.
Triple check that you have selected the correct disk for the wipe.
Recovering data from a wiped disk is usually impossible.
Click Wipe to open a dialog with additional options:
Quick erases only the partitioning information on a disk without clearing other old data, making it easy to reuse. Quick wipes take only a few seconds.
Full with zeros overwrites the entire disk with zeros and can take several hours to complete.
Full with random overwrites the entire disk with random binary code and takes even longer than the Full with zeros operation to complete.
After selecting the appropriate method, click Wipe and confirm the action. A Confirmation dialog opens.
Verify the name to ensure you have chosen the correct disk. When satisfied you can wipe the disk, set Confirm and click Continue.
Continue starts the disk wipe process and opens a progress dialog with the Abort button.
Abort stops the disk wipe process. At the end of the disk wipe process a success dialog displays.
Close closes the dialog and returns you to the Disks screen.
For more general information on SLOG disks, see SLOG Devices.
Because this is a potentially disruptive procedure, contact TrueNAS Enterprise Support to review your overprovisioning needs and schedule a maintenance window.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later).
SED configuration options are not visible in the TrueNAS Community Edition.
Community users wishing to implement SEDs can continue to do so using the command line sedutil-cli utility.
Note: Additional changes to SED management options in the TrueNAS UI ahead of the 25.04.0 release version, with documentation updates to follow.
Supported Specifications
Legacy interface for older ATA devices (Not recommended for security-critical environments!)
TCG Pyrite Version 1 and Version 2 are similar to Opalite, but with hardware encryption removed
Pyrite provides a logical equivalent of the legacy ATA security for non-ATA devices. Only the drive firmware protects the device.
Pyrite Version 1 SEDs do not have PSID support and can become unusable if the password is lost.
TCG Enterprise is designed for systems with many data disks.
These SEDs cannot unlock before the operating system boots.
See this Trusted Computing Group and NVM Express® joint white paper for more details about these specifications.
TrueNAS Implementation
TrueNAS implements the security capabilities of sedutil-cli for TCG-compliant devices.
You can configure a SED before or after assigning the device to a pool.
By default, SEDs are not locked until the administrator takes ownership of them.
Ownership is taken by explicitly configuring a global or per-device password in the web interface and adding the password to the SEDs.
Adding SED passwords in the web interface also allows TrueNAS to automatically unlock SEDs on boot.
A password-protected SED protects the data stored on the device when the device is physically removed from the system.
This allows secure disposal of the device without having to first wipe the contents.
Repurposing a SED on another system requires the SED password or a full cryptographic erase with PSID revert.
Deploying SEDs
TrueNAS supports setting a global password for all detected SEDs or setting individual passwords for each SED.
Using a global password for all SEDs is strongly recommended to simplify deployment and avoid maintaining separate passwords for each SED.
SED passwords are used during initial setup and for unlocking SEDs.
A system configuration backup includes SED passwords only when you download the configuration file with the Export Password Secret Seed option selected.
For a full list of what a configuration backup includes, see Configuration Backup Contents.
Configuring Global SED Settings
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive widget.
Select the user to unlock SEDs from the ATA Security User dropdown list.
Options are USER or MASTER.
Enter the global SED password in SED Password and in Confirm SED Password.
Click Save.
Remember SED passwords!
If you lose the SED password, you cannot unlock SEDs or access their data.
After configuring or modifying SED passwords, always record and store them in a secure location!
Check SED Functionality
When SED devices are detected during system boot, TrueNAS checks for configured global and device-specific passwords.
Unlocking SEDs allows a pool to contain a mix of SED and non-SED devices.
Devices with individual passwords are unlocked with their password.
Devices without a device-specific password are unlocked using the global password.
Managing SED Disks and Data
Improper use of the sedutil-cli can be destructive to data and passwords.
Keep backups and use with caution.
Additional SED management options are available using a shell session and the sedutil-cli utility.
Enter sedutil-cli -h or see the sedutil-cli.8 man page for more information.
TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial setup and management of SEDs using sedutil-cli.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Drive Health Management (DHM) in TrueNAS monitors the condition of installed HDD and SSD drives (SAS, SATA, and NVMe) and alerts you when action is required. TrueNAS manages drive health with three layers:
ZFS detects sudden failures in real time during active read and write operations.
TrueNAS Middleware automatically polls SMART (Self-Monitoring, Analysis, and Reporting Technology) data in each drive.
TrueNAS Middleware handles the alert logic and provides actionable notifications.
TrueNAS DHM is designed to:
Minimize data loss from drive failures.
Provide actionable alerts and support drive replacement workflows.
Predict failures with low false-positive rates.
Extend drive and system lifespan.
Keep configuration simple and automated.
Minimize performance impact on drives and CPU.
Enterprise Considerations
Enterprise deployments benefit from additional protections and processes built around DHM:
Factory burn-in testing (running drives at sustained load before deployment) significantly reduces failure rates.
TrueNAS DHM is designed to scale across large drive counts (1000+) without increasing administrator and system resource overheads.
When an alert appears, review the alert details to determine the recommended action.
For guidance on drive replacement or interpreting a specific alert condition, contact iXsystems support.
How DHM Works in TrueNAS 25.10 and Later
SMART Integration
TrueNAS integrates SMART stats collection directly into the middleware, which provides consistent handling across all supported drive types and vendors.
SMART polls drives every 90 minutes. When a polled attribute crosses a threshold indicating a likely failure, TrueNAS alerts the user.
ZFS as Real-Time Failure Detection
ZFS acts as the primary detector for sudden, unexpected drive failures.
Unlike SMART polling, which runs on a schedule, ZFS detects failures immediately when a read or write operation returns an error.
When ZFS encounters an unrecoverable error, it marks the affected VDEV or disk as faulted and generates an alert.
ZFS and SMART work together: SMART catches degrading drives before they fail, while ZFS catches drives that fail without prior warning.
Alert Logic
TrueNAS evaluates incoming SMART data and ZFS events against alert rules before generating a notification.
This filtering suppresses known-benign attribute fluctuations and only notifies users about conditions that require attention, reducing false-positive alerts by approximately 50% compared to prior releases.
Alert Levels can be adjusted to control notification severity.
Higher-priority alerts appear in the Alerts panel and can trigger configured alert services (email, SNMP, etc.).
TrueNAS configures automated temperature alerts based on the specified maximum operating temperature of each drive.
If a drive reports a temperature that exceeds its rated maximum, TrueNAS generates an alert.
Monitoring Drive Health
To view drive health status, go to the Storage dashboard and view the Disk Health card.
Active alerts appear in the Alerts panel at the top right of the UI.
Click an alert to expand it and view details, including the affected disk, the attribute or event that triggered the alert, and recommended next steps.
Alert Types
Type
Description
SMART Stat
A drive-reported diagnostic value crossed a failure threshold. The alert identifies the specific attribute (for example, Reported Uncorrectable Error) and the current value.
ZFS Event
ZFS detected an I/O error or checksum failure during a read or write operation. These alerts indicate the disk might have failed or is failing.
Temperature
Drive temperature exceeded the rated maximum from the manufacturer specification.
SMART Test Options for Community Edition
TrueNAS handles SMART testing through its automated DHM polling.
The manual SMART test options described in this section are primarily intended for Community Edition users who want additional drive validation beyond the automated 90-minute polling.
Cron Jobs
You can schedule manual SMART tests using Cron Jobs in the TrueNAS UI.
TrueNAS logs cron job output. Review the system log or configure the cron job to send output to a file for later review.
Manual Drive Tests
The manual SHORT test performs a quick, surface-level diagnostic check. It typically completes within a few minutes and has minimal performance impact on drives used in a ZFS pool. It is suitable for nightly or weekly scheduling as a routine check.
The manual LONG test performs a full drive surface scan for periodic, deep validation. It provides a thorough validation of the entire drive surface, but has a significant negative performance impact during the test. LONG tests can also produce false-positive failure results on healthy drives.
TrueNAS 25.10+ has an unsupported API call it can leverage to start a SMART test on all drives with the default parameters. Use at your own risk or switch to a custom smart command where advanced options are required for stability or functionality.
To run the command, use
midclt call disk.smart_test {SHORT|LONG} '["*"]'
Third-Party Tools
Additional drive introspection and analysis tools are available outside of TrueNAS.
These tools can supplement DHM data with more detailed vendor-specific diagnostics.
Consult the documentation for any third-party tool before running it against drives in an active ZFS pool.
Create Pool
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
What is a pool?
Storage pools attach drives organized into virtual devices called VDEVs.
Drives arranged inside VDEVs provide varying amounts of redundancy and performance.
ZFS and VDEVs combined create high-performance pools that maximize data lifetime.
ZFS and TrueNAS periodically review and heal when discovering a bad block in a pool.
Reviewing Storage Needs
We strongly recommend that you review your available system resources and plan your storage use case before creating a storage pool. Considerations:
Allocating more drives to a pool increases redundancy when storing critical information.
Maximizing total available storage at the expense of redundancy or performance entails allocating large-volume disks and configuring a pool for minimal redundancy.
Maximizing pool performance entails installing and allocating high-speed SSD drives to a pool.
RAIDz pool layouts are well-suited for general use cases and especially smaller (<10) data VDEVS or storage scenarios that involve storing multitudes of small data blocks.
dRAID pool layouts are useful in specific situations where large disk count (>100) arrays need improved resilver times due to increased disk failure rates and the array is intended to store large data blocks.
TrueNAS recommends defaulting to a RAIDz layout generally and whenever a dRAID vdev would have fewer than 10 data storage devices.
Determining your specific storage requirements is a critical step before creating a pool.
The ZFS and dRAID primers provide a starting point to learn about the strengths and costs of different storage pool layouts.
You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.
Data Encryption
Security requirements can mean the data must be protected with additional encryption.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Creating a Pool
Click Create Pool to open the Pool Creation Wizard.
Pool Creation Wizard
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Enclosure Option only shows for TrueNAS Enterprise systems with connected expansion shelves.
You can rename your enclosure on the Enclosure screen to include the rack and U number in the name, which helps identify the physical location while in the pool creation screen.
Enter a name of up to 50 lowercase alpha-numeric characters.
Use only the permitted special characters that conform to ZFS naming conventions.
The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
You cannot change the pool name after creation.
(Enterprise systems only) Select the Enclosure Option to apply the dispersal strategy of your choice.
This option only shows for TrueNAS Enterprise systems with connected expansion shelves.
The dispersal strategy sets how the system adds disks by size and type to the pool VDEVs created using the Automated Disk Selection option. Enclosures mentioned in the options below refer to the disk enclosures in the expansion shelves and main system chassis.
No Enclosure Dispersal Strategy does not apply a dispersal strategy, and does not show additional options.
Disks added to the pool VDEVs are assigned in sequence based on disk availability and are not balanced across all enclosures.
Maximum Dispersal Strategy applies a maximum dispersal strategy.
This option balances disk selection across all enclosures and available disks and does not show additional options.
Disks added to the pool VDEVs are spread across all available enclosure disks.
Limit Pool To A Single Enclosure applies a minimum dispersal strategy.
Select the expansion shelf option on the Enclosure dropdown.
Disks added to the pool VDEVs are spread across the enclosure disks that align with the selection in Enclosure.
Select the layout from the Layout dropdown list, then use the Automated Disk Selection fields to select and add the disks, or click Manual Disk Selection to add specific disks to the chosen Layout.
dRAID layouts do not show the Manual Disk Selection button but do show additional Automated Disk Selection fields.
When configuring a dRAID data VDEV, first, choose a Disk Size then select a Data Devices number.
The remaining fields update based on the Data Devices and dRAID layout selections.
ZFS allows groups to span multiple rows, which means it does not require each row to contain a whole number of redundancy groups. This layout has several advantages over requiring whole groups in each row:
Group count - Group count is not a relevant parameter when defining a dRAID layout. ZFS only needs the group width and all groups will have the desired size.
Group widths - ZFS can support all possible group widths (greater than or equal to the physical disk count).
ZFS determines the number of groups by the least common multiple (LCM) of the group width (D+P) and the number of physical drives minus spares (C-S). The logic within dRAID is simplified when the group width is the same for all groups, although some aspects, such as computing permutation numbers and drive offsets, are more complex. This flexible layout ensures even distribution of data and parity while maintaining high performance and resilvering efficiency.
Click Save And Go To Review if not adding other VDEV types to the pool or click Next to move forward to the next wizard screen.
Add optional VDEVs to suit your storage redundancy and performance requirements.
Click Create Pool on the Review wizard screen to add the pool.
Fusion Pools
Fusion Pools are also known as ZFS allocation classes, ZFS special vdevs, and metadata vdevs (Metadata vdev type on the Pool Manager screen.).
What's a special VDEV?
A special VDEV can store metadata such as file locations and allocation tables.
The allocations in the special class are dedicated to specific block types.
By default, this includes all metadata, the indirect blocks of user data, and any deduplication tables.
The class can also be provisioned to accept small file blocks.
This is a great use case for high-performance but smaller-sized solid-state storage.
Using a special vdev drastically speeds up random I/O and cuts the average spinning-disk I/Os needed to find and access a file by up to half.
Creating a Fusion Pool
Go to the Storage Dashboard and click Create Pool.
A pool must always have one normal (non-dedup/special) VDEV before you assign other devices to the special class.
Enter a name for the pool using up to 50 lowercase alpha-numeric and permitted special characters that conform to ZFS naming conventions.
The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
Click ADD VDEV and select Metadata to add the VDEV to the pool layout.
Add disks to the primary Data VDevs, then to the Metadata VDEV.
Add SSDs to the new Metadata VDev and select the same layout as the Data VDevs.
Metadata VDEVs are critical for pool operation and data integrity. Protect them with redundancy measures such as mirroring, and optionally hot spare(s) for additional fault tolerance. It is suggested to use an equal or greater level of failure tolerance in each of your metadata VDEVs; for example, if your data VDEVs are configured as RAIDZ2, consider the use of 3-way mirrors for your metadata VDEVs.
UPS Recommendation
When using SSDs with an internal cache, add an uninterruptible power supply (UPS) to the system to help minimize the risk from power loss.
Using special VDEVs identical to the data VDEVs (so they can use the same hot spares) is recommended, but for performance reasons, you can make a different type of VDEV (like a mirror of SSDs).
In that case, you must provide hot spare(s) for that drive type as well. Otherwise, if the special VDEV fails and there is no redundancy, the pool becomes corrupted and prevents access to stored data.
While the metadata VDEV can be adjusted after its addition by attaching or detaching drives, the entire metadata VDEV itself can only be removed from the pool when the pool data VDEVs are mirrors. If the pool uses RAIDZ data VDEVs, a metadata VDEV is a permanent addition to the pool and cannot be removed.
When more than one metadata VDEV is created, then allocations are load-balanced between all these devices.
If the special class becomes full, then allocations spill back into the normal class.
Deduplication table data is placed first onto a dedicated Dedup VDEV, then a Metadata VDEV, and finally the data VDEVs if neither exists.
Create a fusion pool and Status shows a Special section with the metadata SSDs.
Managing Pools
The Storage Dashboard widgets provide enhanced storage provisioning capabilities and access to pool management options to keep the pool and disks healthy, upgrade pools and VDEVs, open datasets, snapshots, and data protection screens.
This article provides instructions on pool management functions available in the TrueNAS UI.
Select Storage on the main navigation panel to open the Storage Dashboard.
Locate the Storage Health widget for the pool, then click the Edit Auto TRIM. The Pool Options for poolname dialog opens.
With Auto TRIM selected and active, TrueNAS periodically checks the pool disks for storage blocks it can reclaim.
Auto TRIM can impact pool performance, so the default setting is disabled.
For more details about TRIM in ZFS, see the autotrim property description in zpool.8.
Exporting/Disconnecting or Deleting a Pool
Use the Export/Disconnect button to disconnect a pool and transfer drives to a new system where you can import the pool.
It also lets you completely delete the pool and any data stored on it.
Click on Export/Disconnect on the Storage Dashboard.
A dialog displays showing any system services affected by exporting the pool, and options based on services configured on the system.
To delete the pool and erase all the data on the pool, select Destroy data on this pool.
The pool name field displays at the bottom of the window. Type the pool name into this field. To export the pool, do not select this option.
Select Delete saved configurations from TrueNAS? to delete shares and saved configurations on this pool.
Select Confirm Export/Disconnect
Click Export/Disconnect. A confirmation dialog displays when the export/disconnect completes.
Upgrading a Pool
Upgrading a storage pool is typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Do not do a pool-wide ZFS upgrade until you are ready to commit to this TrueNAS major version! You can not undo a pool upgrade, and you lose the ability to roll back to an earlier major version!
The Upgrade button displays on the Storage Dashboard for existing pools after an upgrade to a new TrueNAS major version that includes new OpenZFS feature flags.
Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS version.
Upgrading pools only takes a few seconds and is non-disruptive.
However, the best practice is to upgrade a pool while it is not in heavy use.
The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
It is not necessary to stop sharing services to upgrade the pool.
Running a Pool Data Integrity Check (Scrub)
Use Scrub Now on the Storage Health pool widget to start a pool data integrity check.
Click Scrub Now to open the Scrub Pool dialog, then click Start Scrub to begin the process.
If TrueNAS detects problems during the scrub operation, it either corrects them or generates an alert in the web interface.
A scrub is a data integrity check of your pool. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
Scheduling Scrub Tasks
TrueNAS automatically creates a scheduled scrub for each pool that runs every Sunday at 12:00 AM.
The Storage Health widget shows the scheduled scrub status:
Scheduled Scrub: None Set with a Schedule link if no scrub task exists
Scheduled Scrub: [when] with a Configure link if a scrub task is configured and enabled
Click Schedule to create a new scrub schedule or Configure to modify an existing schedule. This opens the Configure Scheduled Scrub screen where you can set the schedule, threshold days, and enable or disable the scheduled scrub.
Threshold Days sets the days before a completed scrub is allowed to run again.
This controls the task schedule.
For example, scheduling a scrub to run daily and setting threshold days to 7 means the scrub attempts to run daily.
When the scrub is successful, it continues to check daily but does not run again until seven days have elapsed.
Using a multiple of seven ensures the scrub always occurs on the same weekday.
Starting in TrueNAS 25.10, resilver priority settings are now located in System Settings > Advanced Settings on the Storage widget.
Managing Pool Disks
The Storage Dashboard screen Disks button and the View Disks button on the Disk Health widget both open the Disks screen.
View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
To manage disks in a pool, click on the VDEV to expand it and show the disks in that VDEV.
Click on a disk to see the widgets for that disk.
You can take a disk offline, detach it, replace it, manage the SED encryption password, and perform other disk management tasks from this screen.
See Replacing Disks for more information on the Offline, Replace and Online options.
Expanding a Pool
There are a few ways to increase the size of an existing pool:
Add one or more drives to an existing RAIDZ VDEV.
Add a new VDEV of the same type.
Add a new VDEV of a different type.
Replace all existing disks in the VDEV with larger disks.
Adding a new special VDEV increases usable space in combination with a special_small_files VDEV, but it is not encouraged. A VDEV limits all disks to the usable capacity of the smallest attached device.
When using one of the above methods, TrueNAS does not automatically expand the pool to fit newly available space.
Go to Storage and click Expand Pool above the Usage widget.
Select Confirm in the Expand Pool dialog.
Click Continue to start the pool expansion process.
TrueNAS expands the pool to use the additional available capacity.
Extending a RAIDZ VDEV
Extend a RAIDZ VDEV to add additional disks one at a time, expanding capacity incrementally.
This is useful for small pools (typically with only one RAID-Z VDEV), where there is not enough hardware capacity to add a second VDEV, doubling the number of disks.
Overview and Considerations
TrueNAS 24.10 (Electric Eel) introduces the RAIDZ extension to allow incremental expansion of an existing RAIDZ VDEV using one more disk.
RAIDZ extension allows resource- or hardware-limited home lab and small enterprise users to expand storage capacity with lower upfront costs compared to traditional ZFS expansion methods.
To expand a RAIDZ array, TrueNAS reads data from the current disks and rewrites it onto the new configuration, including any additional disks.
Data redundancy is maintained.
Make sure the pool is healthy before beginning the expansion process.
If a disk fails mid-expansion, the process pauses until the RAIDZ virtual device (vdev) is healthy again, typically by replacing the failed disk and waiting for the system to rebuild.
The storage pool remains accessible throughout the expansion.
If you restart or export/import the pool, the expansion resumes from where it left off.
After the expansion, the extra space becomes available for use.
The fault-tolerance level of the RAIDZ array remains unchanged.
For example, a four-disk-wide RAIDZ2 expanded to a six-disk-wide RAIDZ2 still cannot lose more than two disks at a time.
You can expand a RAIDZ vdev multiple times.
Existing data blocks retain their original data-to-parity ratio and block width, but spread across the larger set of disks.
New data blocks adopt the new data-to-parity ratio and width.
Because of this overhead, an extended RAIDZ VDEV can report a lower total capacity than a freshly created VDEV with the same number of disks.
Before (left) and after (right) expansion of a four-disk to five-disk RAIDZ1 Thanks to Matt Ahrens (Source)
Extended VDEVs recover lost headroom as existing data is read and rewritten to the new parity ratio.
This can occur naturally over the lifetime of the pool as you modify or delete data.
To manually recover capacity, simply replicate and rewrite the data to the extended pool.
You can use the RAIDZ Extension Calculator to visualize potential lost headroom and capacity available to recover by rewriting existing data.
While this process can recover the actual lost capacity, reported capacity continues to rely on the old data-to-parity ratio.
An expanded vdev can continue to report a lower than expected capacity, even after rewriting old data to the new parity ratio.
This accounting inconsistency does not impact the actual available capacity of the vdev.
Select an available disk from the New Disk dropdown menu.
Click Extend.
A job progress window opens.
TrueNAS returns to the Poolname VDEVs screen when complete.
Adding a VDEV to a Pool
ZFS supports adding VDEVs to an existing ZFS pool to increase the capacity or performance of the pool.
To extend a pool by mirroring, you must add a data VDEV of the same type as existing VDEVs.
You cannot change the original encryption or data VDEV configuration.
Adding VDEV Examples
To make a striped mirror, add the same number of drives to extend a ZFS mirror.
For example, you start with ten available drives. Begin by creating a mirror of two drives, and then extend the mirror by adding another mirror of two drives. Repeat this three more times until you add all ten drives.
To make a stripe of two 3-drive RAIDZ1 VDEVs (similar to RAID 50 on a hardware controller), add another three drives as a new RAIDZ1 VDEV to the existing single 3-drive RAIDZ1 VDEV pool.
To make a stripe of two 6-disk RAIDZ2 VDEVs (similar to RAID 60 on a hardware controller), add another six drives as a new RAIDZ2 VDEV to the existing single 6-drive RAIDZ2 VDEV pool.
To add a deduplication VDEV, we suggest creating the VDEV when you first create the pool to ensure that all metadata or deduplication tables are stored on it.
Special or deduplication VDEVs added to a pool with existing data are only populated with new writes.
To add a VDEV to a pool:
Click View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
Click Add VDEV on the PoolnameVDEVs screen to open the Add Vdevs to Pool screen.
Adding a vdev to an existing pool follows the same process as documented in Create Pool.
Click on the type of vdev you want to add, for example, to add a spare, click on Spare to show the vdev spare options.
To use the Automated Disk Selection option, select the disk size. The Width and Number of VDEVs fields populate with default values based on the layout and disk size selected. To change this, select new values from the dropdown lists.
Adding a VDEV Manually
To add the vdev manually, click Manual Disk Selection to open the Manual Selection screen.
Click Add to show the vdev options available for the vdev type.
The example image shows adding a stripe vdev for the spare.
Vdev options are limited by the number of available disks in your system and the configuration of any existing vdevs of that type in the pool.
Drag the disk icon to the stripe vdev, then click Save Selection.
You have the option to accept the change or click Edit Manual Disk Selection to change the disk added to the strip vdev for the spare, or click Reset Step to clear the strip vdev from the spare completely.
Click either Next or a numbered item to add another type of vdev to this pool.
Repeat the same process above for each type of vdev to add.
Click Save and Go to Review to go to the Review screen when ready to save your changes.
To make changes, click either Back or the vdev option (i.e., Log, Cache, etc.) to return to the settings for that vdev.
To clear all changes, click Start Over.
Select Confirm, then click Start Over to clear all changes.
Click Update Pool to save changes.
Adding a Deduplication VDEV
You can add a deduplication VDEV to an existing pool, but files in the pool might or might not have deduplication applied to them.
When adding a deduplication VDEV to an existing pool, any existing entries in the deduplication table remain on the data VDEVs until the data they reference is rewritten.
After adding a deduplication VDEV to a pool, and when duplicated files are added to the pool, the Storage Health widget on the Storage Dashboard shows two links, Prune and Set Quota. These links do not show if duplicated files do not exist in the pool.
Use Prune to set the parameters used to prune the deduplication table (DDT). Select the measurement used, percentage or age, when pruning the table size.
Use Set Quota to set the DDT quota that determines the maximum table size allowed.
The default setting, Auto, allows the system to determine the quota based on the size of a dedicated dedup vdev when setting the quota limit.
This property works for both legacy and fast dedup tables.
Change to Custom to set the quota to your preference.
Click Save to save and close the dialogs.
Replacing Disks to Expand a Pool
To expand a pool by replacing disks with a higher capacity disk, follow the same procedure as in Replacing Disks.
Insert a new disk into an empty enclosure slot. Remove the old disk only after completing the replacement operation.
If an empty slot is not available, you can offline the existing disk and replace it in the same slot, but this reduces redundancy during the process.
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget opens the Poolname VDEVs screen..
Click anywhere on the VDEV to expand it and select one of the existing disks.
(Optional) If replacing disks in the same slot, take one existing disk offline.
Add the new disk to the existing VDEV. Click Replace Disk to add the new disk to the VDEV and bring it online.
Disk replacement fails when the selected disk has partitions or data present.
To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.
After the disk wipe completes, TrueNAS starts replacing the failed disk.
TrueNAS resilvers the pool during the replacement process.
For pools with large amounts of data, this can take a long time.
When the resilver process completes, the pool status returns to Online status on the Poolname Devices screen.
Wait for the resilver to complete before replacing the next disk.
Repeat steps 1-4 for all attached disks.
After replacing the last attached disk, click Expand on the Storage Dashboard to increase the pool size to fit all available disk space.
Removing VDEVs
You can always remove the L2ARC (cache) and SLOG (log) VDEVs from an existing pool, regardless of topology or VDEV type.
Removing these devices does not impact data integrity, but it can significantly impact performance for reads and writes.
In addition, you can remove a data VDEV from an existing pool under specific circumstances.
This process preserves data integrity but has multiple requirements:
The pool must be upgraded to a ZFS version that includes the device_removal feature flag.
The system shows the Upgrade button after upgrading TrueNAS when new ZFS feature flags are available.
All top-level VDEVs in the pool must be only mirrors or stripes.
Special VDEVs cannot be removed when RAIDZ data VDEVs are present.
All top-level VDEVs in the pool must use the same basic allocation unit size (ashift).
The remaining data VDEVs must contain sufficient free space to hold all of the data from the removed VDEV.
When a RAIDZ data VDEV is present, it is generally not possible to remove a device.
To remove a VDEV from a pool:
Click *View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
Click the device or drive to remove, then click the Remove button in the ZFS Info widget.
If the Remove button is not visible, check that all conditions for VDEV removal listed above are correct.
Confirm the removal operation and click the Remove button.
The VDEV removal process status shows in the Jobs screen (or alternately with the zpool status command).
Avoid physically removing or attempting to wipe the disks until the removal operation completes.
Datasets
This section has tutorials about dataset configuration and management.
Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.
Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.
Storage Encryption: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.
Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.
Adding and Managing Datasets
A TrueNAS dataset is a file system within a data storage pool.
Datasets can contain files, directories, and child datasets, and have individual permissions or flags.
Datasets can also be encrypted.
In TrueNAS 22.12.3 or later, the TrueNAS UI requires encryption for child datasets created in encrypted parent datasets, but you can change the encryption type from key to passphrase.
You can create an encrypted dataset if the parent is not encrypted and set the type as either key or passphrase.
We recommend organizing your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.
Creating a Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
Setting Dataset Compression Levels
Compression encodes information in less space than the original data occupies.
We recommend choosing a compression algorithm that balances disk performance with the amount of saved space.
The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Setting Dataset Quotas
You can set dataset quotas while adding datasets using the quota management options in the Add Dataset screen under Advanced Options.
You can also add or edit quotas for an existing dataset, by clicking Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset.
You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space.
You can configure quotas for only the new dataset or both the new dataset and any child datasets of the new dataset.
Define the maximum allowed space for the dataset in either the Quota for this dataset or Quota for this dataset and all children field.
Enter 0 to disable quotas.
Dataset quota alerts are based on the percentage of storage used.
To set up a quota warning alert, enter a percentage value in Quota warning alert at, %.
When consumed space reaches the defined percentage it sends the alert.
To change the setting from the parent dataset warning level, clear the Inherit checkbox and then change the value.
To set up the quota critical level alerts, enter the percentage value in Quota critical alert at, %.
Clear the Inherit checkbox to change this value to something other than using the parent alert setting.
When setting quotas or changing the alert percentages for both the parent dataset and all child datasets, use the fields under This Dataset and Child Datasets.
Enter a value in Reserved space for this dataset to set aside additional space for datasets that contain logs, which could eventually take all available free space.
Enter 0 for unlimited.
By default, many dataset options inherit their values from the parent dataset.
When settings on the Advanced Options screen are set toInherit the dataset uses the setting from the parent dataset.
For example, the Encryption or ACL Type settings.
To change any setting that datasets inherit from the parent, select an available option other than Inherit.
Deduplication is found on the Add Datasets Advanced Settings screen.
Best practice is to add deduplication when you first create the dataset.
You can add deduplication to an existing dataset but existing files do not have deduplication applied to them.
Adding deduplication to an existing dataset only applies deduplication to data written after you enable the function.
When enabling deduplication for a dataset of a pool that does not have a deduplication or special VDEV, the deduplication table (DDT) is stored on a regular VDEVs of the pool.
To store the DDT outside of the regular VDEVs, add a deduplication or special VDEV to the pool.
To add deduplication to a new dataset, after entering the name and selecting the dataset preset, click Advanced Settings.
To add deduplication to an existing dataset, select the dataset on the Dataset screen tree table, click Edit on the Dataset Details widget to open the Edit Dataset screen. Click Advanced Settings.
Scroll down to the ZFS Deduplication setting, then change to On.
A warning dialog opens and states that deduplication is an experimental and not fully supported feature.
Select the root dataset of the pool (with the metadata VDEV), then click Add Dataset to add the dataset.
Click Advanced Options. Enter the dataset name, select the Dataset Preset, then scroll down to Metadata (Special) Small Block Size setting to set a threshold block size for including small file blocks into the special allocation class (fusion pools).
Blocks smaller than or equal to this value are assigned to the special allocation class while greater blocks are assigned to the regular class.
Valid values are zero or a power of two from 512B up to 1M.
The default size 0 means no small file blocks are allocated in the special class.
Enter a threshold block size for including small file blocks into the special allocation class (fusion pools).
Managing Datasets
After creating a dataset, users can manage additional options from the Datasets screen.
Select the dataset, then click Edit on the dataset widget for the function you want to manage.
The Datasets Screen article describes each option in detail.
Editing a Dataset
Select the dataset on the tree table, then click Edit on the Dataset Details widget to open the Edit Dataset screen and change the dataset configuration settings. You can change all settings except Name, Case Sensitivity, or Device Preset.
Editing Dataset Permissions
To edit the dataset ACL permissions, click Edit on the Permissions widget.
If the ACL type is NFSv4, the Permissions widget shows ACE entries for the dataset.
Each entry opens a checklist of flag options you can select or clear without opening the Edit ACL screen.
To modify ownership, configure new or change existing ACL entries, click Edit to open the ACL Editor screen.
To edit a POSIX ACL type, click Edit on the Permissions widget to open the Unix Permissions Editor screen.
To access the Edit ACL screen for POSIX ACLs, select Create a custom ACL on the Select a preset ACL window.
Select the dataset on the tree table, then click Delete on the Dataset Details widget.
This opens a delete window where you enter the dataset path (root/parent/child) and select Confirm to delete the dataset, all stored data, and any snapshots from TrueNAS.
To delete a root dataset, use the Export/Disconnect option on the Storage Dashboard screen to delete the pool.
Deleting datasets can result in unrecoverable data loss!
Move any critical data stored on the dataset off to a backup copy or obsolete the data before performing the delete operation.
Adding and Managing Zvols
A ZFS Volume (zvol) is a dataset that represents a block device or virtual disk drive.
TrueNAS requires a zvol when configuring iSCSI Shares.
Adding a virtual machine also creates a zvol to use for storage.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused.
Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume.
Do not assign capacity that exceeds what is required for TrueNAS to operate properly. For more information, see TrueNAS Hardware Guide for CPU, memory and storage capacity information.
Adding a Zvol
To create a zvol, go to Datasets.
Select the root or non-root parent dataset where you want to add the zvol, and then click Add Zvol.
Enter a name that does not exceed 60 characters, enter a number and letter for the unit of measure in Size, and then click Save.
Managing Zvols
Options to manage a zvol are on the zvol widgets shown on the Dataset screen when you select the zvol on the dataset tree table.
Delete Zvol removes the zvol from TrueNAS.
Deleting a zvol also deletes all snapshots of that zvol. Click Delete on the Zvol Details widget.
Deleting zvols can result in unrecoverable data loss!
Remove critical data from the zvol or verify it is obsolete before deleting a zvol.
Edit on the Zvol Details widget opens the Edit Zvol screen where you can change settings. Name is read-only and you cannot change it.
To create a snapshot, click Take Snapshot on the Data Protection widget.
Cloning a Zvol from a Snapshot
To clone a zvol from an existing snapshot, select the zvol on the datasets tree table, then click View Snapshots on the Data Protection widget to open the Snapshots screen.
You can also access the Snapshots screen from the Periodic Snapshot Tasks screen. Click on the Periodic Snapshot Task widget header on the Data Protection screen to open the Period Snapshot Tasks screen.
Click Snapshots to open the Snapshots screen.
Click on the snapshot you want to clone, then click Clone to New Dataset.
Enter a name for the new dataset or accept the one provided, then click Clone.
The cloned zvol shows on the Datasets screen.
Managing User or Group Quotas
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
You can use the quota settings on the Add Dataset or Edit Dataset configuration screens in the Advanced Options settings to set up alarms and set aside more space in a dataset.
See Adding and Managing Datasets for more information.
To manage the dataset overall capacity, use Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Configuring User Quotas
To view and edit user quotas, go to Datasets and click Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.
Click Add to open the Add User Quota screen.
Click in the field to view a list of system users including any users from a directory server that is properly connected to TrueNAS.
Begin typing a user name to filter all users on the system to find the desired user, then click on the user to add the name.
Add additional users by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual user quotas, click anywhere on a user row to open the Edit User Quota screen where you can edit the User Data Quota and User Object Quota values.
User Data Quota is the amount of disk space that selected users can use. User Object Quota is the number of objects selected users can own.
Configuring Group Quotas
Click Add to open the Add Group Quota screen.
Click in the Group field to view a list of system groups on the system.
Begin typing a name to filter all groups on the system to find the desired group, then click on the group to add the name.
Add additional groups by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual group quotas, click anywhere on a group name to open the Edit Group Quota screen where you can edit the Group Data Quota and Group Object Quota values.
Group Data Quota is the amount of disk space that the selected group can use. Group Object Quota is the number of objects the selected group can own.
Creating Snapshots
Snapshots are one of the most powerful features of ZFS.
A snapshot provides a read only point-in-time copy of a file system or volume.
This copy does not consume extra space in the ZFS pool.
The snapshot only records the differences between storage block references whenever the data is modified.
Why do I want to keep snapshots?
Snapshots keep a history of files and provide a way to recover an older or even deleted files.
For this reason, many administrators take regular snapshots, store them for some time, and copy them to a different system.
This strategy allows an administrator to roll the system data back to a specific point in time.
In the event of catastrophic system or disk failure, off-site snapshots can restore data up to the most recent snapshot.
Taking snapshots requires the system have all pools, datasets, and zvols already configured.
Creating a Snapshot
Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.
There are two ways to access snapshot creation:
From the Data Protection Screen
To access the Snapshots screen, go to Data Protection > Periodic Snapshot Tasks and click the Snapshots button in the lower left corner of the widget.
If you click Create Snapshot the Snapshots screen opens filtered for the selected dataset.
Clear the dataset from the search field to see all snapshots.
You can also click the Manage Snapshots link on the Data Protection widget to open the Snapshots screen.
Click Add at the top right of the screen to open the Add Snapshot screen.
Select a dataset or zvol from the Dataset dropdown list.
Accept the name suggested by the TrueNAS software in the Name field or enter any custom string to override the suggested name.
(Optional) Select an option from the Naming Schema dropdown list that the TrueNAS software populated with existing periodic snapshot task schemas.
If you select an option, TrueNAS generates a name for the snapshot using that naming schema from the selected periodic snapshot and replicates that snapshot.
You cannot enter a value in both Naming Schema and in Name as selecting or entering a value in Naming Schema populates the other field.
(Optional) Select Recursive to include child datasets with the snapshot.
Click Save to create the snapshot.
Managing Snapshots
Viewing the List of Snapshots
File Explorer limits the number of snapshots Windows presents to users. If TrueNAS responds with more than the File Explorer limit, File Explorer shows no available snapshots.
TrueNAS displays a dialog stating the dataset snapshot count has more snapshots than recommended and states performance or functionality might degrade.
There are two ways to view the list of snapshots:
Go to Datasets > Data Protection widget > Manage Snapshots link to open the Snapshots screen.
The Snapshots screen displays a list of snapshots on the system. Use the search bar at the top to narrow the selection. Clear the search bar to list all snapshots.
Use the Clone to New Dataset button to create a clone of the snapshot.
The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen.
Click Clone to New Dataset to open a clone confirmation dialog.
The Delete option destroys the snapshot.
You must delete child clones before you can delete their parent snapshot.
While creating a snapshot is instantaneous, deleting one is I/O intensive and can take a long time, especially when deduplication is enabled.
Why?
ZFS has to review all allocated blocks before deletion to see if another process is using that block. If not used, the ZFS can free that block.
Click the Delete button. A confirmation dialog displays. Select Confirm to activate the Delete button.
Deleting with Batch Operations
To delete multiple snapshots, select the left column box for each snapshot to include. Click the deleteDelete button that displays.
To search through the snapshots list by name, type a matching criteria into the searchFilter Snapshots text field.
The list now displays only the snapshot names that match the filter text.
Confirm activates the Delete button. If the snapshot has the Hold options selected, an error displays to prevent you from deleting that snapshot.
Using Rollback to Revert a Dataset
The Rollback option reverts the dataset to the point in time saved by the snapshot.
Rollback is a dangerous operation that causes any configured replication tasks to fail.
Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out of order.
A less disruptive method to restore data from a point in time is to clone a specific snapshot as a new dataset:
Clone the desired snapshot.
Share the clone with the share type or service running on the TrueNAS system.
Allow users to recover their needed data.
Delete the clone from Datasets.
This approach does not destroy any on-disk data or disrupt automated replication tasks.
TrueNAS asks for confirmation before rolling back to the chosen snapshot state.
Select the radio button for how you want the rollback to operate.
All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden .zfs located at the root of every dataset.
A snapshot and any files it contains are not accessible or searchable if the snapshot mount path is longer than 88 characters.
The data within the snapshot is safe but to make the snapshot accessible again shorten the mount path.
Users can browse and search any files they have permission to access throughout the entire dataset snapshot collection.
When creating a snapshot, permissions or ACLs set on files within that snapshot might limit access to the files.
Snapshots are read-only, so users do not have permission to modify a snapshot or its files, even if they had write permissions when creating the snapshot.
From the Datasets screen, select the dataset and click Edit on the Dataset Details widget.
Click Advanced Options and set Snapshot Directory to Visible.
To access snapshots using a share, configure the client system to view hidden files.
For example, in a Windows SMB share, enable Show hidden files, folders, and drives in Folder Options.
From to the dataset root folder, open the .zfs directory and navigate to the snapshot.
Storage Encryption
TrueNAS offers ZFS encryption for your sensitive data in datasets and zvols.
Users are responsible for backing up and securing encryption keys and passphrases!
Losing the ability to decrypt data is similar to a catastrophic data loss.
The local TrueNAS system manages keys for data-at-rest.
Users are responsible for storing and securing their keys.
TrueNAS includes the Key Management Interface Protocol (KMIP).
Pool and Dataset Encryption
Encryption is for users storing sensitive data.
It does not apply encryption to the storage vdev or the disks in the pool.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Leave Encryption unselected on the Pool Creation Wizard screen to create a pool with an unencrypted root dataset.
You can create both encrypted and unencrypted datasets within an unencrypted pool.
By default, child datasets inherit encryption settings from the parent.
Disabling Inherit under Advanced Options allows modifying the encryption configuration for a child dataset.
You cannot change a child dataset of an encrypted parent dataset to unencrypted.
However, datasets created outside the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured.
For example, the ix-apps dataset on the pool selected for applications does not inherit encryption settings.
Can I change dataset encryption?
Before saving a new dataset, you can change the type of encryption of an encrypted dataset to key to passphrase.
After saving a dataset with encryption applied you cannot change the dataset to unencrypted.Can I unencrypt my data?
Yes, you can move encrypted data to an unencrypted pool or dataset using either rsync or replication.
You can also move data from an unencrypted pool or dataset to an encrypted dataset using rsync or replication.
If your system loses power or you restart the system, all encrypted datasets and zvols automatically lock to protect data.
Encryption Visual Cues
TrueNAS uses lock icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen.
Each icon shows a text label with the state of the dataset when you hover the mouse over the icon.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
A dataset that inherits encryption shows the mouse hover-over label Locked by ancestor or Unlocked by ancestor.
Select an encrypted dataset to see the ZFS Encryption widget on the Datasets screen.
The dataset encryption state is unlocked until you lock it using the Lock button on the ZFS Encryption widget.
After locking the dataset, the icon on the tree table changes to locked, and the Unlock button appears on the ZFS Encryption widget.
Implementing Encryption
Before creating a encrypted pool (root dataset) or dataset, decide if you want to encrypt all child datasets, zvols, and data stored on that dataset.
If your system does not have enough disks to create a second storage pool, we recommend not using encryption at the pool level.
Apply encryption at the dataset level to non-root parent or child datasets.
All pool-level encryption is key-based encryption. When prompted, download the encryption key and keep it stored in a safe place where you can back up the key file.
You cannot use passphrase encryption at the pool level.
You cannot change an existing dataset from encrypted to unencrypted.
You can only change the dataset encryption type (key or passphrase).
Adding Encryption to a New Pool
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Go to Storage and click Create Pool on the Storage Dashboard screen.
Or click Add to Pool on the Unassigned Disks widget and click Add to New to open the Pool Creation Wizard.
Enter a name for the pool, then select Encryption. Select the layout for the data VDEV and add the disks.
A warning dialog displays after selecting Encryption.
Read the warning, select Confirm, and then click I UNDERSTAND.
A second dialog opens where you click Download Encryption Key for the pool encryption key.
Click Done to close the window.
Move the encryption key to safe location where you can back up the file.
Add the VDEVs to the pool you want to include, then click Save to create the pool with encryption.
Adding Encryption to a New Dataset
To add an encrypted dataset, go to Datasets.
Select a dataset on the tree table where you want to add a new dataset.
The default dataset selected when you open the Datasets screen is the root dataset of the first pool on the tree table list.
If you have more than one pool and want to create a dataset in a pool other than the default, select the root dataset for that pool or any dataset under the root where you want to add the new dataset.
Click Add Dataset to open the Add Dataset screen, and enter a name.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
.
Click Advanced Options.
To add encryption to a dataset, scroll down to Encryption Options and select the inherit checkbox to clear the checkmark and show the Encryption option. Clear this checkbox to show the default settings for key type encryption.
If the parent dataset is unencrypted and you want to encrypt the dataset select the Inherit (non-encrypted) checkbox to clear it and show the Encryption option.
If the parent dataset is encrypted and you want to change the type, select Inherit (encrypted) to show the encryption configuration options.
To keep the dataset encryption settings from the parent, leave inherit selected.
Decide if you want to use the default key type encryption and want to let the system generate the encryption key.
To use key encryption and an existing key, disable Generate Key to display the Key field.
Enter the existing key in this field.
The passphrase must be longer than 8 and less than 512 characters.
Keep encryption keys and/or passphrases safeguarded in a secure and protected place.
Losing encryption keys or passphrases can result in permanent data loss!
Select the encryption algorithm from Algorithm or use the recommended default.
Leave the default selection if you do not have a particular encryption standard you want to use. What are these options?
TrueNAS supports AES Galois Counter Mode (GCM) and Counter with CBC-MAC (CCM) algorithms for encryption.
These algorithms provide authenticated encryption with block ciphers.
Changing Dataset (or Zvol) Encryption
You cannot add encryption to an existing dataset!
You can change the type of encryption for an already encrypted dataset using the Edit option on the Encryption widget for the dataset.
Save changes to the encryption key or passphrase, update your saved passcodes and keys file, and back up that file.
To change the encryption type, go to Datasets, select the encrypted dataset on the tree table, then click Edit on the Encryption widget.
The Edit Encryption Options dialog for the selected dataset opens.
Before making changes to a locked encrypted dataset you must unlock it.
If the dataset inherits encryption settings from a parent dataset, to change this, clear the Inherit encryption properties from parent checkbox to display the key type encryption setting options.
If the encryption type is set to passphrase, you can change the passphrase, or change Encryption Type to key.
You cannot change a dataset created with a key as the encryption type to passphrase.
Key type options are Generate Key (pre-selected) or clear to display the Key field. Enter your new key in this field.
Use a complex passphrase that is not easy to guess. Store in a secure location subject to regular backups.
Leave the other settings at default, then click Confirm to activate Save.
Click Save to close the window. The ZFS Encryption widget updates to reflect the changes made.
Locking and Unlocking Datasets
You can only lock and unlock an encrypted dataset if it is secured with a passphrase instead of a key file.
Before locking a dataset, verify that it is not currently in use.
Locking a Dataset
Select the encrypted dataset on the tree table, then click Lock on the Encryption widget to open the Lock Dataset dialog with the full path name for the dataset.
Use the Force unmount option only if you are certain no one is currently accessing the dataset.
Force unmount boots anyone using the dataset (e.g. someone accessing a share) so you can lock it.
Click Confirm to activate Lock, then click Lock.
You cannot use locked datasets.
Unlocking a Dataset
To unlock a dataset, go to Datasets then select the locked dataset on the tree table.
Click Unlock on the Encryption widget to open the Unlock Dataset screen.
Enter the key if key-encrypted, or the passphrase into Dataset Passphrase and click Save.
Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.
Select Force if the dataset mount path exists but is not empty. The unlock operation fails when this happens.
Using Force allows the system to rename the existing directory and file where the dataset should mount which prevents the mount operation from failing.
A confirmation dialog displays.
Click CONTINUE to confirm you want to unlock the datasets. Click CLOSE to exit and keep datasets locked.
A second confirmation dialog opens confirming the datasets unlocked.
Click CLOSE.
TrueNAS displays the dataset with the unlocked icon.
Encrypting a Zvol
Users are responsible for backing up and securing encryption keys and passphrases!
Losing the ability to decrypt data is similar to a catastrophic data loss.
To encrypt a Zvol, select a parent dataset and then create a new Zvol.
If the parent dataset is encrypted, select Inherit (encrypted) under Encryption Options.
If the parent dataset is not encrypted, disable Inherit (non-encrypted), select Encryption, and then configure the Encryption Type and related settings.
Next, go to Datasets and click on the Zvol and locate the Encryption widget.
If Encryption Type is set to Key, type an encryption key into the Key field or select Generate Key.
If using Passphrase, enter a passphrase of eight to 512 characters.Use a passphrase complex enough that is not easily guessed.
After making any changes, select Confirm, and then click Save.
Save changes to the encryption key or passphrase, update your saved passcodes and keys file, and back up the file.
Managing Encryption Credentials
There are two ways to manage the encryption credentials, with a key file or passphrase.
Creating a new encrypted pool automatically generates a new key file and prompts users to download it.
Always back up the key file to a safe and secure location.
To manually back up a root dataset key file, click Export Key on the Encryption widget.
A passphrase is a user-defined string of at least eight characters in length, and that is required to decrypt the dataset.
A passphrase is a user-defined string of eight to 512 characters that is required to decrypt the dataset.
The pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Users must enter a number greater than 100000.
Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase
TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.
Method 1: Construct JSON Manifest.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.
Method 2: Replicate Encrypted Dataset/zvol Without Properties.
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Method 3: Replicate Key Encrypted Dataset/zvol.
Go to Datasets on the system you are replicating from.
Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset.
Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
Configuring ACL Permissions
TrueNAS provides basic permissions settings and an access control list (ACL) editor to define dataset permissions.
ACL permissions control the actions users can perform on dataset contents and shares.
An Access Control List (ACL) is a set of account permissions associated with a dataset that applies to directories or files within that dataset.
TrueNAS uses ACLs to manage user interactions with shared datasets.
When you create a dataset, TrueNAS sets the ACL type based on the dataset preset, but you must configure the ACL before it becomes active.
ACL Types in TrueNAS
TrueNAS offers two ACL types: POSIX and NFSv4.
The Dataset Preset setting on the Add Dataset screen determines the type of ACL for the dataset.
Datasets created with the Generic dataset preset have the ACL type set to a POSIX (Unix) ACL.
Datasets created with the SMB dataset preset have the ACL type set to an NFSv4 ACL.
SMB shares require the more robust configurations in an NFSv4 ACL.
For most cases, a POSIX ACL is all you need.
If you want the more granular ACL controls in the NFSv4 ACL, you can create a dataset using the SMB dataset preset without creating an SMB share, or you can use the ACL Type option on the Add Dataset > Advanced Options screen to change a dataset using the Generic preset from a POSIX to NFSv4 ACL.
For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer.
How do I know what ACL Type my dataset has?
The Permissions widget for the dataset shows the dataset ACL type.
When Unix Permissions shows in the widget, the dataset has a POSIX ACL.
Alternatively, click Edit on the Dataset Details widget for the dataset to open the Edit Dataset screen, then click Advanced Options and scroll down to the ACL Type field to see the ACL type.
You can also check the ACL type while on the Edit ACL screen by clicking Use Preset, then clicking the down arrow for the Preset field in the Select a preset ACL window.
TrueNAS does not allow creating an ACL for the root dataset of a pool.
TrueNAS POSIX or NFSv4 ACL types, show different options on the ACL Editor screen.
Both the POSIX and NFSv4 ACL Editors screens allow you to:
Select a pre-configured ACL by clicking Use Preset and then selecting a Preset option
Customize the ACL by defining the owner user and group and adding ACL entries (ACEs) for individual user accounts or groups
Select a preset and customize the ACL
When using a preset and customising the ACL, select the preset first and then customize the ACL with new users or groups.
Selecting the preset after adding new ACL entries (ACEs) erases any ACEs added to the ACL, requiring you to re-enter them.
Click Save Access Control List when you are done configuring the ACL.
In most cases, the owner user and group should remain set to root, but you can change this to the primary admin user and group account with full privileges.
Add ACE items for users, groups, directories, etc., not included in preset configurations to customize access permissions to the dataset.
When adding a dataset using the SMB preset for a share or just setting up an NFSv4 ACL, TrueNAS shows the Set ACL for this dataset dialog after you save the dataset.
Click Go to ACL Manager to configure the ACL.
You must configure an ACL for the dataset.
The dataset does not have an ACL until you configure it even though you see ACL information in the Permissions widget.
This initially indicates the type of ACL created and the default basic permissions.
To access the dataset and files within it, you must set up the ACL with users and access permissions.
If you want to defer configuring the ACL, click Return to pool list, but make a note to return to the dataset to configure the ACL before attempting to use it.
Changing the ACL type affects how TrueNAS writes and reads on-disk ZFS ACLs.
When the ACL type changes from NFSv4 to POSIX, native ZFS ACLs do not convert to POSIX1e extended attributes, but ZFS uses the native ACL for access checks.
To prevent unexpected permissions behavior, you must manually set new dataset ACLs recursively after changing the ACL type.
Setting new ACLs recursively is destructive.
We suggest creating a ZFS snapshot of the dataset before changing the ACL type or modifying permissions.
While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.
Configuring POSIX ACL Permissions
The Unix Permissions Editor screen shows for datasets using the Generic dataset preset.
Accept the default root in Owner and Owner Group, or if you want to change this to a system administrator with full permissions, select the admin user name from each dropdown list, then click Apply Owner and Apply Group to make the change.
Next, select the Access levels using the Read, Write, Execute checkboxes for User, Group, Other.
Click Save to save changes and close the Unix Permissions Editor screen.
To further define the POSIX ACL, click Set ACL to open the Select a preset ACL window with two options: Select a preset ACL and Create a custom ACL.
Accept the default option Select a preset ACL to choose from the options on the Preset dropdown list.
Select Create a custom ACL to open the Edit ACL screen for a POSIX ACL with a minimal default configuration.
Selecting a preset also opens the Edit ACL screen, but with different default configurations based on the preset selected.
After selecting a preset, click Continue to close the preset window and show the Edit ACL screen for a POSIX ACL.
Next add ACL entries.
POSIX Preset Options
POSIX_OPEN - Gives the owner and group full dataset control. All other accounts can modify the dataset contents.
Use for collaborative datasets where multiple users need read/write access.
POSIX_RESTRICTED - Gives the owner full dataset control. The group can modify the dataset contents.
Others have no access. Use when you want group collaboration but need to restrict outside access.
POSIX_HOME - Gives the owner full dataset control. The group can modify the dataset contents.
All other accounts can navigate the dataset, but cannot read or modify files.
Use for private user directories where others need to traverse the path but not access the contents.
POSIX_ADMIN - Gives the admin user and builtin_administrators group full dataset control.
All other accounts can navigate the dataset but cannot read or modify files.
Use for administrative datasets that only system administrators should access.
Adding POSIX ACL Entries
The Edit ACL screen shows the ACL owner and owner group and allows you to change both, just as you can on the Unix Permissions Editor screen.
It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.
You can define the ACE entries when you first configure the POSIX ACL or change ACL entries (ACEs) and permissions for ACEs.
To edit an existing POSIX ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.
When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.
Click Add Item below the Access Control List on the left side of the screen.
If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List.
With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen.
Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset.
Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset.
This shows the Group field.
The group must be defined on the system.
In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users.
Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.
The options are Read, Modify, and/or Execute permissions.
(Optional) Select Default under Flags.
The POSIX flag for an ACL entry controls inheritance for newly created files and directories.
The default flag can only be set on directories, not on files.
When Default is selected, the ACL entry becomes a default ACL that applies to new objects created inside that directory, but it does not affect the access permissions of the current directory, just controls what new files/directories inherit.
New files inherit the default ACL as their access ACL. New directories inherit the default ACL as both their access ACL and their default ACL.
This continues down the tree of files and directories.
If not set, the ACL entry only affects access to the directory itself; new files and directories created inside the dataset do not inherit the permission.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets.
This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.
If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.
If you change your mind and want to discard the changes and revert to using a preset, click Use Preset.
This reopens the Select a Preset window where you can select a different preset to apply to the dataset.
Changing an ACL Owner or Owner Group
This applies to both POSIX and NFSv4 ACLs. The Edit ACL screen for POSIX and NFSv4 ACLs shows different configuration options, but the Owner and Owner Group settings are the same for both ACL types.
Think of the owner of the ACL as the main traffic cop granting other users access. In most cases, leave the default user set to root.
To allow a system administrator access, either change the owner and owner group to that admin user name, or add that admin user as an ACL entry (ACE) and grant it full permissions to allow it to administer the ACL and configure the dataset for other functions like an SMB share.
To change the owner and owner group:
Select the Owner user from the User dropdown list. To filter the list of users begin typing the name in the field.
Click Apply Owner to apply the change.
Next, change the Owner Group in the same manner as changing the owner.
Click Apply Group to apply the group change.
User and group options include those created manually or imported from a directory service.
To prevent errors, TrueNAS only submits changes after you select the apply options.
A common misconfiguration is not adding or removing the Execute permission from a dataset that is a parent to other child datasets.
Removing this permission results in lost access to the path.
If only changing the owner and owner group, click Save Access Control List.
If adding ACL entries, refer to the instructions for each ACL type.
To apply ACL settings to all child datasets, select Apply permissions recursively.
Change the default settings to your preferred primary account and group and select Apply permissions recursively before saving any changes.
See Edit ACL Screen for information on the ACL editor screens and setting options.
Users can grant root permissions to containers and instances through an unprivileged root account using the ACL editor in the UI or the TrueNAS API.
To ensure functionality, add an ACE for the truenas_container_unpriv_root user and assign the appropriate permissions (such as Read, Modify, and Execute).
For container environments, verify that the ACL includes an entry for truenas_container_unpriv_root with the required access to any dataset paths used by the container.
Selecting SMB in the Dataset Preset field on the Add Dataset screen applies an NFSv4 ACL type to the dataset.
You can use the SMB dataset preset and choose to not create an SMB share as the easiest way to apply an NFSv4 ACL to a dataset, or you can leave Dataset Preset set to Generic, click Advanced Options, scroll down to the ACL Type field, and select NFSv4 to apply this to the dataset.
After applying the NFSv4 ACL type to a dataset, you must configure the ACL.
If you uset the ACL Type setting on the Add Dataset > Advanced Options screen for a dataset with the Generic preset to change to an NFSv4 ACL, the Permissions widget for the dataset shows Unix Permission until you configure the NFSv4 ACL.
The Permissions widget for datasets with the SMB preset shows NFSv4 permissions, but you still need to configure the ACL permissions. The dataset does not have an ACL applied until you configure the ACL.
To edit or configure an NFSv4 ACL, select the dataset on the dataset tree table, then click Edit on the Permissions widget to open the Edit ACL screen.
You can change the owner and owner group, and/or change, add, or delete an ACE item on the Access Control List.
Either change the owner and owner group to the admin user on your system with full administration privileges or add the admin user name as an ACE item on the Access Control List.
This allows the admin user to make functional changes for the dataset and child datasets nested under it.
For example, when configuring shares and private dataset shares.
To rewrite the current ACL with a standardized preset, click Use Preset on the Edit ACL screen, which opens the Select a preset ACL window.
Select the preset option, then click Continue to apply the preset.
Presets load pre-configured permissions to match general permissions situations.
NFSv4 ACL Presets
NFS4_OPEN gives the owner and group full dataset control. All other accounts can modify the dataset contents.
NFS4_RESTRICTED gives the owner full dataset control. The group can modify the dataset contents.
NFS4_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_DOMAIN_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_ADMIN gives the admin user and builtin_administrators group full dataset control. All other accounts can navigate the dataset.
Adding NFSv4 ACL Entries
The Edit ACL screen shows the ACL owner and owner group and allows you to change both.
It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.
You can define the ACE entries when you first configure the NFSv4 ACL or change ACL entries (ACEs) and permissions for ACEs when you edit an existing ACL.
To edit an existing NFSv4 ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.
When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.
Click Add Item below the Access Control List on the left side of the screen.
If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List.
With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen.
Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset.
Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset.
This shows the Group field.
The group must be defined on the system.
In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users.
Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.
If Basic is selected, the Permissions dropdown list shows four options: Read, Modify, Traverse, and Full Control.
If Advanced is selected, the Permissions dropdown list shows 14 checkboxes for more granular control over the permissions granted to the selected ACE entry.
Options are: Read Data, Write Data, Append Data, Read Named Attributes, Write Named Attributes, Execute, Delete Children, Read Attributes, Write Attributes, Delete, Read ACL, Write ACL, Write Owner, and Synchronize.
(Optional) Select the ACL flags to apply the ACE item selected on the Access Control List, not to the entire ACL.
Each ACE entry can have different flags set. Flags apply to the files, directories, and subdirectories created in this dataset.
Flag options:
Basic shows the Inherit and No Inherit flags. Just as with the POSIX Default flag, this determines if files and directories in this dataset, for the ACE item selected (for example, a user item selected on the Access Control List), inherit the ACL from the dataset.
Advanced shows five flags for more granular control. Flag options are:
File Inherit - Selected by default. Limits ACL inheritance for files in the dataset for the selected ACE item.
Directory Inherit - Selected by default. Limits ACL inheritance for directories in the dataset for the selected ACE item.
No Propagate Inherit - Limits ACL inheritance to direct child directories. Files and directories created in this dataset inherit the ACL, but subdirectories cannot pass it further down the tree for the selected ACE item.
Inherit Only - Removes the ACE from permission checks but allows new files or subdirectories to inherit it for this dataset and the selected ACE item. Inherit Only is removed from these new objects.
Inherited - Selected by default. Indicates the selected ACE item inherited the ACL from the parent dataset (set by TrueNAS).
Selecting Advanced allows more granular control of file and directory permissions for a selected ACE item (such as a user) on the Access Control List.
See Debian nfs4_setfacl(1) NFSv4 ACL ENTRIES.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets.
This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.
If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.
If you change your mind and want to discard the changes and revert to using a preset, click Use Preset.
This reopens the Select a Preset window where you can select a different preset to apply to the dataset.
Viewing Permissions
Basic ACL permissions are viewable and configurable from the Permissions widget on the Datasets screen.
Select a dataset, then scroll down to the Permissions widget to view owner and individual ACL entry permissions.
To view the Edit ACL screen, select the dataset and click Edit on the Permissions widget, or go to Sharing and click on the share widget header to open the list of shares. Select the share, then click the options icon and select Edit Filesystem ACL.
You can view permissions for any dataset, but the edit option only displays on the Permissions widget for non-root datasets.
Shares
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares. TrueNAS allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
When creating zvols for shares, avoid giving them names with capital letters or spaces since they can cause problems and failures with iSCSI and NFS shares.
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
Contents
AFP Migration: Provides information on migrating AFP shares from FreeBSD- to Linux-based TrueNAS versions.
Block Shares (iSCSI): Describes the iSCSI protocol and has tutorials for various configuration scenarios.
Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.
Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.
Multiprotocol Shares: Provides instructions on setting up SMB and NFSv4 mixed-mode shares.
Windows Shares (SMB): Provides information on SMB shares and instructions on creating a basic share and setting up various specific configurations of SMB shares.
Managing SMB Shares: Provides instructions on managing existing SMB share and dataset ACL permissions.
Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.
NVMe-oF Subsystems: Provides information on NVMe-oF subsystems and instruction on creating a subsystem and setting up enterprise configurations of subsystems.
Managing NVMe-oF Subsystems: Provides information on managing NVMe-oF subsystems, namespaces, hosts, and ports.
AFP Migration
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
Since the Apple Filing Protocol (AFP) for shares is deprecated and no longer receives updates, it is not present in TrueNAS.
However, users can sidegrade AFP configurations into TrueNAS to migrate previously-saved AFP configurations into SMB configurations.
Migrating AFP Shares
To prevent data corruption that could result from the sidegrade operation, in TrueNAS, go to Windows (SMB) Shares, select the more_vert for the share, then select Edit to open the Edit SMB screen.
Click Advanced Options and scroll down to the Other Options section.
Select Legacy AFP Compatibility to enable compatibility for AFP shares migrated to SMB shares.
Do not select this option if you want a pure SMB share with no AFP relation.
Netatalk service is not present in TrueNAS 21.06 or later.
AFP shares automatically migrate to SMB shares with the Legacy AFP Compatibility option enabled.
Do not clear the Legacy AFP Compatibility checkbox, as it impacts how data is written to and read from shares.
Any other shares created to access these paths after the migration must also have Legacy AFP Compatibility selected.
Once you have migrated to TrueNAS, you can find your migrated AFP configuration in Shares >Windows Shares (SMB) with the prefix AFP_.
To make the migrated AFP share accessible, start the SMB service.
Connecting Migrated Shares
Since AFP shares migrate to SMB, you must use SMB syntax to mount them.
On your Apple system, press +K or go to Go > Connect to Server….
Enter smb://ipaddress/mnt/pool/dataset, where:
ipaddress* is your TrueNAS IP address
pool is the name of the pool
dataset is the name of the shared dataset
Block Shares (iSCSI)
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations.
IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack.
The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack.
Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance clould suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
OSI Layer Number
OSI Layer Name
Activity as it relates to iSCSI
7
Application
An application tells the CPU that it needs to write data to non-volatile storage.
6
Presentation
OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage.
5
Session
Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU).
4
Transport
OSI encapsulates the iSCSI PDU within a TCP segment.
3
Network
OSI encapsulates the TCP segment within an IP packet.
2
Data
OSI encapsulates the IP packet within the Ethernet frame.
1
Physical
The Ethernet frame transmits as bits (zeros and ones).
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing.
Block sharing provides the benefit of block-level access to data on the TrueNAS.
iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
iSCSI Terminology
Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively.
iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network.
The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes.
It also requires that each node is given a unique iSCSI name.
To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
dash (-)
dot (.)
colon (:)
lower case characters (a…z).
Upper-case characters must be mapped to their related lower-case counterparts.
digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN.
The result is an iSCSI connection that emulates a connection to a SCSI hard disk.
Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs.
When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size.
This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU).
A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways.
Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames.
Systems administrators should also account for the impact on host CPU utilization.
Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment.
Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.
TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system.
HA storage clusters can provide multiple paths to the same storage.
For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer.
The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage.
If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage.
When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.
iSCSI Configuration Methods
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores.
This is all managed through the vCenter web interface.
TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares.
This requires creating and populating zvol block devices with data, then setting up the iSCSI Share.
TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
Contents
Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Adding an iSCSI Block Share
Go to Shares and click Wizard on the Block (iSCSI) Shares Targets widget.
TrueNAS offers two methods to add an iSCSI block share: the setup wizard or the manual steps using the screen tabs.
Both methods cover the same basic steps but have some differences.
The setup wizard steps you through the process.
The setup wizard ensures you configure the iSCSI share completely so you can use it immediately.
The manual process has more configuration screens than the wizard and allows you to configure the block share in any order after creating the target.
Use this process to customize your share for special use cases.
It gives you additional flexibility to build or tune a share to your exact requirements.
Before You Begin
Before adding iSCSI shares, make sure you have already created a zvol or a dataset with at least one file to share. Do not use capital letters or spaces in the names or path.
Take note of the path to the zvol or file.
Creating a share with the iSCSI Wizard
Go to Shares, then click Wizard on the iSCSI Block Share Targets widget.
Click Create New on the Target screen, then click Next or on Extent to go to next screen.
a. Enter a name using up to 64 lowercase alphanumeric and/or special characters.
Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed.
b. Select the extent type. Choose between device and file based on your use case. The screen shows different settings based on the choice.
If using a zvol, select Device in Extent Type.
You can create a new zvol or select an existing zvol as the Device.
Adding a New Device
To create a new zvol, set Device to Create New.
Browse to select the path to the parent dataset using the file browser field below Pool/Dataset.
Selecting the parent dataset activates Create Dataset.
Click Create Dataset, enter a name that does not exceed 64 lowercase alphanumeric and/or special characters, then click Create.
The mount path under Pool/Dataset populates with the path to the new zvol.
To use an existing zvol, after selecting Device in Extent Type, select Existing, then browse to select the existing zvol.
Enter a numerical value and suffix to specify the size of the zvol you are creating in Size.
Adding a File
To use a file for the extent, select File in Extent Type.
Enter or browse to select the mount point to the directory you want to use.
If a directory does not exist, after selecting the parent dataset where you want to add the directory, enter a / followed by the name to add the directory to the dataset.
Enter the size for the directory in Filesize.
Leave this set to 0 to use the actual file size. This requires that the file already exists.
Otherwise, specify the file size for the new file.
c. Select the sharing platform, then click Next or on Protocol Options to advance to the next step.
Create a portal or select an available existing portal.
Select a portal from the dropdown list or click Create New to add a new portal.
If you create a new portal, click Add to enter an IP address and netmask (CIDR) for the portal. To add another, click Add again.
Leave Initiator blank to allow all, or enter a host name to limit access to the select client.
To enter more than one host name, press Enter after each to separate each entry.
You can edit initiators from the individual screens on the iSCSI screen after adding the target.
click Save.
iSCSI Manual Setup
This procedure guides you through adding an iSCSI share using the individual configuration screens.
While the procedure places each screen in order, you can select tab screens in any order.
Click on the Block (iSCSI) Share Targets widget header to open the iSCSI screen. The Targets screen shows by default.
b. Enter a name using lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in Target Name.
Use the iqn.format for the name. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
You can enter a common name for the target in Target Alias, but this is not required.
c. (Optional) Add authorized networks.
Click Add to show the Network fields to enter a publicly accessible IP address and netmask (CIDR).
This allows communication between client computers and the iSCSI target.
Click Add for each address you want to add.
Addresses are added to the iSCSI Authorized Networks widget.
d. (Optional) Click Add to the right of Add Groups to enter portal settings.
You can add a portal from the Portals screen. Click on the Portals tab, then click Add to open the Add iSCSI Portal screen.
Select a target with a number assignment from the dropdown list in Portal ID.
Select a group from the Initiator Group ID. You can add initiator groups (client groups) from the Initiators screen.
Click on the Initiators tab, then click Add to open the Add iSCSI Initiator screen.
Select the authentication method from the dropdown list.
None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication.
To show the Mutual CHAP option, you must set the peer user and secret password.
For more information on authentication methods, see iSCSI Screens.
The Authentication Group Number dropdown list populates after configuration groups on the Add Authorized Access screen.
Edit the target after adding these groups if you want to include them.
e. Click Save.
Add extent(s). Click on the Extents tab, then click Add to open the Add iSCSI Extent screen.
b. Add a description about the extent if you want, but this is not required.
The description shows in the Target table on the Targets screen and the iSCSI Block Share Targets widget and helps identify the share use or purpose.
c. Select Enabled to enable the extent.
d. Leave Enable TCP selected. To disable it, clear the checkbox.
Select Xen initiator compat mode if required for your share.
e. Set the device type as Device or File.
Adding a Device Extent
After choosing **Device** in **Extent Type**, select the zvol or zvol snapshot from the **Device** dropdown list. The zvol must already exist to add it here.
Accept the default in **Logical Block Size** or change the size to what fits your use case.
Adding a File Extent
After choosing **File** in **Extent Type**, enter or browse to select the path to an existing file.
Enter a slash (/) followed by a file name to create a file in a dataset and append the file name to the path (/filename.ext).
Enter the file size. Enter **0** to use the actual file size of an existing file, or specify the size to apply to the new file added in **Path to the Extent**.
f. Leave Disable Physical Block Size Reporting disabled unless you want to enable this function.
g. Enter a product identification for the extent in Product ID or leave it blank to use the default iSCSI Disk used when left empty.
h. Click Save.
Add initiator groups. Click on the Initiators tab, then click Add to open the Add Initiator screen.
Leave Allow All Initiators selected, or clear and enter the host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Click Save.
Add portals. Click on the Portals tab, then click Add to open the Add Portal screen.
a. Enter a number in Group ID. This field configures different groups with different authentication profiles.
For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.
b. Select the discovery method from the dropdown list. None allows anonymous discovery. CHAP uses one-way discovery.
Mutual CHAP uses two-way discovery, but not show as an option until you add the Peer User and Peer Secret credentials.
c. Enter a username and password for CHAP authentication to the remote system. These can be the admin user account credentials.
d. Enter a peer user account and password if using Mutual CHAP authentication.
The Peer Secret cannot be the same password entered in Secret. You can select Mutual CHAP as the discovery method now.
e. Click Save.
Creating a Quick iSCSI Target
TrueNAS allows users to add iSCSI targets without adding the extent, portal, initiators, etc. You can create the target and add the rest later.
Go to Shares and click the Block (iSCSI) Shares Targets widget header to open the iSCSI screen with the Targets tab selected by default.
Click Add to open the Add iSCSI Target screen.
Enter a name in Target Name. Use lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in the iqn.format.
See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
(Optional) Enter a user-friendly name in Target Alias.
Add authorized networks. Click Add to show the Network fields where you can enter an IP address and netmask (CIDR).
This allows communication between client computers and the iSCSI target. Click Add for each address you want to add.
Addresses are added to the authorized networks list.
Click Add to the right of Add Groups to enter portal settings.
Portal and group settings can be added later or on the Add Portal screen, and initiator groups can be added by editing the target or using the Add Initiators screen.
Select a target with a number assignment from the dropdown list in Portal ID.
Select the authentication method from the dropdown list.
None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication.
For more information on authentication methods, see iSCSI Screens.
Select a portal ID from the Initiator Group ID dropdown list.
The Authentication Group Number dropdown list is populated after configuration groups on the Add Authorized Access screen.
Edit the target after adding these groups if you want to include them.
Click Save.
Starting the iSCSI Service
After adding a share with the iSCSI wizard or manual entry screens, the system shows a dialog prompting you to start or restart the service.
You can also start the service by clicking on the more_vert on the Block (iSCSI) Shares Targets widget and selecting Turn On Service.
You can go to System > Services, locate iSCSI on the service list, and click the Start Service button to start the service.
Setting Up Fibre Channel
The Fibre Channel feature is available to Enterprise-licensed High Availability (HA) and non-HA systems.
Any Enterprise system, equipped with the required fibre channel hardware can implement this feature.
This article provides instructions for VMware VCenter ESXi.
If you are using a different platform for your block share backups, use the documentation for that platform for alternative instructions for the ESXi process documented in this tutorial.
.
Before You Begin
When setting up iSCSI fibre channel for the first time:
(Optional) Create a zvol for each fibre channel port with a network interface associated with it.
The wizard provides an option to create a dataset on the Extents screen when adding the device.
Selecting this option creates a dataset for organizational purposes and a zvol of the same name for block storage.
Configuring Fibre Channel - First-Time Install
We recommend using the iSCSI wizard to create your target, create the extents, and set up fibre channel ports.
If the system is a High Availability (HA) system, turn on ALUA.
Click on the iSCSI widget header to open the Sharing iSCSI screens. Click on Global Target Configuration. Scroll down and select Asynchronous Logic Unit Access (ALUA), then click Save.
b. Select Device in Extent Type, then select Create New on the Device dropdown list.
When selecting Create New, the Pool/Dataset and /mnt fields display.
Navigate through the pool and datasets to select the zvol and populate the /mnt field with the path.
Clicking Create Dataset allows you to add a dataset where the /mnt path indicates. TrueNAS creates the dataset for organizational purposes and a zvol of the same name for block storage.
c. Enter a value in Size.
d. Select the platform option that matches your use case and for this iSCSI share on the Sharing Platform dropdown list.
For example, if using the VMware ESXi platform for your block storage, select VMware: Extent block size 512b, TCP enabled, no Xen compat mode, SSD speed.
e. Click Next to show the Protocol Options screen.
Select the protocol option for your use case.
When installing iSCSI fibre channel ports the first time, select Create new virtual port.
Start the iSCSI service when prompted.
If you did not stop the iSCSI service, restart it by clicking the more_vert button, stop the service, and when the status indicates it is stopped, start it.
Log into your block storage backup platform (i.e., VCenter ESXi) and configure your adaptors, devices, and datastores.
Refer to VMWare or documentation for the platform used for instructions on completing the configuration.
Using an iSCSI Share
Connecting to and using an iSCSI share can differ between operating systems.
This article provides instructions on setting up a Linux and Windows system to use the TrueNAS iSCSI block share.
Using Linux iSCSI Utilities and Service
In this section, you start the iSCSI service, log in to the share, and obtain the configured basename and target. You also partition the iSCSI disk, make a file system for the share, mount it, and share data.
Click here for more information
Before you begin, open the command line and ensure you have installed the open-iscsi utility.
To install the utility on an Ubuntu/Debian distribution, enter command sudo apt update && sudo apt install open-iscsi.
After the installation completes, ensure the iscsid service is running using the sudo service iscsid start command.
First, with the iscsid service started, run the iscsiadm command with the discovery arguments and get the necessary information to connect to the share.
Next, discover and log into the iSCSI share.
Run the command sudo iscsiadm \--mode discovery \--type sendtargets \--portal {IPADDRESS}.
The output provides the basename and target name that TrueNAS configured.
Alternatively, enter sudo iscsiadm -m discovery -t st -p {IPADDRESS} to get the same output.
Note the basename and target name given in the output. You need them to log in to the iSCSI share.
When a Portal Discovery Authentication Method is CHAP, add the three following lines to /etc/iscsi/iscsid.conf.
discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = user
discovery.sendtargets.auth.password = secret
The user for discovery.sendtargets.auth.username is set in the Authorized Access used by the iSCSI share Portal.
Likewise, the password to use for discovery.sendtargets.auth.password is the Authorized Access secret.
Without those lines, the iscsiadm does not discover the portal with the CHAP authentication method.
Enter comand sudo iscsiadm \--mode node \--targetname {BASENAME}:{TARGETNAME} \--portal {IPADDRESS} \--login,
where {BASENAME} and {TARGETNAME} is the discovery command information.
Now you partition an iSCSI disk.
When the iSCSI share login succeeds, the device shared through iSCSI shows on the Linux system as an iSCSI Disk.
To view a list of connected disks in Linux, enter command sudo fdisk -l.
Because the connected iSCSI disk is raw, you must partition it.
Identify the iSCSI device in the list and enter sudo fdisk {/PATH/TO/iSCSIDEVICE}.
Use the fdisk command defaults when partitioning the disk.
Remember to type w when finished partitioning the disk.
The w command tells fdisk to save any changes before quitting.
After creating the partition on the iSCSI disk, a partition slice displays on the device name.
For example, /dev/sdb1.
Enter fdisk -l to see the new partition slice.
Next, make a file system on the iSCSI disk.
Finally, use mkfs to make a file system on the new partition slice.
To create the default file system (ext2), enter sudo mkfs {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.
Mount the iSCSI device and share the data.
Enter sudo mount {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.
For example, sudo mount /dev/sdb1 /mnt mounts the iSCSI device /dev/sdb1 to file /mnt.
Using the iSCSI Share with Windows
This section provides instructions on setting up Windows iSCSI Initiator Client to work with TrueNAS iSCSI shares.
Hyper-V hosts that connect to a TrueNAS system with high availability (HA) require additional multipath and failover cluster tuning.
See Hyper-V Best Practices.
Click here for more information
To access the data on the iSCSI share, clients need to use iSCSI Initiator software. An iSCSI Initiator client is pre-installed in Windows 7 to 10 Pro, and Windows Server 2008, 2012, and 2019. Windows Professional Edition is usually required.
First, click the Start Menu and search for the iSCSI Initiator application.
Next, go to the Configuration tab and click Change to replace the iSCSI initiator with the name created earlier. Click OK.
Next, switch to the Discovery Tab, click Discover Portal, and type in the TrueNAS IP address.
If TrueNAS changed the port number from the default 3260, enter the new port number.
If you set up CHAP when creating the iSCSI share, click Advanced…, set Enable CHAP log on, and enter the initiator name and the same target/secret set earlier in TrueNAS.
Click OK.
Go to the Targets tab, highlight the iSCSI target, and click Connect.
After Windows connects to the iSCSI target, you can partition the drive.
Search for and open the Disk Management app.
The current state of your drive should be unallocated. Right-click the drive and click New Simple Volume….
Complete the wizard to format the drive and assign a drive letter and name.
Finally, go to This PC or My Computer in File Explorer. The new iSCSI volume should display under the list of drives. You should now be able to add, delete, and modify files and folders on your iSCSI drive.
Increasing iSCSI Available Storage
Expanding LUNs
TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage in an iSCSI share.
Zvol LUNs
To expand a Zvol LUN, go to Datasets and click the Zvol LUN name. The Zvol Details widget displays. Click the Edit button.
TrueNAS prevents data loss by not allowing users to reduce the Zvol size.
TrueNAS also does not allow users to increase the Zvol size past 80% of the pool size.
File LUNs
Go to Shares and click Configure in the Block (iSCSI) Shares Targets screen, then select the Extents tab.
Enter a new size in Filesize.
Enter the new value as an integer that is one or more multiples of the logical block size (default 512) larger than the current file size.
Click Save.
Adding NFS Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
About UNIX (NFS) Shares
Creating a Network File System (NFS) share on TrueNAS makes a lot of data available for anyone with share access.
Depending on the share configuration, you can restrict users to read or write privileges.
NFS treats each dataset as its own file system. When creating the NFS share on the server, the specified dataset is the location that the client accesses.
If you choose a parent dataset as the NFS file share location, the client cannot access any nested or child datasets beneath the parent.
If you need to create shares that include child datasets, SMB sharing is an option. Note that Windows NFS Client versions currently support only NFSv2 and NFSv3.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Creating an NFS Share and Dataset
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
You have the option to create the share and a dataset at the same time from either the Add Dataset or Add NFS screens.
If creating a dataset and share from the Add Dataset screen, we recommend creating a new dataset with the Dataset Preset set to Generic for the new NFS share.
Or you can set it to Multiprotocol and only select the NFS share type.
Creating a Dataset Using Add Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
To create the share and dataset from the Add NFS Share screen:
Go to Shares > Unix (NFS) Shares and click Add to open the Add NFS Share configuration screen.
Enter the path or use the arrow_right icon to the left of /mnt to locate the dataset and populate the path.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Create Dataset, enter a name for the dataset, and click Create.
The system creates the dataset optimized for an NFS share, populates the share Name, and updates the Path with the dataset name.
The dataset name is the share name.
Enter text to help identify the share in Description.
Enable Service turns the NFS service on and changes the toolbar status to Running.
If you wish to create the share without immediately enabling it, select Cancel.
Adding NFS Share Networks and Hosts
If you want to enter allowed networks, click Add to the right of Networks.
Enter an IP address in Network and select the mask CIDR notation.
Click Add for each network address and CIDR you want to define as an authorized network.
Defining an authorized network restricts access to all other networks. Leave empty to allow all networks.
Click Add to the right of Hosts if you want to enter allowed systems.
Enter a host name or IP address to allow that system access to the NFS share.
Click Add for each allowed system you want to define.
Defining authorized systems restricts access to all other systems.
Press the X to delete the field and allow all systems access to the share.
Adjusting Access Permissions
To tune the NFS share access permissions or define authorized networks, click Advanced Options.
Select Read-Only to prohibit writing to the share.
To map user permissions to the root user, enter a string or select the user from the Maproot User dropdown list.
To map the user permissions to all clients, enter a string or select the user from the Mapall User dropdown list.
To map group permissions to the root user, enter a string or select the group from the Maproot Group dropdown list.
To map the group permissions to all clients, enter a string or select the group from the Mapall Group dropdown list.
Select an option from the Security dropdown. If you select KRB5 security, you can use a Kerberos ticket. Otherwise, everything is based on IDs.
Security Types
Setting
Description
SYS
Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5
Uses Kerberos for authentication.
KRB5I
Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P
Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.
Editing an NFS Share
To edit an existing NFS share, go to Shares > Unix (NFS) Shares and click the share you want to edit.
The Edit NFS screen settings are identical to the share creation options, but you cannot create a new dataset.
Starting the NFS Service
To begin sharing, click the more_vert on the toolbar and select Turn On Service. Turn Off Service displays if NFS is on. Turn On Service displays if NFS is off.
Or you can go to System > Services, locate NFS, and click the Start Service button to start the service.
Toggle Start Automatically on if you want NFS to activate when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
Configuring the NFS Service
You can configure the NFS service from either the System > Services screen or the Shares > Unix (NFS) Shares widget.
To configure NFS service settings from the Services screen, click edit on the System > Services screen to open the NFS service screen.
To configure NFS service settings from the Shares > Unix (NFS) Shares widget, click the Config Service from the more_vert dropdown menu on the widget header to open the NFS service screen.
Unless you need specific settings, we recommend using the default NFS settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
TrueNAS Enterprise
NFS over RDMA
TrueNAS Enterprise customers utilizing NFS shares with compatible hardware can enable NFS over RDMA to improve NFS performance and efficiency.
Remote Direct Memory Access (RDMA) lets a client system transfer data directly from server memory to its own, improving speed, reducing latency, and lowering CPU usage.
NFS over RDMA support requires an active Enterprise license and RDMA-capable network interface cards (NICs) in the TrueNAS host and client systems.
Interested customers should contact Enterprise Support for assistance.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Although you can connect to an NFS share with various operating systems, we recommend using a Linux/Unix OS.
First, download the nfs-common kernel module.
You can do this using the installed distribution package manager.
For example, on Ubuntu/Debian, entering the command sudo apt-get install nfs-common in the terminal.
After installing the module, connect to an NFS share by entering sudo mount -t nfs {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}.
Where {IPaddressOfTrueNASsystem} is the remote TrueNAS system IP address that contains the NFS share, {path/to/nfsShare} is the path to the NFS share on the TrueNAS system, and {localMountPoint} is a local directory on the host system configured for the mounted NFS share.
For example, sudo mount -t nfs 10.239.15.110:/mnt/Pool1/NFS_Share /mnt mounts the NFS share NFS_Share to the local directory /mnt.
You can also use the Linux nconnect function to let your NFS mount support multiple TCP connections.
To enable Linux nconnect, enter sudo mount -t nfs -o rw,nconnect=16 {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}.
Where {IPaddressOfTrueNASsystem}, {path/to/nfsShare}, and {localMountPoint} are the same ones you used when connecting to the share.
For example, sudo mount -t nfs -o rw,nconnect=16 10.239.15.110:/mnt/Pool1/NFS_Share /mnt.
By default, anyone who connects to the NFS share only has read permission.
To change the default permissions, edit the share, open the Advanced Options, and change the Access settings.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
You must have ESXI 6.7 or later for read/write functionality with NFSv4 shares.
Multiprotocol Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS 25.04.0: Time Machine shares are incompatible with multiprotocol (SMB/NFS) shares. TrueNAS automatically disables SMB2/3 lease support and AAPL extensions globally when multiprotocol shares are configured, preventing Time Machine functionality.
TrueNAS 25.04.1 and later: This limitation is removed. Multiprotocol shares now use per-share oplock management instead of global oplock disabling, allowing Time Machine and Final Cut Pro Storage Share shares to coexist with multiprotocol shares on the same system. SMB leases are permitted globally, with oplocks disabled only at the multiprotocol share level.
About Multi-Protocol Shares
A multi-protocol or mixed-mode NFS and SMB share supports both NFS and SMB protocols for sharing data.
Multi-protocol shares allow clients to use either protocol to access the same data.
This can be useful in environments with a mix of Windows systems and Unix-like systems, especially if some clients lack an SMB client.
Carefully consider your environment and access requirements before configuring a multi-protocol share.
For many applications, a single protocol SMB share provides a better user experience and ease of administration.
Linux clients can access SMB shares using mount.cifs.
To ensure security and data integrity when using multi-protocol sharing, it is important to properly configure permissions and access controls.
To maximize security on the NFS side of the multi-protocol share, we recommend using NFSv4 and Active Directory(AD) for Kerberos authentication.
It is also important that NFS clients preserve extended attributes when copying files, or SMB metadata could be discarded in the copy.
Multi-protocol shares are not compatible with APPL extensions such as Time Machine that rely on SMB3/3 lease support, which is no longer available in multi-protocol shares.
Choosing to configure a multi-protocol share disables options to enable AAPL extensions globally.
First Steps
Before adding a multi-protocol SMB and NFS share to your system:
Configure and start the SMB and NFS services.
Configure the NFS service to require Kerberos authentication.
Join the TrueNAS server to an existing Active Directory domain.
Configure a container, Kerberos admin, and user accounts in AD.
Before joining AD and creating a dataset for the share, start both the SMB and NFS services and configure the NFS service for Kerberos authentication.
Configure the NFS service before joining AD for a simpler Kerberos credential creation.
To configure services, you can use the Shares screen Config Service option on both the Windows (SMB) Share and the UNIX (NFS) Shares widgets, or go to System > Services and select the Edit option for the SMB and NFS services.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default SMB service settings.
After configuring the SMB and NFS share services, start the services.
From the Shares screen, click on the Windows (SMB) Sharesmore_vert to show the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
After adding a share, use the toggle to enable or disable the service for that share.
To enable the service from the System > Services screen, click the Start Service button to start the service and toggle Start Automatically on if you want the service to activate when TrueNAS boots.
Configuring and Starting the NFS Service
Open the NFS service screen, then select only NFSv4 on the Enabled Protocols dropdown list.
For security hardening, we recommend disabling the NFSv3 protocol.
Select Require Kerberos for NFSv4 to enable using a Kerberos ticket, then click Save.
TrueNAS automatically generates and applies the Kerberos service principal name (SPN) for the NFS service when the system joins Active Directory or FreeIPA.
No manual SPN configuration is required.
Start the NFS service.
Go to the Shares screen, click on the Unix (NFS) Sharesmore_vert to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
Each NFS share on the list also has a toggle to enable or disable the service for that share.
To enable the service from the System > Services screen, click the Start Service icon to start the service and toggle Start Automatically on to start the service when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
Joining Active Directory
Multi-protocol SMB and NFS shares greatly simplify data access for clients running a range of operating systems.
They also require careful attention to security complexities not present in standard SMB shares.
NFS shares do not respect permissions set in the SMB share ACL.
Protect the NFS export with proper authentication and authorization controls to prevent unauthorized access by NFS clients.
We recommend using Active Directory to enable Kerberos security for the NFS share.
Configure a container (group or organizational unit), Kerberos admin, and user accounts in AD.
Creating a Multi-Protocol Share
You can create a share and a dataset from either the Add Dataset or Add SMB screen.
The multi-protocol share type is mutually exclusive with AAPL extension support, like Time Machine.
These extensions require the SMB2/3 lease support, which is no longer available in multi-protocol shares.
Therefore, the Multi-Protocol Share option does not include a Time Machine option. Selecting other Apple protocol options displays warning messages.
Multi-protocol shares can impact the performance of all SMB shares.
Using the Add Dataset Screen
TrueNAS allows you to create the dataset and add a multi-protocol (SMB and NFS) share using the Add Dataset screen.
This is the recommended method when creating a multi-protocol share.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
Select the parent dataset where you want to add the multi-protocol dataset, then click Add Dataset.
Enter a name for the dataset.
Select Multiprotocol from the Dataset Preset dropdown.
The share configuration options display with Create NFS Share and Create SMB Share preselected.
The dataset name populates the SMB Name field and becomes the name of the SMB and NFS shares.
(Optional) Click Advanced Options to customize other dataset settings such as quotas, compression level, encryption, and case sensitivity.
See Creating Datasets for more information on adding and customizing datasets.
Click Save.
TrueNAS creates the dataset and the SMB and NFS shares.
TrueNAS sets the same share presets as the Multi-Protocol Share option in Purpose on the Advanced Options for the Add SMB screen.
To configure other share settings, go to Shares, select the share, click on the more_vert icon, and select Edit to open the Edit SMB screen, and click Advanced Options to modify the settings.
After adding the dataset, edit the dataset ACL.
Using the Add SMB Screen
Adding a multi-protocol share from the Add SMB screen creates the SMB share and the dataset, but you must also use the Add NFS screen to add the NFS share.
To create a share and a dataset from the Add SBM share screen, go to Shares, and click Add on the Windows (SMB) Shares widget to open the Add SMB screen.
Enter or browse to select the parent dataset where you want to add the share dataset, then click Create Dataset.
Enter a name for the dataset/share, then click Create Dataset. The Path field populates with the path to the dataset, and the Name field populates with the dataset/share name. Both the dataset and the share have the same name.
Select Multi-Protocol Shares on the Purpose dropdown list.
This applies the pre-determined Other Options selected on the Advanced Options screen.
Click Advanced Options to modify any settings you want to use. Multi-mode shares cannot use APPL extension settings like Time Machine.
(Optional) Enter a Description to help explain the share purpose.
Click Save.
Configure the ACL when prompted.
Click Add on the UNIX (NFS) Shares widget to open the Add NFS screen.
Set the path to the same dataset created for the SMB share.
Customize the NFS share to suit your use case, and click Save.
Restart the NFS and SMB services when prompted.
You can modify share settings after creating it.
Editing the NFS Share
After creating the multi-protocol share on the Add Dataset screen, if you want to customize the NFS share further, go to Shares and edit the NFS share.
Select the new share listed on Unix (NFS) Shares widget, click on the more_vert icon and then click Edit.
The Edit NFS screen opens with the Basic Options settings showing.
Enable Kerberos security. Click Advanced Options.
Select KRB5 from the Security dropdown to enable the Kerberos ticket generated when you joined Active Directory.
If needed, select Read-Only to prohibit writing to the share.
Click Save.
Start or restart the service when prompted.
Adjusting the Dataset ACL
After joining AD and creating a multi-protocol dataset and the SMB and NFS shares, adjust the dataset permission or use the SMB file system permissions to match the container and users configured in AD.
You can modify dataset permissions from the Shares screen using securityEdit Filesystem ACL to open the Edit ACL screen for the selected share (SMB and NFS).
Select the share row on the widget, then click the edit icon to modify permissions for the share dataset.
Note: editing the dataset permissions sets permissions for the SMB and NFS.
Using the Edit Filesystem ACL only edits permissions for the SMB share in the multi-protocol share configuration.
Or go to Datasets, select the dataset row created for the multi-protocol share on the Datasets table, then scroll down to the Permissions widget for the dataset.
Click Edit to open the Edit ACL screen.
Check the Access Control List to see if the AD group you created is on the list and has the correct permissions.
If not, add this Access Control Entry (ACE) item on the Edit ACL screen for the multi-protocol dataset (or each share).
Enter Group in the Who field or use the dropdown list to select Group.
Type or select the appropriate group in the Group field.
Verify Full Control displays in Permissions. If not, select it from the dropdown list.
Click Save Access Control List to add the ACE item or save changes.
See Permissions for more information on editing dataset permissions.
After setting the dataset permission, connect to the share.
Connecting to a Multi-Protocol Share
After creating and configuring the shares, connect to the multi-protocol share using either SMB or NFS protocols from a variety of client operating systems, including Windows, Apple, FreeBSD, and Linux/Unix systems.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
About Windows (SMB) Shares
SMB (also known as CIFS) is the native file-sharing system in Windows.
SMB shares can connect to most operating systems, including Windows, Mac OS, and Linux.
TrueNAS can use SMB to share files among single or multiple users or devices.
SMB supports a wide range of permissions, security settings, and advanced permissions (ACLs) on Windows and other systems, as well as Windows Alternate Streams and Extended Metadata.
SMB is suitable for managing and administering large or small pools of data.
TrueNAS uses Samba to provide SMB services.
The SMB protocol has multiple versions. During the SMB session negotiation, a typical SMB client can negotiate the highest supported SMB protocol.
Industry-wide, SMB1 protocol (sometimes referred to as NT1) use is deprecated for security reasons.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
However, most SMB clients support SMB 2 or 3 protocols even when they are not the default.
Legacy SMB clients rely on NetBIOS name resolution to discover SMB servers on a network.
TrueNAS disables the NetBIOS name server (nmbd) by default. Enable it on the Network > Global Settings screen if this functionality is required.
Mac OS clients use mDNS to discover SMB servers present on the network. TrueNAS enables the mDNS server (avahi) by default.
Windows clients use WS-Discovery to discover the presence of an SMB server.
You can disable network discovery by default depending on the Windows client version.
Discoverability through broadcast protocols is a convenience feature and is not required to access an SMB server.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
How do I add an SMB Share?
Verify your Active Directory connections are working and error-free before adding an SMB share.
When an SMB share is configured but not working or is in an error state, AD cannot bind, and TrueNAS cannot start the SMB service.
Creating an SMB share on your system requires adding the share and then getting it working.
You can manually add user accounts or use Active Directory to provide additional user accounts.
If setting up an external SMB share, we recommend using Active Directory, or at a minimum, synchronizing the user accounts between systems.
You can use the Add SMB screen to create a basic SMB share or a more specific share type with specific feature requirements using the Advanced Options settings before saving the share.
The Add Dataset and the Add SMB share screens allow TrueNAS to create a dataset and SMB share from the same screen.
Use either option to create a basic SMB share.
When creating an SMB share that requires customization or is intended for a specific purpose, such as working with Veeam Backup & Restore immutability or a repository for block or fast cloning (requires an Enterprise license), use the Add SMB screen Purpose presets to create the share and dataset for these special SMB shares.
For more information on Veeam SMB shares, refer to the Solutions > IntegrationsVeeam and Veeam Immutability guides.
When setting up multi-protocol (SMB and NFS) shares, refer to the Multiprotocol Shares tutorial for configuration instructions.
This article describes adding a dataset while adding the share using the Add SMB screen.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled.
You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To add or edit users, go to Credentials > Users, then add or edit an existing user to create the SMB share user(s).
Click Add to create a new user or as many new user accounts as needed.
Joining TrueNAS to Active Directory creates the user accounts.
Enter the values in each required field, verify SMB Access is selected, then click Save.
For more information on the fields and adding users, see Creating User Accounts.
By default, all new users are members of a built-in group called builtin_users.
You can use a group to grant access to all users on the server or add more groups to fine-tune permissions for large numbers of users.
Why not just allow anonymous access to the share?
Anonymous or guest access to the share is possible, but allowing guest access can create a security vulnerability, so it is not recommended for Enterprise customers or systems with more than one SMB share administrator account.
Using a guest account increases the likelihood of unauthorized users gaining access to your data in the SMB share.
Major SMB client vendors are deprecating guest users, partly because signing and encryption are impossible for guest sessions.What about LDAP users?
Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel).
Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.
Adding an SMB Share and Dataset
You can create an SMB share while creating a dataset on the Add Dataset screen or create a dataset and the share using the Add SMB share screen.
This article covers adding the dataset using the Add SMB share screen.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
What are ZFS dataset setting defaults?
TrueNAS creates the ZFS dataset with these settings:
ACL Mode set to Restricted
The ACL Type influences the ACL Mode setting. When ACL Type is set to Inherit, you cannot change the ACL Mode setting.
When ACL Type is set to NFSv4, you can change the ACL Mode to Restricted.
For datasets with NFSv4 ACL type, SMB clients automatically use access-based enumeration.
This means directory listings over SMB only include files and directories for which the client has read permissions.
This behavior is enabled by default and matches FreeBSD behavior.
Case Sensitivity set to Insensitive
TrueNAS also applies a default access control list to the dataset.
This default ACL is restrictive and only grants access to the dataset owner and group.
You can modify the ACL later according to your use case.
If you want to organize the SMB share dataset under a parent dataset (for example, under smb-shares), create that parent dataset so you can select it as the parent in step 2 below.
Alternatively, you can create the parent and SMB share dataset using the Create Dataset option associated with the file browser in the Add SMB screen by making the create dataset instructions a two-=step process.
To create a basic Windows SMB share and a dataset, go to Shares, then click Add on the Windows Shares (SMB) widget to open the Add Share screen.
Enter or browse to select the SMB share mount path (parent dataset where you want to add a dataset for this share).
You cannot use a root dataset for a share. When the dataset selected has an existing ACL, a warning dialog shows. Click Continue.
Click on the dataset under which you want to add the SMB share dataset.
The blank Path field populates with the path selected in the file browser field directly below it.
The Path file browser field is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Create Dataset.
Enter a name for the dataset in the Create Dataset dialog, then click Create.
The system creates the new dataset and populates the Name field with the dataset name, which becomes the share
To make the new dataset the parent for an SMB share, select the just-added dataset, then click Create Dataset again to add the child dataset for the share.
The path forms part of the share pathname when SMB clients perform an SMB tree connect.
Because of how the SMB protocol uses the name, it must be less than or equal to 80 characters.
Do not use invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6.
If you change the name, follow the naming conventions for:
Select a share type on the Purpose dropdown list.
The share type selected locks or unlocks the pre-determined Advanced Options settings for the share.
Select Default Share to create a basic SMB share with the Browsable to Network Clients option preselected.
This determines whether this share name is included when browsing shares.
Select Private Datasets Share to create an alternative to home shares.
See Setting Up SMB Home Shares for more information on replacing this legacy feature with private SMB shares and datasets.
Select Multi-protocol Share to create a multi-protocol share (NFSv4/SMB). Set this if the path is shared through NFS, FTP, or used by containers or apps.
Note: This setting can reduce SMB share performance as it turns off some SMB features for safer interoperability with external processes.
See Setting Up SMB Multichannel for more information on creating multi-protocol shares.
Select Time Machine Share to create a Time Machine share. The SMB share is presented to Mac OS clients as a Time Machine target.
See Adding a Basic Time Machine SMB Share for more information on creating and using Time Machine shares.
Select Final Cut Pro Storage Share (available in TrueNAS 25.10.1 and later) to create a share optimized for Final Cut Pro workflows.
The SMB share is configured with Apple-style character encoding and requires Apple SMB2/3 protocol extensions for compatibility with Final Cut Pro.
See Setting Up Final Cut Pro SMB Shares for more information on creating shares for Final Cut Pro workflows.
Select External Share to create an external share. Enter the full domain name or IP address and the share name as 192.168.0.200\SHARE in Remote Path.
Select Time Locked Share to create a share that makes files read-only after the grace period you specify expires.
This setting does not work if the path is accessed locally or if another SMB share with the Time Locked Share purpose uses the same path.
Warning: This setting might not meet regulatory requirements for write-once storage.
(Optional) Enter a short description or explanation of the share purpose or use in Description.
This shows on both the SMB widget and Share > SMB screen to help explain how the share is used.
For example, if for an external share, enter external share in the field.
The description entered shows in the SMB table on the SMB screen and the Windows (SMB) Share widget.
Select Enabled to allow sharing of this path when the SMB service is activated.
Leave the checkbox cleared to disable the share without deleting the configuration.
(Optional) Click Advanced Options to show additional configuration settings.
Click to configure other advanced settings such as access, audit logging, or settings specific to the type of share selected in Purpose.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
Start or restart the SMB service when prompted.
Configuring Advanced Options
A basic SMB share does not need to use the Advanced Options settings. Click Advanced Options to finish customizing the SMB share settings.
Guest access adds security vulnerabilities and should be avoided.
Guest access allows users to connect to an SMB share without providing credentials.
In TrueNAS SCALE 25.10 and later, this feature is only available for shares with the Legacy Share preset (shares that used No Preset in releases before 25.10).
To enable guest access on a Legacy Share:
Go to Shares and click on the share name to expand the share widget, then click Edit.
Click Advanced Options and scroll down to the Access settings.
Select the Allow Guest Access checkbox.
Click Save.
The privileges granted are the same as those for a guest account.
Windows 10 version 1709 and later, and Windows Server 2019 and later disable guest access by default as a security measure.
Windows clients require additional configuration to connect to shares with guest access enabled.
To enable guest access on Windows clients, modify Windows registry settings or Group Policy to allow insecure guest logons.
See Microsoft documentation for configuration details.
For new shares:
New shares created in TrueNAS SCALE 25.10 and later cannot select the Legacy Share preset, and therefore cannot use guest access.
Guest access has been limited to legacy shares due to security concerns and client-side deprecation:
Windows 10 version 1709 and Windows Server 2019 and later disable guest access by default
Major SMB client vendors are deprecating guest users
Guest sessions cannot use signing and encryption features
Client-specific behavior:
Mac OS clients - Prevent automatic connection as guest account.
Users must explicitly select Connect As: Guest.
See the Apple documentation for more details.
Windows clients - Require registry or Group Policy modifications to enable insecure guest authentication
Alternative approaches:
Instead of guest access, consider these secure alternatives:
Create a dedicated guest user account with limited permissions
Use share ACL to restrict the guest user to read-only access
To prohibit writes to the share, select Export Read-Only.
Select Access Based Share Enumeration to restrict share visibility for users with read or write access to the share.
This setting applies to datasets with a POSIX ACL type.
For datasets with NFSv4 ACL type, access-based enumeration is automatically enabled and does not allow disabling.
See the smb.conf manual page.
Host Allow and Host Deny
Hosts Allow and Hosts Deny settings are available for all share presets except External Share.
Use the Host Allow and Host Deny options to allow or deny specific host names and IP addresses.
Use the Hosts Allow field to enter a list of allowed IP addresses.
Separate entries by pressing Enter.
Entering values in the Host Allow restricts access to only the addresses entered into this list!
This list can break UI access for all other IP or host name entries.
You can find a more detailed description with examples here.
Use the Hosts Deny field to enter a list of denied host names or IP addresses. Separate entries by pressing Enter.
Hosts Allow and Hosts Deny work together to produce different situations:
Leaving both Hosts Allow and Hosts Deny free of entries allows any host to access the SMB share.
Adding entries to the Hosts Allow list but not the Hosts Deny list allows only the hosts on the Hosts Allow list to access the share.
Adding entries to the Hosts Deny list but not the Hosts Allow list allows all hosts not on the Hosts Deny list to access the share.
Adding entries to both a Hosts Allow and Hosts Deny list allows all hosts on the Hosts Allow list to access the share and allows hosts not on the Hosts Allow or Hosts Deny list to access the share.
Legacy Share Preset (Upgraded Shares Only)
What is a legacy share?
When you upgrade to TrueNAS SCALE 25.10 from an earlier release, existing shares that used the No Preset option are automatically migrated to the Legacy Share preset.
This preset provides access to configuration options that are no longer available for new shares.
Why can I not create a new legacy share?
The Add SMB screen does not include Legacy Share as an option. This preset only appears in the Edit SMB screen for shares created before 25.10.
TrueNAS removed these options from new shares due to:
Security concerns (guest access, recycle bin)
Better alternatives available (ZFS snapshots instead of recycle bin)
Client-side deprecation (guest access no longer supported by major vendors)
Legacy share options:
Legacy shares provide access to additional settings not available in modern presets.
AFP shares are deprecated and not available in TrueNAS.
To customize your SMB share to work with a migrated AFP share or with your Mac OS, use the share option on the Purpose dropdown list and the Advanced Options settings provided for these use cases:
Use Apple-style Character Encoding, listed under Other Options for all share types except Time Machine Share and External Share, converts NTFS illegal characters like the Mac OS SMB clients do.
By default, Samba uses a hashing algorithm for NTFS illegal characters.
Private SMB Datasets and Shares
Used to set up an alternative to the legacy home shares function, select Private Dataset Share on the Purpose dropdown list, and customize settings listed under Other Options.
This allows you to add private datasets and shares for individual users, and is an alternate way to create home shares for them.
See Setting Up SMB Home Shares for more information.
SMB Audit Logging
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Use Watch List or Ignore List to limit auditing to specific groups and reduce audit volume.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Tuning ACLs for SMB Shares
There are two levels to set SMB share permissions: at the share or for the dataset associated with the share.
See Managing SMB Shares for more information on these options.
See Permissions for more information on dataset permissions.
Tuning the Share ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses.
The permissions apply at the SMB share level for the selected share.
They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on shareEdit Share ACL to open the Edit Share ACL screen to modify permissions at the share level.
Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
Tuning the Dataset (Filesystem) Permissions
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option.
This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level.
To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, click on the more_vert dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share.
You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group.
Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default.
Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry.
Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group.
Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
Changing the built-in-user Group Permissions
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen.
Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
Adding a New Share Group
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Groups, click Add and create the new group.
Go to Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group.
Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL.
Add an ACE entry for the new group, and select Traverse.
Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
Using the Traverse Permission
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
Starting the SMB Service
To connect to an SMB share, start the SMB service.
After adding a new share, TrueNAS prompts you to start or restart the SMB service.
You can also start the service from the Windows (SMB) Share widget or on the System > Services screen from the SMB service row.
Starting the Service Using the Windows SMB Share
From the Sharing screen, click on the Windows (SMB) Sharesmore_vert to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
Each SMB share on the list also has a toggle to enable or disable the service for that share.
Starting the Service Using System Settings
To make SMB share available on the network, go to System > Services and click the SMBStart Service button to start the service.
Toggle Start Automatically on if you want the service to activate when TrueNAS boots.
Configuring the SMB Service
Configure the SMB service by clicking Config Service from the more_vert dropdown menu on the Windows (SMB) Shares widget header or by clicking edit on the Services screen.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.
Mounting the SMB Share
The instructions in this section cover mounting the SMB share on a system with the following operating systems.
Mounting on a Linux System
Verify that your Linux distribution has the required CIFS packages installed.
Create a mount point with the sudo mkdir /mnt/smb_share command.
Mount the volume with the sudo mount -t cifs //computer_name/share_name /mnt/smb_share command.
If your share requires user credentials, add the switch -o username= with the username after cifs and before the share address.
Mounting on a Windows System
To permanently mount the SMB share in Windows, map a drive letter in the computer for the user to the TrueNAS IP and share name.
Select a drive letter from the bottom of the alphabet rather than from the top to avoid assigning a drive dedicated to some other device.
The example below uses Z.
Open the command line and run the following command with the appropriate drive letter, TrueNAS system name or IP address, and the share name.
net use Z: \\TrueNAS_name\share_name /PERSISTENT:YES
Where:
Z is the drive letter to map to TrueNAS and the share
TrueNAS_name is either the host name or the system IP address
share_name is the name given to the SMB share
To temporarily connect to a share, open a Windows File Explorer window, type \\TrueNAS_name\share_name and then enter the user credentials to authenticate with to connect to the share.
Windows remembers the user credentials, so each time you connect, it uses the same authentication credentials unless you restart the system.
After restarting, you are prompted to enter the authentication credentials again.
Mounting on an Apple System
Before you begin this process, have the username and password for the user assigned to the pool or the credentials for the guest if the share has guest access ready.
Open Finder > Go > Connect To Server
Enter the SMB address as follows: smb://192.168.1.111.
Input the username and password for the user assigned to that pool or a guest user if the share has guest access.
Mounting on a FreeBSD system involves creating the mount point and mounting the volume.
Create a mount point using the sudo mkdir /mnt/smb_share command.
Mount the volume using the sudo mount_smbfs -I computer_name\share_name /mnt/smb_share command.
Setting up an External SMB Share
External SMB shares are essentially redirects to shares on other systems.
Administrators might want to use this when managing multiple TrueNAS systems with SMB shares, and if they do not want to keep track of which shares are on which boxes for clients.
This feature allows admins to see and connect to any TrueNAS system with external shares active.
Create the SMB share on another TrueNAS remote server (for example, system1), as described in Adding an SMB Share above.
We recommend using Active Directory when creating user accounts, but at a minimum, synchronize user accounts between the system with the share (system1) and on the TrueNAS system where you set up the external share (for example, system2).
On system2 (the local system), select External Share, enter the full domain name or IP address, and the share name.
Separate the server and share name with the \ character. Example: 192.168.0.200\SHARE in Remote Path.
Click Save to add the share.
Repeat the system2 instructions above on system1 to see the SMB shares on each system.
Repeat for each TrueNAS system with SMB shares to add as an external share.
Setting Up an External Share with an Earlier Release
When setting up an external share between TrueNAS systems that are on different releases, for example, one system is on 25.04 and the other is on the latest release of 25.10, follow the external share instructions for each release.
Set the TrueNAS 25.04 system SMB Purpose to the default preset, leave the default settings associated with this share as is, and then enter the redirect path to share on the 25.10 system as EXTERNAL:ipaddress\sharename in the Path field. For example, EXTERNAL:10.220.3.33\testshare2.
Be aware, changing the path also changes the SMB share name. Verify the share name is set to the desired or existing share name and not renamed to the redirect string in Path.
Set the TrueNAS 25.10 system SMB Purpose to External Share, and then enter the path to the share on the 25.04 system as ipaddress*sharename* in the Remote Path field. For example, 10.220.1.34*testshare*.
Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
To access SMB share management options, go to Shares screen with the Windows (SMB) Shares widget.
To access SMB share management options, go to Shares and locate the Windows (SMB) Shares widget.
The widget lists configured SMB shares, but it is not the complete list.
To see a complete list of shares, click on Windows (SMB) Shares launch header to open the Shares > SMB screen.
The more_vert dropdown list to the right of each share shows four options that open other screens or dialogs that provide access to share settings.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Managing SMB Shares
To manage an SMB share, click more_vert dropdown list to the right of each share to see the options for the share you want to manage. Options are:
Edit opens the Edit SMB screen where you can change settings for the share.
Edit Filesystem ACL opens the Edit ACL screen, where you can edit the dataset permissions for the share.
The Dataset Preset option determines the ACL type and the type of ACL Editor screen that opens (POSIX or NSFv4).
Delete opens a delete confirmation dialog. Use this to delete the share and remove it from the system. Delete does not affect shared data.
Configuring SMB Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Use Watch List or Ignore List to limit auditing to specific groups and reduce audit volume.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Modifying ACL Permissions for SMB Shares
When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
When this happens, click Continue to close the dialog so you can continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions card, and then click Edit to open the Edit ACL screen.
Click Strip ACL on the Edit ACL screen. Save the change, then return to the Shares screen and open the Add SMB screen.
If you did not stop to strip the ACL, TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
You have two options that modify ACL permissions for SMB shares:
Edit Share ACL modifies ACL permissions that apply to the SMB share.
Edit Filesystem ACL modifies ACL permissions at the share dataset level.
See the ACL Primer for general information on Access Control Lists (ACLs) in general, the Permissions article for more details on configuring ACLs, and Edit ACL Screen for more information on the dataset ACL editor screens and setting options.
Configuring the SMB Share ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses.
The permissions apply at the SMB share level for the selected share.
They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on shareEdit Share ACL to open the Edit Share ACL screen to modify permissions at the share level.
Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
Configuring Dataset File System ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option.
This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level.
To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, click on the more_vert dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share.
You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group.
Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default.
Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry.
Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group.
Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
Changing the built-in-user Group Permissions
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen.
Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
Adding a New Share Group
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Groups, click Add and create the new group.
Go to Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group.
Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL.
Add an ACE entry for the new group, and select Traverse.
Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
Using the Traverse Permission
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
Adding a Basic Time Machine SMB Share
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS 25.04.0: Time Machine shares are incompatible with multiprotocol (SMB/NFS) shares. TrueNAS automatically disables SMB2/3 lease support and AAPL extensions globally when multiprotocol shares are configured, preventing Time Machine functionality.
TrueNAS 25.04.1 and later: This limitation is removed. Multiprotocol shares now use per-share oplock management instead of global oplock disabling, allowing Time Machine and Final Cut Pro Storage Share shares to coexist with multiprotocol shares on the same system. SMB leases are permitted globally, with oplocks disabled only at the multiprotocol share level.
TrueNAS uses predefined setting options to establish an SMB share that fits a predefined purpose, such as a basic Time Machine share.
Setting Up a Basic Time Machine SMB Share
To set up a basic time machine share:
Create the user(s) for this SMB share.
Go to Credentials > Users and click Add.
After creating the share, start or restart the SMB service.
When accessing from a Windows client, having more than 512 snapshots on the TrueNAS box can lead to performance issues, as the Windows client often attempts to load all snapshots into the Windows Previous Versions tab.
To avoid this, users should maintain fewer than 512 snapshots or consider accessing from a non-Windows client.
Alternatively, configure snapshot lifetimes or create an automatic deletion policy via the Periodic Snapshot Tasks screen. This screen helps users manage the snapshot count more effectively.
The latest maintained Mac OS versions allow setting the maximum Time Machine backup size from the Mac OS UI.
Setting this from the client side is generally recommended for better share flexibility and macOS coordination.
Note that enabling a multi-user Time Machine does not automatically replicate the backup data to another pool or offsite system. To protect against data loss, configure a Replication Task that includes the dataset used by the Time Machine share.
Creating the Share and Dataset
You can either create the dataset to use for the share on the Add Dataset screen and the share, or create the dataset when you add the share on the Add SMB screen.
We recommend using the Add SMB screen when setting up a Time Machine share, as it can create the dataset, enable the SMB2/3 protocol setting in the SMB service, and create the Time Machine share from the same screen.
When you want to customize the dataset, use the Add Dataset screen to create the customized dataset and a basic SMB share.
After saving, go to Shares, select the SMB share, and click Edit to change the purpose to Time Machine Share.
The Edit SMB screen shows the Enable Now button to configure the SMB service with the required SMB2/3 protocol option if it is not already enabled.
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
When this happens, click Continue to close the dialog so you can continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions card, and then click Edit to open the Edit ACL screen.
Click Strip ACL on the Edit ACL screen. Save the change, then return to the Shares screen and open the Add SMB screen.
If you did not stop to strip the ACL, TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
To use the Add SMB screen, click Add on the Windows (SMB) Shares widget to open the screen.
Set the Path to the existing dataset created for the share, or to where you want to add the dataset, then click Create Dataset.
Enter a name for the dataset and click Create Dataset.
The dataset name populates the share Name field and updates the Path automatically.
The dataset name becomes the share name.
Leave this as the default.
If you change the name, follow the naming conventions for:
Enabled is selected by default to allow sharing of this path when the SMB service is activated.
Clearing this option disables the share but does not delete the configuration.
Click Advanced Options to finish customizing the share, then click Save.
Start or restart the SMB service when prompted.
Modifying the SMB Service
You can configure the SMB service before you add the share, or you can enable this setting from the Add SMB or Edit SMB screens while adding the share or modifying an existing share. The system prompts you to restart the service after modifying the SMB service or adding/changing a share configuration.
Click on the on the Windows (SMB) Share widget, then click Config Service to open the SMB Service screen.
Go to System > Services and scroll down to SMB.
When using the Services screen, click the Stop Service button to turn off the SMB service if it is running, then click editEdit to open the SMB service settings screen.
Click Advanced Settings.
Select Enable Apple SMB2/3 Protocol Extension to enable it, then click Save.
Start or restart the SMB service.
Setting Up Final Cut Pro SMB Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
The Final Cut Pro Storage Share purpose enables Use Apple-style Character Encoding, which translates NTFS illegal characters to the Unicode private range. This ensures compatibility with Final Cut Pro.
Enabling this feature on shares with existing data might cause unexpected behavior for files that were written without Apple character encoding enabled. Test thoroughly before applying to production shares with existing content.
This share purpose requires Apple SMB2/3 Protocol Extensions to be enabled globally in the SMB service configuration.
About Final Cut Pro Storage Shares
The Final Cut Pro Storage Share purpose is available in TrueNAS 25.10.1 and later.
TrueNAS provides the Final Cut Pro Storage Share purpose for professional media production workflows.
This share type automatically enables Use Apple-style Character Encoding to translate NTFS illegal characters for proper file handling in Final Cut Pro.
Apple-style character encoding ensures that special characters and metadata are preserved correctly, which is essential when working with media files that have complex naming conventions.
Many online guides recommend manually configuring SMB VFS options for macOS compatibility:
vfs objects = catia fruit streams_xattr
TrueNAS does not support manual VFS module configuration. Manually setting VFS objects via auxiliary parameters or CLI overrides TrueNAS defaults and breaks Asynchronous I/O (AIO), Access Control Lists (ACLs), and Shadow Copies.
Why does TrueNAS handle VFS modules differently?
The TrueNAS SMB implementation integrates VFS modules with several advanced features. Manual VFS configuration breaks functionality including:
Asynchronous I/O (AIO): Overrides modules needed for SMB performance optimization, causing poor performance or stability issues.
Access Control Lists (ACLs): Bypasses or breaks ACL functionality, causing incorrect permission handling.
The Final Cut Pro Storage Share purpose preset automatically configures VFS modules to integrate properly with TrueNAS AIO, ACLs, and Shadow Copies. By using this preset instead of manual configuration, you get a share that works seamlessly with Final Cut Pro without risking system functionality.
Prerequisites
Before setting up a Final Cut Pro Storage Share:
Create user accounts for media users who access the share.
Go to Credentials > Local Users and click Add.
Ensure SMB Access is selected for each user.
Prepare a dataset for the share (or you can create one during share creation).
For best performance with large media files, consider:
Enabling compression (LZ4 is recommended for media files).
Setting appropriate record size (128K or larger for video files).
Configuring adequate space quotas.
Turn on Enable Apple SMB2/3 Protocol Extensions for the SMB service (instructions below).
Setting Up a Final Cut Pro Storage Share
To set up a Final Cut Pro storage share, complete the following steps in order:
If the SMB service is already running, restart it for the changes to take effect.
Create the Share and Dataset
You can either create the dataset first using the Datasets screen and then add the share, or create both together.
This tutorial uses the Add SMB screen to create both the dataset and share at the same time.
Go to Shares and click Add on the Windows (SMB) Shares widget.
In the Path field, browse to the parent dataset where you want to create the share dataset.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Enable Now to enable the required setting in the SMB service configuration. Wait for the service to update.
When complete, TrueNAS displays a success message confirming Apple SMB2/3 protocol extension support is enabled.
Configure Advanced Options
While creating a basic Final Cut Pro Storage Share requires no additional configuration, you can customize access and logging settings.
Click Advanced Options to expand additional settings.
Configure Access settings as needed:
Export Read-Only: Leave unselected to allow media file editing.
Browsable to Network Clients: Enabled by default (recommended).
Access Based Share Enumeration: Select to enable if needed for your access control requirements.
Configure Watch List and Ignore List as needed for monitoring specific users or groups.
Note that Use Apple-style Character Encoding is automatically enabled under Other Options and cannot be disabled.
TrueNAS enforces this setting because Final Cut Pro requires Apple character encoding to operate properly.
Click Save to create the share.
Configure Dataset Permissions
After creating the share, configure dataset permissions to grant access to media users.
On the Shares screen, locate the new share in the Windows (SMB) Shares widget.
Click and select Edit Filesystem ACL.
Configure ACL entries for users or groups who need access:
For individual users: Add ACL entries with appropriate permissions (FULL for editors, READ for reviewers).
For groups: Create a group like media_users and add users, then add a group ACL entry.
Click Save Access Control List.
See Managing SMB Shares for detailed information on configuring ACL permissions.
Start the SMB Service and Mount the Share
If the SMB service is not running, start it from the Windows (SMB) Shares widget:
Click on the widget header.
Select Turn On Service.
Connect from Mac Client
On the Mac client, connect to the share:
Open Finder.
Select Go > Connect to Server (or press Cmd+K).
Enter the SMB address:
smb://your-truenas-ip/share-name.
Authenticate with a user account that has access to the share.
The share is now available for use with Final Cut Pro.
Testing and Verification
After mounting the share, verify proper operation:
File Creation: Create test files from Final Cut Pro to verify proper file handling.
Character Handling: Test filenames with special characters to confirm Apple character encoding is working correctly.
Performance: Copy large media files to verify adequate transfer speeds for your workflow.
Permissions: Test access with different user accounts to verify ACL configuration.
Migrating Existing Media Libraries
If you have an existing Final Cut Pro workflow using a standard SMB share with default settings that works properly, TrueNAS recommends keeping your current configuration. Migration is only necessary if you are experiencing specific compatibility issues or need the character encoding features provided by the Final Cut Pro Storage Share preset.
Migrating an existing media library from a standard SMB share to a Final Cut Pro Storage Share requires careful planning because enabling Apple character encoding might affect existing files:
Files created without Apple character encoding might display differently or have access issues
Existing project files might need to be re-indexed by Final Cut Pro
Test thoroughly in a non-production environment before migrating production data
Migration Steps
Only proceed with migration if you have confirmed that your current setup is incompatible with your requirements:
Create a new Final Cut Pro Storage Share and dataset in TrueNAS following the instructions in this article.
Configure dataset permissions for the new share to grant appropriate access to media users.
Copy a small subset of test files to the new share using the Mac client:
Open Finder and connect to both the old and new shares
Copy a few representative project files and media assets from the old share to the new share
Test these files in Final Cut Pro to verify proper access and functionality
If testing is successful, migrate remaining data via the Mac client:
Use Finder to copy files from the old share to the new share
Monitor the transfer for errors or warnings
Verify file integrity after the transfer completes
Update Final Cut Pro libraries and project files to point to the new share location.
Keep the old share available for a period of time as a backup until you confirm all workflows function correctly with the new share.
Using SMB Shadow Copy
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS automatically enables shadow copies for SMB shares, exporting ZFS snapshots as Shadow Copies for Microsoft clients.
About SMB Shadow Copies
Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots.
You can use shadow copies to restore previous versions of files from within Windows Explorer.
By default, all ZFS snapshots for a dataset underlying an SMB share path are presented to SMB clients through the volume shadow copy service or are accessible directly with SMB when the hidden ZFS snapshot directory is within the SMB share path.
TrueNAS 25.10 and later does not support per-share disabling of SMB shadow copies on non-legacy shares.
If you need to completely disable shadow copies and prevent client access to ZFS snapshots, disable the ZFS snapshot directory for the shared dataset.
Go to Storage > Datasets, select the shared dataset, and click Edit on the Details widget.
In the Edit Dataset screen, select Advanced Options and set Snapshot Directory to Disabled.
When the snapshot directory is disabled, Samba automatically turns off the shadow copy feature.
Deleting Shadow Copies
Users with an SMB client cannot delete shadow copies.
Instead, the administrator uses the TrueNAS web interface to remove snapshots.
Managing Shadow Copies (Legacy Shares)
Enabling or disabling shadow copies is an available option in pre-25.10 TrueNAS releases or for legacy shares in 25.10 or later.
TrueNAS sets a share Purpose to Legacy Share after upgrading to 25.10 when shares created in a release before 25.10 have Purpose set to No Preset.
See Legacy Share Settings for more information.
To enable shadow copies for a compatible dataset go to Shares > Windows (SMB) Shares and locate the share.
Click on the Edit option for the share.
If not listed, click Windows (SMB) Shares launch to open the Sharing > SMB screen.
Select the share, then click the more_vert for the share, then click Edit to open the Edit SMB screen.
Click Advanced Options, scroll down to Other Options, and then select Enable Shadow Copies.
Click Save.
Windows 10 v2004 Issue
Some users might experience issues in the Windows 10 v2004 release where they cannot access network shares.
The problem appears to come from a bug in gpedit.msc, the Local Group Policy Editor.
Unfortunately, setting the Allow insecure guest logon flag value to Enabled in Computer Configuration > Administrative Templates > Network > Lanman Workstation in Windows does not affect the configuration.
To work around this issue, edit the Windows registry.
Use Regedit and go to HKLM\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters.
The DWORD AllowInsecureGuestAuth is an incorrect value: 0x00000000. Change this value to 0x00000001 (Hexadecimal 1) to allow adjusting the settings in gpedit.msc.
You can use a Group Policy Update to apply the edit to a fleet of Windows machines.
Disable shadow copies for an SMB share by clearing the Enable shadow copies checkbox on the Edit SMB screen in the Other Options on the Advanced Options screen for the SMB share.
Disabling does not prevent access to the hidden .zfs/snapshot directory for a ZFS dataset when it is within the path for an SMB share.
Setting Up SMB Private Dataset Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
SMB Home Share is a legacy feature for organizations looking to maintain existing SMB configurations.
Microsoft deprecated the Home Shares feature in Windows 10 and removed it completely from Windows 11.
They no longer support Home Shares as of October 2025.
TrueNAS removed the home share option from the SMB share Purpose list in 24.04 (Dragonfish).
The SMB share Other Options in pre-25.10 releases includes a home share legacy option, but it is not recommended for new shares.
It is for organizations still using the legacy home shares option to add a single SMB share to provide a personal directory for every user account.
Future TrueNAS releases can introduce instability or require configuration changes affecting this legacy feature.
This option does not show in 25.10 and later releases unless an existing home share is upgraded to 25.10 or later.
The share user is the individual user account for the private dataset share.
You can manually create this user as described below or by using a directory server (FreeIPA or Active Directory).
Users who require access to an SMB share must be created with the SMB Access granted.
TrueNAS assigns this level of access to new users by default, but administrators can disable/enable this manually on the Add User or Edit User screen.
Go to Credentials > Users to verify that the user for a private dataset exists and is correctly configured. If the user does not exist, create the user.
If the user exists but does not have SMB Access enabled, edit the user to enable this level of access.
How do I create a user?
User Access Levels
Users are assigned different access levels by TrueNAS administrators. All user accounts are assigned access levels based on their roles or system privileges.
All users are assigned the SMB Access by default.
SMB Access is the default user access type that allows using the account credentials to access data shared with SMB.
TrueNAS requires other options based on the level of access
TrueNAS Access shows the predefined roles available in TrueNAS. Assigning TrueNAS Access requires setting one of the options or roles: Full Admin, Readonly Admin, or Sharing Admin.
Some administration users require access to the TrueNAS shell or might require access using an SSH session.
These users must be assigned the Shell option and or the SSH Access options.
If a user only requires access to the TrueNAS Shell screen, assign the user Shell Access.
If the user requires SSH session access, assign the SSH Access to the user. This provides access to the Shell screen and an SSH session.
SSH Access requires adding an SSH keypair to TrueNAS, and then copying the public key into the Add User or Edit User screen.
Turn on the SSH service before establishing an SSH session, and then turn it off when access is no longer required to maintain a security-hardened system.
When creating a user, you must:
Enter a value in Full Name or description for the user, such as a first and last name.
Enter a value in Username.
Enter a value in Password and confirm that password.
Specify or accept the default user ID (UID)
To manually add a new user, click Credentials > Users, and then click Add to open the Add User screen.
Enter a username for the user. Names are case sensitive!
Set the level of access given to this user.
SMB Access is selected by default, and required for a user to have access to an SMB share.
Select TrueNAS Access and then the administration role from the dropdown list that shows after selecting the TrueNAS Access option.
To create an administrator with full access, select Full Admin.
To create an administrator with access to manage shares, select Sharing Admin.
To create an administrator with read-only access, select Readonly Admin.
To allow the user to access the Shell in the UI, select Shell Access.
To allow the user to establish an SSH session with the system, select SSH Access.
Selecting this option also selects the Shell Access option by default.
To limit the user to only Shell access, do not select the SSH Access option.
Enter a password for the user, and confirm it.
Setting Up SSH Access.
These options only show when you select the SSH Access option. Only Full Admin users who require SSH session access should be configured with this option.
Select the optional Allow SSH Login with Password if you want to allow this user to log in to an SSH session and not be prompted to enter a password.
This is not recommended as it presents a security vulnerability!
Manually enter or copy/paste the public key in the Public SSH Key field to assign a public SSH key to the user for key-based authentication.
Do not enter the private key!
After adding authentication settings, complete the SSH access by setting up sudo commands in the next step.
Always keep a backup of an SSH public key if you are using one.
Enter additional details for the user. Setting options change based on the access option selected in Allow Access.
If this is an SMB share user, leave the default SMB Access selected.
When Shell Access and SSH Access are assigned to the user, the Shell and Sudo Command settings show in the Additional Details section.
Enter the full name for the user. The full user name is not case sensitive.
(Optional) Enter the email for the user.
Starting in TrueNAS 25.10, system notifications are sent to recipients configured in system email settings rather than user account emails.
Set up a group.
Accept the default group setting, which is Create New Primary Group. This creates a group with the same name as the admin user.
The role setting adds the user to the appropriate auxiliary group for that role.
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list.
Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID.
TrueNAS suggests a user ID starting at 3000, but you can change it if you wish.
We recommend using an ID of 3000 or greater for non-built-in users.
(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty.
This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.
If set to this path, TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory.
The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset.
After clicking on a dataset, the Create Dataset option activates.
Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist.
pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure.
This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did.
This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished.
Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password.
To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password.
To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.
Using AD to Add Users with Private Shares
Using AD to Add Users and Private Dataset Shares
You can manually add users and groups in TrueNAS, or configure groups in Active Directory and add users to each group, and then have AD add the users and group to TrueNAS.
After AD adds users and groups, configure private directories, and if needed for other file system functions not related to private directory shares, configure home directories for the users and group(s).
See Managing Users for more information on adding home directories.
Before setting up SMB shares, check system alerts to verify that no errors related to connections to Active Directory are listed.
Resolve any issues with Active Directory before proceeding. If Active Directory cannot bind with TrueNAS, you cannot start the SMB service after making changes.
Adding Share Users with Directory Services
You can use Active Directory to create the share users.
Creating the Private Dataset Share
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled.
You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
You can edit and use an existing dataset and share to use for a private dataset share, or you can create a new dataset and share. We recommend creating a new dataset and share.
When creating a new share, TrueNAS allows you to use the Add Dataset or Add SMB screen to create the share and dataset.
Each method has advantages depending on the type of share you want to create.
In general, when creating a simple SMB share and dataset, you can use either screen.
When adding a new share and dataset for a private dataset share, we recommend using the Add SMB screen to create a new share and dataset for private datasets, or for any other customized SMB share, rather than using the Add Dataset screen.
We recommend using the Add Dataset screen when you want to customize the dataset with the advanced setting options. After which, use the Add SMB or Edit SMB screen to create or customize an SMB share with presets and advanced options.
When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
When this happens, click Continue to close the dialog so you can continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions card, and then click Edit to open the Edit ACL screen.
Click Strip ACL on the Edit ACL screen. Save the change, then return to the Shares screen and open the Add SMB screen.
If you did not stop to strip the ACL, TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
Checking Parent Dataset File Permissions
To avoid possible permission issues or error messages when creating the private dataset share, check the file system permissions assigned to the parent dataset for the private share dataset.
If the admin user who creates the private dataset share and dataset is not listed as the owner or as an ACL entry, the permission issues blocks creating the share dataset.
The owner and owner group default user is root, which means only the root user can create the private share dataset.
When set to root, if another logged-in admin user tries to create a new private dataset share nested under the parent, TrueNAS shows an error message and prevents adding the new private dataset share until you correct the permissions issue.
You can change the admin user who is creating the private dataset share dataset to the ACL as the Owner and Owner Group user. Click apply for both the owner and owner group changes.
Alternatively, leave the Owner and Owner Group set to the root user and add a new user entry for the admin user who creates the private dataset shares.
Give that admin user full access permissions.
For more information on changing permissions, see Storage Permissions.
Adding the Private Dataset Share and Dataset
To create an SMB private dataset share, go to Shares, and click Add on the Windows (SMB) Shares card to open the Add SMB screen.
Select Private Dataset Share on the Purpose dropdown list, then click Advanced Options to configure additional share setting options.
Enter or browse to select the path to the parent dataset for the private share dataset.
Click on the dataset where you want to add the private share dataset, then to create a new dataset, click Create Dataset. The Create Dataset dialog opens.
Enter the private dataset name, for example rikka-private, then click Create Dataset.
The dialog closes, and Path populates with the full path to the new dataset.
Modifying an Existing Share
If you created a simple share and dataset using the Add Dataset screen, to customize it, go to Shares, select it on the SMB screen (or card if it shows on the list), then click Edit. Verify the path and Name field are populated, and change the Purpose from Default Share to Private Dataset.
The dataset name populates the share Name field and becomes the share name. The Path field is updated with the dataset name.
The share and dataset must have the same name.
(Optional) Click Advanced, scroll down to select Enable Logging to enable SMB share audit logging.
(Optional) Scroll down to Other Options on the Advanced Options screen to locate the legacy Export Recycle Bin option, which only shows if you select a share created in an earlier TrueNAS release.
This option allows moving files deleted in the share to a recycle bin in that dataset.
Files are renamed to a per-user subdirectory within .recycle directory at the root of the SMB share if the path is the same dataset as the share.
If the dataset has a nested dataset, the directory is at the root of the current dataset. If this is the case, there is no automatic deletion based on file size.
(Optional) Select any other advanced options that apply to your share needs.
Click Save.
Enable or restart the SMB service when prompted and make the share available on your network.
When prompted by the system to configure the dataset ACL, accept the option. The Edit ACL screen for the new private share dataset opens.
Setting ACL Permissions
There are two types of ACL permissions for shares: file system and share permissions.
The private dataset share requires both the dataset and share ACL permissions to allow or prevent access to the share.
If you did not modify the dataset ACL permissions as described above, when prompted by the system to configure the dataset ACL, accept the option.
The Edit ACL screen for the new private share dataset opens. This controls who can access or modify file system permissions for the dataset the share uses.
The Edit Share ACL option for the share opens the Share ACL for rikka-private screen where you can mofify who can see or access the share when connecting to it though Windows File Explorer.
Setting Dataset Permissions
First, set the dataset permissions to allow your admin user and the user assigned to the private directory to access the share.
Your admin user must have permissions granted for the parent dataset covered in Before You Begin and the private dataset covered in this section.
If you want or need to grant another user access to the private share dataset, other than the private share user or a group of users, add an ACL entry to the dataset on the Edit ACL screen, and then grant share ACL to allow access to the private dataset.
Accessing the Edit ACL screen with the dataset permissions:
From the Datasets screen, select the dataset row for the private share dataset.
Click Edit on the Permissions card to open the Edit ACL screen.
See Setting Up Permissions for more information on editing dataset permissions.
From the Shares screen, click the triple dot icon for the share row, then click Edit Filesystem ACL to open the Edit ACL screen.
Set the permission for the private dataset to allow additional users or a group if others are permitted to access the private directory share.
Click the Owner dropdown, select the administration user with full control, and then repeat for Group.
You can set the owning group to your Active Directory domain admins. Click Apply Owner and Apply Group to apply the changes.
Click Use Preset and choose NFS4_HOME. If the dataset has a POSIX ACL, choose HOME.
Click Continue.
Next, click Add Entry to add user entries for each user that needs access to the dataset.
To assign required permissions, select User in Who and locate the user name in the User dropdown list.
Select the required permissions.
Repeat for each user that needs access.
Alternatively, if you added users to a group, select, set Who to Group and locate the group in the dropdown list.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
After adding all users or groups and setting the required permissions for each, click Save Access Control List.
Setting Share Permissions
If the private dataset is nested under a parent dataset that has other private datasets nested under it, you must set the share ACL permission to restrict access to the files in the private share dataset (directory) to prevent other users from accessing the private share.
Windows File Explorer shows all datasets nested under the share parent, but blocks other users not granted access permission from opening and viewing the contents of that folder or directory.
Click the triple dot icon at the right of the private dataset share on the Shares screen, then click Edit Share ACL to open the Share ACL for rikka-private screen.
Change Who from the default everyone@ to the private dataset share user. In the example, the user is rikka for the rikka-private share.
Leave Permissions set to Full and Type set to Allowed.
Click Add to show another Add entry group of settings. Change Who to the admin user to allow for share maintenance tasks, like moving the directory to a new location if that becomes necessary.
If granting other users in a group to a private share for that group, add an entry for each user and change the level of permissions to what is needed.
For example, if the group members can read the files but not change them, set Permission to READ for those users, and grant the user who maintains the documents either FULL or CHANGE permissions.
Click Save when finished.
Replacing SMB Home Shares
This section applies to users upgrading from earlier releases of TrueNAS where they configured SMB shares for use as home shares.
TrueNAS has removed the Use as Home Share option, found in the Other Options section of the Advanced Options screen for the Add SMB and Edit SMB screens in earlier releases of TrueNAS.
The Private Dataset Share found as a Purpose dropdown list option in 25.10 and later releases replaces home shares, and is the recommended method to provide users with a private personal folder they access through an SMB share.
The Private Dataset Share option allows creating a private personal directory for a user in the specified dataset, that when correctly configured, provides users with a private folder only they access through an SMB share.
A Private Dataset Share is not the same as guest access:
Private Dataset Share creates per-user isolated datasets - users must authenticate with credentials
Guest Access (Legacy Share only) allows anonymous access without credentials
If you are looking for guest access functionality, see the Guest Access section in the main SMB tutorial.
TrueNAS allows creating one private directory per user, while it still allows creating as many non-private directories as desired or needed.
When a user first authenticates to a Private Dataset Share, TrueNAS automatically creates a subdirectory named after their username (for example, /mnt/poolname/share-name/username/).
Each user only sees and can access their own subdirectory when connecting to the share.
Users can create as many directories as needed through Windows File Explorer.
TrueNAS does not control what Windows allows through the File Explorer.
Share ACL settings control who can access the private directory share.
If the personal directories show in File Explorer, use Windows file properties and access control to hide the folder in the share.
A user home directory in TrueNAS is a function of the ZFS file system and is not related to the SMB private dataset share or (deprecated Home Share).
A user configuration does not need to specify or add a file system home directory for a private dataset share.
Other options for configuring individual user directories include:
Configure a single share on the TrueNAS and provision individual user directories on the client OS.
Create a single SMB share and configure the ACL so that users can create individual directories on the share that inherit write access for the user and grant read access to the administrator.
Create an SMB share using the Private SMB datasets and shares preset, and then create per-user datasets under the umbrella of a single share when users access the share.
Creating an SMB private dataset share requires provisioning users or joining Active Directory, and configuring the system storage and share.
Adding Private Dataset Shares
Private directories are not intended for every user on the system.
When setting the Purpose dropdown list to the Private Dataset Share option, TrueNAS might show the private directories to all users with access to the root level of the share, but setting the share ACL prevents other users from accessing the private share.
Examples of setting up private SMB shares are those for backups, system configuration, and users or departments that need to keep information private from other users.
This article covers:
Adding the private dataset share user.
Creating the private dataset share and the dataset.
Modifying ACL permissions for the dataset (who has access to the file system) and the share (who has access to the share).
SMB Share MacOS Client Limitations When Using Decomposed Unicode Characters
There are normalize forms for a unicode character with diacritical marks: decomposed (NFD) and pre-composed (NFC).
Take for example the character ä (a + umlaut) and the encoding differences between NFC (b’\xc3\xa4’) and NFD (b’a\xcc\x88’).
The MacOS SMB client historically and at present forces normalization of unicode strings to NFC prior to generating network traffic to the remote SMB server.
The practical impact of this is that a file that contains NFD diacritics on a remote SMB server (TrueNAS, Windows, etc.) might be visible in the directory listing in the MacOS SMB client and thereby Finder, but any operations on the file (edits, deletions, etc.) have undefined behaviors since a file with NFC diacritics does not exist on the remote server.
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
>>> os.unlink('220118_M_HAN_MGK_X_4_Entwässerung.pdf')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
FileNotFoundError: [Errno 2] No such file or directory: '220118_M_HAN_MGK_X_4_Entwässerung.pdf'
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
Above is a short example of a MacOS SMB client attempting to delete a file with NFD normalization on remote Windows server.
Short of Apple providing a fix for this, the only strategy for an administrator to address these issues is to rename the files with pre-composed (NFC) form. Unfortunately, normalization is not guaranteed to be lossless.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance.
SMB multichannel does not function if you combine NICs into a LAGG.
Configuring Multiple Network Interfaces
Do not configure multiple SMB multichannel interfaces on the same subnet. To ensure reliable multichannel performance, TrueNAS recommends placing each interface on a different subnet.
If interfaces share a subnet, the system could fail to initialize multichannel, experience several connectivity issues, and accept inbound traffic inconsistently. To avoid these issues, assign each NIC a unique IP address on a different subnet and avoid bridging interfaces used for multichannel.
Activating Multichannel in TrueNAS
If you already have clients connected to SMB shares, disconnect them before activating multichannel.
Go to System > Services and click the edit edit icon for the SMB service.
Click Advanced Settings, then enable Multichannel.
Save and restart the SMB service, then reconnect all clients to their SMB Shares.
Validating Multichannel Activated In Windows
After you connect a client to their SMB share, open Powershell as an administrator on a client, then enter Get-SmbMultichannelConnection. The terminal should list multiple server IPs.
# View active SMB multichannel connectionsGet‑SmbMultichannelConnection# Sample output:# Server Name Selected Client IP Server IP Client Interface Index Server# ------------- ----------- --------- --------- ------------------------- ------# 192.168.10.2 True 192.168.10.10 192.168.10.2 5 2# 192.168.20.2 True 192.168.20.10 192.168.20.2 16 5
You can also enter Get-SmbMultichannelConnection | ConvertTo-Json and ensure CurrentChannels is more than 1.
View details as JSON
# View details as JSONGet-SmbMultichannelConnection|ConvertTo-Json# Sample output:[{"CimClass":{"CimSuperClassName":null,"CimClass":null,"CimClassProperties":"...","CimClassQualifiers":"...","CimClassMethods":"...","CimSystemProperties":"Microsoft.Management.Infrastructure.CimSystemProperties"},"CimInstanceProperties":[{"ClientInterfaceFriendlyName":"Ethernet 3","ClientInterfaceIndex":5,"ClientIpAddress":"10.230.46.64","ClientLinkSpeed":10000000000,"ClientRdmaCapable":false,"ClientRSSCapable":false,"CurrentChannels":2}]}]
NVMe-oF Subsystems
Overview of NVMe-oF
NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for fused commands required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.
Configuring the NVMe-oF Service
You can access the NVMe-of service screen from the:
more_vert dropdown menu on the NVMe-oF Subsystems widget on the Shares screen
Global Configuration button at the top of the NVMe-oF screen
NVMe-oF service option on the System > Services screen
The NVMe-oF Global Configuration shows the base NQN for the service.
What is the Base NQN?
The Base NQN us the standardized NVMe Qualified Name for the service. It is the prefix used when a new subsystem is created.
The NQN standard structure follows the format defined in the base specification. The maximum length/size is 223 bytes.
TrueNAS subsystems use the Base NQN as the root identifier for the NVMe subsystems in fabric deployments.
Discovery controllers use the standardized NQN to advertise available subsystems.
Storage systems use the Base NQN to authenticate and authorize host connections.
The Base NQN format provides the foundation for all NVMe-oF naming, ensuring interoperability, and preventing naming conflicts across different vendors and implementations.
TrueNAS populates the Base NQN field with the NVMe identifier.
Accept this value or click in the field to copy/paste a new, properly formatted Base NQN identifier.
NQN is used as the prefix when creating a subsystem, if a subnqn is not supplied.
Modifying this value does not change the subnqn of any existing subsystems.
We recommend using caution if you change this Base NQN. A particular client might be configured to talk to a particular NQN, so changing this could break the client connection.
Select Generate Cross-port Referrals for Ports on This System if subsystems are published through multiple ports and connect-all functionality is desired by clients.
If ANA is active, referrals are always generated between the peer ports on each TrueNAS controller node.
Select the Enable Remote Direct Memory Access (RDMA) option. Click Save.
Enabling RDMA allows configuring one or more ports with RDMA selected as the transport when enabled.
This option requires an Enterprise license, and you must have an RDMA-capable system and network equipment.
This option is inactive on systems without an Enterprise licenses.
If the system is not equipped with required hardware, shows Not enabled, because this system does not support RDMA on the screen.
Adding Asymmetric Namespace Access (ANA)
Go to the NVMe-oF Global Configuration screen.
Select the Enable Asymmetric Namespace Access (ANA) option, and click Save.
This allows storage systems to inform hosts about the optimal controller path to access a namespace on Enterprise licensed systems.
It is similar to Asymmetric Logical Unit Access (ALUA) in iSCSI.
ANA helps storage arrays communicate to hosts which controller provides the best (lowest latency) path to specific namespaces, enabling intelligent multipathing and improved performance in NVMe-oF environments.
Adding a Subsystem
Subsystems correlate to iSCSI targets. Each subsystem has a namespace and port, hosts are optional for added security.
The Add Subsystem wizard steps through the subsystem creation process.
You can access the Add Subsystem wizard from the:
Add button on the NVMe-oF Subsystems widget on the Shares screen
Add Subsystem button at the top of the NVMe-oF screen
Enter a name for the subsystem. We recommend keeping the name short to avoid any possible issues with accessing the subsystem.
A name can consist of upper and lowercase alphabetical characters, numbers, and/or some special characters such as the dash (-), underscore (_), etc.
Leave the NQN set to Generate from global setting.
To change it, click on it or the edit edit icon, and then enter or copy/paste a correctly formatted NQN identification number in the field.
Add a namespace. Click Add to open the Add Namespace screen. The screen opens with the Zvol tab selected.
A subsystem can have only one namespace.
To add a new zvol, browse to and select the parent dataset where you want to add the zvol, then click Create Zvol to open the Add Zvol screen. See Creating a Zvol for more information on adding a new zvol.
To use an existing file, click on the Existing File tab, and then browse to select the path to the file.
Leave Allow any host to connect selected to allow any host to connect, or clear the checkbox to show the Add option for hosts.
Adding individual hosts limits access to the subsystem to only the host(s) added.
c. (Optional) Enter the DH-CHAP key obtained from the host system to use when connecting to TrueNAS.
Enter or copy/paste the key into the field.
To allow TrueNAS to create a key for the host, click in the field to activate Generate Key below the Key for Host to Present field. The field populates with a key. Copy/paste this into the host system connecting to TrueNAS.
d. (Optional) Add a bi-directional key for TrueNAS when it connects to the host system.
Click Generate Key below the Key for TrueNAS to Present to populate the field with a key. Copy/paste this into the host system to use when authenticating TrueNAS when it connects to it.
e. (Optional) Select Also use Diffie-Hellman key exchange for additional security.
f. Click Save, then click on the breadcrumb at the top of the screen to return to the Add Subsystem wizard.
Add a port. Click Add to the right of Ports to open the Add Ports screen.
Enter a port number that is at least four digits in length.
4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.
a. Select the transport type. TCP is the default setting.
If you have an Enterprise license and your system can support RDMA, this option shows as an available choice.
b. Enter an available port number of at least four digits in length.
c. Select the IP address from the dropdown list.
d. Click Save.
e. Click on the breadcrumb at the top of the screen to close the Add Port screen and return to the Add Subsystem wizard.
Click Save at the bottom of the Add Subsystem wizard screen to add the subsystem.
Creating a Zvol
The Add Zvol screen is accessed from the Add Subsystem wizard after clicking Add to the right of Namespaces.
You can also access it from the Namespace widget on the NVMe-oF screen.
Select the subsystem row on the NVMe-oF screen table, then click Add on the Namespaces widget to show the options.
Select Create New to open the Add Namespace screen.
Browse to and select the dataset where you want to add the zvol, then click on Create New to open the Add Zvol screen.
To add a new zvol:
Enter a name. We recommend keeping the name short.
You can use standard name alpha-numeric, upper or lower case letters, and approved special characters in the name.
Accept the default settings for the remaining settings, or click the edit edit icon to show a text entry or dropdown selection field.
Enter or select the desired new settings.
(Optional) Set encryption for the zvol.
If the parent dataset where you add the zvol is unencrypted, you can set encryption by clearing the Inherit (unencrypted) checkbox.
If the parent dataset is encrypted you can only change the type of encryption as key or passphrase type.
Clear the Inherit (encrypted) checkbox to see the encryption type options.
Click Save, then click the breadcrumb at the top of the screen to return to the previous screen.
Managing NVMe-oF Subsystems
NVME Structure
NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for fused commands required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.
Editing a Subsystem
After configuring a NVMe-oF subsystem, you can change the subsystem by adding or deleting a namespace, removing or adding a port, or adding, removing, or deleting a host.
To access the subsystem configuration screen from the Shares screen:
Click the more_vert dropdown menu on the row for the subsystem listed in the NVMe-oF Subsystems widget.
Select View to open the NVMe-oF screen for that subsystem and showing the Details widgets for it.
or
Click on the NVMe-oF Subsystems widget header to open the NVMe-oF screen, and then locate and select the row in the Subsystem table for the desired subsystem to show the Details widgets for that subsystem.
Renaming the Subsystem
To change a subsystem name, while on the NVMe-oF screen, select the subsystem row in the table, then click on the subsystem name or the edit icon in the Details widget.
The name changes to a text entry field. Enter a new name for the subsystem, then click outside the field to save the change.
The subsystem NQN is not modified by this operation. You must choose to modify the NQN by clicking on the NQN or edit icon for the NQN shown in the Details widget, then enter or copy/paste a new correctly-formatted NQN in the field.
Copying the NQN
To copy the NQN identification number for the subsystem, while on the NVMe-oF screen, select the subsystem row in the table, then click Copy in the Details widget.
TrueNAS copies the identification number to the clipboard.
Deleting a Subsystem
Before deleting a namespace subsystem, delete the port and any associated host. TrueNAS shows an error if the subsystem has an active port and host.
While on the NVMe-oF screen, select the subsystem row in the table, then click Delete to the right of Details for name.
The Delete Subsystem dialog opens.
Delete the port. This does not delete the port configuration from the system, it removes it from the namespace subsystem.
Delete any associated host. This does not delete the host configuration from the system, it removes it from the namespace subsystem.
Delete the subsystem.
Verify the name of the subsystem listed in the dialog to confirm you have the desired subsystem.
Click Delete to delete the subsystem and namespace(s) associated with it.
Cancel closes the dialog without deleting the subsystem.
Select Force if the delete operation shows an in use error, or to delete with a port or host still associated with the subsystem, then click Delete again.
Deleting a Zvol Namespace
To delete a zvol namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the zvol in the Namespace widget.
The Delete Namespace dialog opens. Deleting the namespace from the zvol does not delete the zvol it only removes it from the subsystem.
To delete a file namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the file in the Namespace widget.
The Delete Namespace dialog opens with the option to delete the underlying file.
Select the Also delete the underlying file option, then click Delete to delete both the namespace and the file.
Editing Ports
You can add new ports or edit existing ports from the Ports widget on the NVMe-oF screen.
First, select the subsystem row in the table, then click the Add dropdown on the right of the Ports widget header.
Click Create New to open the Add Port screen and add a new port.
To edit or delete a port, click Manage Ports to open the Ports dialog.
Adding a Port
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports widget.
Click Create New to open the Add Port screen.
The Add Port screen creates a new port IP address:port assignment on the system for use by a subsystem.
Select the transport type. TCP is the default setting.
If your system has an Enterprise license, and it supports RDMA, this option is listed as available.
Enter an available port number of at least four digits in length. For example, 4420 is the default and recommended port number.
Select the IP address from the dropdown list. Only static IP addresses in the TrueNAS system show on this list.
Click Save.
The next time you click Add on the Ports widget, the added port shows as an option on the dropdown list.
Editing a Port
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports widget.
Click Manage Ports to open the Ports window.
Select the edit edit icon for the port listed in the table to open the Edit Port screen.
The Edit Port screen shows current port settings for the selected subsystem.
Select the transport type from the dropdown list.
Leave TCP as the default option unless your system has an Enterprise license and it supports RDMA.
Enter a port number that is at least four digits in length. 4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.
Leave the IP address for the TrueNAS system, or select any static IP address shown on the list.
Click Save.
Removing a Port from the Subsystem
You can change the port number assigned to the subsystem using the Remove this port from the subsystem icon on the Ports widget.
After removing a port, the Add button lists any available port on the system, including the port removed from the subsystem, in the format IP address:port.
Deleting a Port
Deleting a port does not remove it from the system; it removes the port from the selected subsystem.
A deleted port shows on the Add dropdown list on the Ports widget for a selected subsystem on the NVMe-oF screen.
To delete the port, click on the delete delete icon at the right of the port row on the Ports window.
The Delete Port confirmation dialog opens. You are asked to confirm that you want to delete the port.
Delete Anyway removes the port assignment from the subsystem specified in the dialog.
Adding a Host
The Associated Hosts widget on the NVMe-oF screen shows a list of hosts associated with the subsystem selected on the table.
All hosts are allowed is selected by default, and allows all clients to connect to the subsystem if a host is not specified.
To add connection security, limit the hosts allowed to connect to the subsystem. Select All Hosts are allowed to clear the checkbox and show the option to add a host.
To add a host, click Add to open the Add Host screen.
Obtain the NQN number from the host system and enter or copy/paste it into the NQN field.
TrueNAS uses this to determine if the host(s) can access the subsystem namespace.
To require authentication and add secret keys to further secure communication between the TrueNAS subsystem and the host system, select Require Host Authentication.
This shows the additional setting options.
Accept the default in Hash or click the edit edit edit icon and select a hash option from the dropdown list.
Options are SHA-256, SHA384, and SHA-512.
Obtain the DH-CHAP key from the host you are allowing to connect to the subsystem, and enter or copy/paste it in the Key For Host To Present field.
Alternatively, TrueNAS can create a key for the host system if you click Generate Key directly under the field.
Copy this key from TrueNAS, and paste it into the host system as the key it presents to TrueNAS to authenticate the connection.
To use bidirectional authentication, click Generate Key directly below the Key For TrueNAS To Present (Optional).
It populates the field with a secret key.
Copy this key from TrueNAS, and paste it into the host system to validate the TrueNAS connection.
For additional authentication security, select Also use Diffie-Hellman key exchange for additional security.
Click Save, then close the screen.
Hosts added to the subsystem show in the Associated Hosts widget with options to edit, delete, or remove them from the host.
Removing a Host
Click the Removes this host from the subsystem icon to remove the host from the subsystem.
This does not delete it from TrueNAS; the removed host shows on the Add dropdown list if you want to add the host to the subsystem again.
Editing a Host
To edit a host, click Add, then select Manage Hosts. The Hosts window opens.
The Hosts window shows a table listing the host NQN, if it requires authentication, and the number of subsystems that use it.
Click the edit edit icon to the right of the host row to open the Edit Host screen.
The Edit Host screen shows the fields associated with the subsystem and allows you to change the host settings.
Make the desired change, then click Save.
Delete Host Dialog
To delete a host from the subsystem, click Add, then select Manage Hosts. The Hosts window opens.
click the delete delete icon to the right of the host.
The Delete Host confirmation dialog opens, showing the hosts associated with the subsystem.
Click Delete Anyway to delete the host from the subsystem(s) specified in the dialog.
Data Protection
The Data Protection section allows users to set up multiple redundant tasks that will protect and/or backup data in case of drive failure.
Scrub Tasks can provide early disk failure alerts by identifying data integrity problems and detecting various indicators of drive reliability.
TrueCloud Backup, Cloud Sync, Periodic Snapshot, Rsync, and Replication Tasks, provide backup storage for data and allow users to revert the system to a previous configuration or point in time.
Contents
Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.
Cloud Sync Tasks: Tutorials for configuring and managing data backups to from TrueNAS to various 3rd party Cloud Service Providers.
Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.
Advanced Replication Tasks: Provides instructions on configuring advanced ZFS snapshot replication tasks in TrueNAS.
Managing TrueCloud Backup Tasks
TrueNAS can send, receive, or synchronize data with the cloud storage providers available in TrueNAS.
TrueCloud backup tasks allow for single-time transfers or recurring transfers on a schedule.
They are an effective method to back up data to a remote location.
This article provides instructions on configuring a TrueCloud backup task using Storj and covers setting up the Storj iX account and TrueNAS credential.
To take advantage of the lower-cost benefits of the TrueCloud backup service, you must create your Storj iX account using the link provided on the Add Cloud Credentials screen.
You must also create and authorize the storage buckets on Storj for TrueNAS to use.
iXsystems is not responsible for charges incurred using a third-party vendor with the TrueCloud backup feature.
TrueCloud Backup Task Requirements
You must configure all system storage (pool and datasets or zvols) and have them ready to receive or send data.
Adding the Storj cloud credential in TrueNAS includes following the link to create the Storj iX account, creating a new bucket, and obtaining the S3 authentication credentials needed to complete the process in TrueNAS.
Go to Credentials > Backup Credentials and click Add on the Cloud Credentials widget.
The Cloud Credentials screen opens with Storj displayed as the default provider in the Provider field.
You must use this link to create your Storj account to take advantage of the benefits of the Storj iX pricing!
Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, and click the button at the bottom of the screen.
The Storj main dashboard opens.
Select the permissions you want to allow this access key.
Choose Full Access to allow permanent full permissions to all buckets and data then click Create Access or select Advanced then click Next to customize access configuration.
b. Select the buckets to allow access to.
Click All Buckets or click Select Buckets and use the Buckets dropdown to select one or more bucket(s).
Click Next.
c. Select an expiration date if you want to set the duration or length of time to allow this credential to exist.
You can select a preset period, click Set Custom Expiration Date to use the calendar to set the duration, or select No expiration.
Click Next to open the Access Encryption window.
Not all Storj buckets are TrueNAS compatible.
To create a TrueNAS-compatible bucket, either log in to Storj using the ix Storj affiliate link before creating the bucket in the Storj UI, or use the TrueNAS UI to create the bucket using the Add New option.
To create a Storj bucket from the TrueNAS UI:
Go to Data Protection.
Click Add on either the TrueCloud Backup Tasks or Cloud Sync Tasks widget.
Select the stored Storj cloud credential from the Provider > Credentials dropdown.
Do this as part of setting up a task or use the wizard to create the bucket without saving a configured task.
Click Verify Credential for verification, then click Next to go to the What and When screen.
Enter or browse to select the local Source Path to the directories or files you want sent to the cloud for backup.
Click the arrow to the left of the name to expand it, then click on the name to select it.
Select the Storj credential on the Credentials dropdown list.
You can select Add New to create the Storj credential if you skipped the instructions above.
Select the Storj bucket from the Bucket dropdown list.
If you have not previously created a TrueNAS compatible Storj bucket, select Add New and follow the procedure in Creating a TrueNAS Storj Bucket.
Click the arrow icon for the Folder field to expand the dropdown list and select the desired folder in the Storj bucket, or enter a folder path.
Enter /name, where name is a folder that does not exist, to create a new folder in the Storj bucket.
Enter a name for the task under Task Settings.
Enter the number of snapshot copies to retain in Keep Last.
Enter a password for the backup repository.
Record this password in a secure location.
You need the password to recreate the task using the same bucket/folder, such as in a new TrueNAS install or system, or to restore data from the existing snapshots in another TrueNAS system.
Set the task schedule for when to run this task.
Click Save.
TrueNAS adds the task to the TrueCloud Backup Tasks widget with the state N/A until the task runs on schedule.
To test the task, click the vertical ellipses more_vert on the task and select Run Job to start the task apart from the scheduled time.
Select Use Snapshot to create and use a snapshot to back up or synchronize the operation between TrueNAS and the TrueCloud backup solution. This snapshot is automatically removed after the operation completes.
Advanced users can write scripts that run immediately before or after the TrueCloud backup task.
Enter environment variables in either the Pre-script or Post-script fields.
The Post-script field only runs when the TrueCloud backup task succeeds.
See TrueCloud Backup Tasks Screens for information on available environment variables.
Use Exclude to enter a list of files and directories to exclude from sync.
Press Enter to separate entries.
See TrueCloud Backup Tasks Screens for syntax examples.
Use Transfer Settings to prevent excess resource consumption by setting the pack size and read concurrency.
Managing TrueCloud Tasks
To edit an existing TrueCloud backup task, click the vertical ellipses more_vert on the task and select Edit to open the Edit TrueCloud Backup Task screen. After making changes, click Save.
To run a scheduled task before the defined time, click the vertical ellipses more_vert on the task and select Run Job to start the task immediately.
To delete a task, click the vertical ellipses more_vert on the task and select delete Delete for the task to delete.
Select Include Everything to restore all data, or exclude some data using Include from subfolder, Select paths to exclude, or Exclude by pattern.
See TrueCloud Backup Tasks Screens for more information.
Set the local Target to the target dataset of the backup task.
Click Save to restore data from the snapshot.
Removing TrueCloud Snapshots
To delete an existing snapshot, locate it on the Snapshots widget.
Click the vertical ellipses more_vert on the snapshot and select delete Delete to delete the snapshot.
A Delete Snapshot dialog opens.
This section has tutorials for configuring and managing data backups to from TrueNAS to various 3rd party cloud service providers.
This article provides instructions on adding a cloud sync task, configuring environment variables, running an unscheduled sync task, creating a copy of a task with a reversed transfer mode, and troubleshooting common issues with some cloud storage providers.
TrueNAS can send, receive, or synchronize data with a cloud storage provider.
Cloud sync tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS:
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
Using the cloud means data can go to a third-party commercial vendor not directly affiliated with iXsystems.
You should fully understand vendor pricing policies and services before using them for cloud sync tasks.
iXsystems is not responsible for any charges incurred using third-party vendors with the cloud sync feature.
Cloud Sync Task Requirements
You must have:
All system storage configured and ready to receive or send data.
A cloud storage provider account and location (like an Amazon S3 bucket).
You can create cloud storage account credentials using Credentials > Backup Credentials > Cloud Credentials before adding the sync task or add it when configuring the cloud sync task using Add on the Data Protection > Cloud Sync Task widget to open the Cloudsync Task Wizard.
See the Cloud Credentials article for instructions on adding a backup cloud credential.
Creating a Cloud Sync Task
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.
Select an existing backup credential from the Credential dropdown list.
If not already added as a cloud credential, click Add New to open the Cloud Credentials screen to add the credential.
Click Save to close the screen and return to the wizard.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the option from Direction and in Transfer Mode.
Select the location where to pull from or push data to in the Folder field.
Select the dataset location in Directory/Files. Browse to the dataset to use on TrueNAS for data storage.
Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select or enter the required settings that include where files are stored. Cloud provider settings change based on the credential selected.
If shown, select the bucket on the Bucket dropdown list.
Select the time to run the task from the Schedule options.
Click Save to add the task.
Use Dry Run to test the configuration before clicking Save or select the option on the Cloud Sync Task widget after you click Save.
TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule.
Encrypting Cloud Sync Tasks
The option to encrypt data transferred to or from a cloud storage provider is available in the Advanced Options settings.
Select Remote Encryption to use rclone crypt encryption during pull and push transfers.
With Pull selected as the Transfer Direction, the Remote Encryption decrypts files stored on the remote system before the transfer.
This requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.
With Push selected as the Transfer Direction, data is encrypted before it is transferred and stored on the remote system.
This also requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.
We do not recommend enabling Filename Encryption for any cloud sync tasks that did not previously have it enabled.
Users with existing cloud sync tasks that have this setting enabled must leave it enabled on those tasks to be able to restore those existing backups.
Do not enable file name encryption on new cloud sync tasks!
When selecting Filename Encryption transfers encrypt and decrypt file names with the rclone Standard file name encryption mode.
The original directory structure of the files is preserved.
When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, use sub-paths, and copy single files.
When enabled, file names are encrypted, file names are limited to 143 characters, the directory structure is visible, and files with identical names have identical uploaded names.
File names can use sub-paths, single-copy files, and shortcuts to shorten the directory recursion.
Troubleshooting Transfer Mode Problems
Sync keeps all the files identical between the two storage locations.
If the sync encounters an error, it does not delete files in the destination.
Syncing to a Backblaze B2 bucket does not delete files from the bucket, even after deleting those files locally.
Instead, files are tagged with a version number or moved to a hidden state.
To automatically delete old or unwanted files from the bucket, adjust the Backblaze B2 Lifecycle Rules.
A directory, deleted in BackBlaze B2 and notated with an asterisk, do not display in the TrueNAS UI.
These folders are essentially empty directories and Backblaze API restricts them so they do not display.
Amazon S3 Issues
Sync cannot delete files stored in Amazon S3 Glacier or S3 Glacier Deep Archive.
First restore these files by another means, like the Amazon S3 console.
Using Scripting and Environment Variables
Advanced users can write scripts that run immediately before or after the cloud sync task.
Use either the Advanced Options screen accessed from the Cloudsync Task Wizard or Edit Cloud Sync Task screen, scroll down to the Advanced Options to locate and then enter environment variables in either the Pre-script or Post-script fields.
The Post-script field only runs when the cloud sync task succeeds.
Running an Unscheduled Cloud Sync Task
Saved tasks activate based on the schedule set for the task.
Click Run Now on the Cloud Sync Task widget to run the sync task before the saved scheduled time.
You can also expand the task on the Cloud Sync Tasks screen and click Run Now on the task details screen.
An in-progress cloud sync must finish before another can begin.
Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.
To view logs about a running task, or its most recent run, click on the State oval.
Using Cloud Sync Task Restore
To create a new cloud sync task that uses the same options but reverses the data transfer, click the vertical ellipses more_vert on an existing cloud sync task on the Data Protection page and select historyRestore.
The Restore Cloud Sync Task window opens.
Enter a name in Description for this reversed task.
Select the Transfer Mode and then define the path for a storage location on TrueNAS for the transferred data.
Click Restore.
TrueNAS saves the restored cloud sync as another entry in Data protection > Cloud Sync Tasks.
If you set the restore destination to the source dataset, TrueNAS may alter ownership of the restored files to root.
If root did not create the original files and you need them to have a different owner, you can recursively reset their ACL permissions through the GUI.
Cloud Sync Tasks Contents
Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.
Google Drive and G Suite are widely used tools for creating and sharing documents, spreadsheets, and presentations with team members.
While cloud-based tools have inherent backups and replications included by the cloud provider, certain users might require additional backup or archive capabilities.
For example, companies using G Suite for important work might be required to keep records for years, potentially beyond the scope of the G Suite subscription.
TrueNAS offers the ability to easily back up Google Drive by using the built-in cloud sync.
Setting up Google Drive Credentials
You can add Google Drive credentials using the Add Cloud Credentials screen accessed from the Credentials > Backup Credentials > Cloud Credentials screen, or you can add them when you create a cloud sync task using the Add Cloud Sync Task screen accessed from the Data Protection > Cloud Sycn Task screen.
Adding Google Drive Credentials Using Cloud Credentials
To set up a cloud credential, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
Enter a credential name.
Select Google Drive on the Provider dropdown list. The Google Drive authentication settings display on the screen.
Enter the Google Drive authentication settings.
a. Click Log In To Provider. The Google Authentication window opens.
b. Click Proceed to open the Choose an Account window.
c. Select the email account to use. Google displays the Sign In window. Enter the password and click Next to enter the password. Click Next again.
Google might display a Verify it’s you window. Enter a phone number where Google can text an verification code, or you can click Try another way.
d. Click Allow on the TrueNAS wants to access your Google Account window. TrueNAS populates Access Token with the token Google provides.
Click Verify Credentials and wait for TrueNAS to display the verification dialog with verified status. Close the dialog.
Click Save.
The Cloud Credentials widget displays the new credentials. These are also available for cloud sync tasks to use.
Adding A Google Drive Cloud Sync Task
You must add the cloud credential on the Backup Credentials screen before you create the cloud sync task.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloudsync Task Wizard opens.
Select Google Drive on the Credential dropdown list, then enter your credentials.
Click Next.
Select the direction for the sync task.
PULL brings files from the cloud storage provider to the location specified in Directory/Files (this is the location on TrueNAS).
PUSH sends files from the location in Directory/Files to the cloud storage provider location you specify in Folder.
Select the transfer method from the Transfer Mode dropdown list.
Sync keeps files identical on both TrueNAS and the remote cloud provider server. If the sync encounters an error, destination server files are not deleted.
Copy duplicates files on both the TrueNAS and remote cloud provider server.
Move transfer the files to the destination server and then deleted the copy on server that transferred the files. It also overwrites files with the same names on the destination.
Enter or browse to the dataset or folder directory.
Click the arrow_right arrow to the left of folder/ under the Directory/Files and Folder fields.
Select the TrueNAS dataset path in Directory/Files and the Google Drive path in Folder.
If PUSH is the selected Direction, this is where on TrueNAS the files you want to copy, sync or move transfer to the provider.
If Direction is set to PULL this is the location where on TrueNAS you want to copy, sync or move files to.
Click the arrow_right to the left of folder/ to collapse the folder tree.
Select the preset from the Schedule dropdown that defines when the task runs.
For a specific schedule, select Custom and use the Advanced Scheduler.
Clearing the Enable checkbox makes the configuration available without allowing the specified schedule to run the task.
To manually activate a saved task, go to Data Protection > Cloud Sync Tasks, click for the cloud sync task you want to run. Click CONTINUE or CANCEL for the Run Now operation.
(Optional) Click Advanced Options to set any advanced option you want or need for your use case or to define environment variables.
Scroll down to and enter the variables or scripts in either the Pre-script or Post-script fields.
These fields are for advanced users.
Click Dry Run to test your settings before you click Save.
TrueNAS connects to the cloud storage provider and simulates a file transfer but does not send or receive data.
The new task displays on the Cloud Sync Tasks widget with the status of PENDING until it runs.
If the task completes without issue the status becomes SUCCESS.
See Using Scripting and Environment Variables for more information on environment variables.
Working with Google Created Content
One caveat is that Google Docs and other files created with Google tools have their own proprietary set of permissions and their read/write characteristics unknown to the system over a standard file share. Files are unreadable as a result.
To allow Google-created files to become readable, allow link sharing to access the files before the backup. Doing so ensures that other users can open the files with read access, make changes, and then save them as another file if further edits are needed. Note that this is only necessary if the file was created using Google Docs, Google Sheets, or Google Slides; other files should not require modification of their share settings.
TrueNAS is perfect for storing content, including cloud-based content, for the long term. Not only is it simple to sync and backup from the cloud, but users can rest assured that their data is safe, with snapshots, copy-on-write, and built-in replication functionality.
Adding a Google Photos Cloud Sync Task
On March 31, 2025, Google changed the Google Photos API to allow external applications to access and manage only the media and albums they create.
Cloud sync tasks continue to upload photos to albums created by the TrueNAS sync client, but reading from your full photo library or from shared albums does not work as expected.
Some operations return permission errors.
Tokens issued before March 31, 2025 do not provide full-library access under the new API rules.
Generate new credentials if you need to continue uploading into albums created by the sync client.
Review existing Google Photos cloud sync tasks and configure them to use albums created by the TrueNAS source.
A complete backup of a Google Photos library through the API is not possible.
Google Photos cloud sync tasks in TrueNAS use the rclone backend for the Google Photos API to authenticate credentials and transfer data.
Configuring a Google Photos cloud sync task is a multi-part procedure where you:
A Google Photos cloud sync task can either push local files to Google Photos or (limited) pull files from Google Photos to a local TrueNAS dataset.
Select the direction that fits how you want to manage your media files.
Pull is restricted by the Google Photos API and only accesses albums created by the TrueNAS sync client.
Pulling your full library or from shared albums is not possible.
Push uploads local files into albums created by the TrueNAS sync client.
Use push to manage media in your local dataset and back it up to Google Photos.
Next, select the data transfer mode that fits how you want to manage file retention between the source and destination.
There are three options:
SYNC - Matches files on the destination to the source.
Deletes files from the destination if they do not exist on the source.
Only affects albums created by the sync client.
COPY - Duplicates each source file into the destination.
Overwrites files with the same name.
Only affects albums created by the sync client.
MOVE - Transfers files from the source to the destination and deletes them from the source.
Overwrites files with the same name.
Only affects albums created by the sync client.
Choosing a Target Folder
After choosing the direction and mode for your cloud sync task, select the remote Google Photos folder that rclone targets. Each folder option has specific file management and structure requirements due to API restrictions. Cloud sync tasks cannot target the root folder (/).
Folder
Recommended
Direction
Description
/album
Yes
Push or Pull
Use this folder for push tasks or to organize media into albums. Only albums created by the TrueNAS cloud sync client are accessible. Pull returns only items in these albums; push uploads work as expected. All local files must be in child directories (albums) under the dataset.
/media/all
No
Pull
API restrictions prevent reading your full Google Photos library. Only items in app-created albums are accessible. Do not use this option for full-library sync.
/upload
No
Push
Temporary upload location. Files pushed here are not sorted into albums, metadata can be lost, and repeated sync tasks can produce duplicates or unstable filenames. Use only for temporary transfers.
Selecting the Dataset and Organizing Files
Select a TrueNAS local dataset or create a new one to use as the source or destination.
Creating a Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
For push tasks, organize files in the local dataset so they map to albums created by the TrueNAS cloud sync client. For pull tasks, the Google Photos API only provides access to items in albums created by the sync client.
Full-library pulls or shared albums are not accessible.
Configure your dataset accordingly based on your chosen direction, mode, and target folder.
Creating the API Credentials
Tokens generated before March 31, 2025 do not provide full access to your Google Photos library under the new API rules. When creating credentials, ensure that your OAuth client and token are intended for use with albums created by the TrueNAS cloud sync client.
Only these app-created albums can be accessed for push or pull tasks.
On the Google API dashboard, click the dropdown menu to the right of the Google Cloud logo and select your project.
If you do not have a project, click NEW PROJECT and enter a value in Project name, Organization, and Location.
Click Create.
Enter photos library api in the search bar, then select Photos Library API and click ENABLE.
This enables the API for your project
Access remains limited to albums created by the TrueNAS cloud sync client.
Can I leave the app in testing mode?
You can leave the app in testing mode, but testing app credentials expire after seven days.
Cloud sync tasks fail when testing mode credentials expire.
Create Credentials
Click Credentials on the left menu, then click + CREATE CREDENTIALS and select OAuth client ID.
Download rclone for your client OS and open it in a command line utility following the rclone installation instructions.
The example photos in this article use Powershell in Windows OS.
Enter rclone config, then enter n to create a new remote.
Enter a name for the new remote, then enter the number from the list corresponding to Google Photos.
Enter the client id and secret you saved when you created the Google Photos API credentials, then enter false or press Enter to allow the Google Photos backend to request full access.
Note: After March 31, 2025, full-library access is no longer possible under the Google Photos API.
Even if rclone requests full access, it only sees albums created by the TrueNAS cloud sync client.
Enter y to authenticate rclone using the web browser.
A browser window opens to authorize rclone access.
Click Allow.
In the command line, enter y to confirm rclone uploads media items with full resolution and complete the configuration.
Only albums created by the TrueNAS cloud sync client are accessible.
Copy and save the type, client_id, client_secret, and token, then enter y to save the new remote.
Select Google Photos as the Provider and enter a name.
Paste the Google Photos API client ID and client secret in the OAuth Client ID and OAuth Client Secret fields.
Paste your rclone token into the Token field.
Note: Due to API restrictions, these credentials only provide access to albums created by the TrueNAS cloud sync client
Full-library or shared-album access is not possible.
Click Verify Credential to ensure the credentials are valid, then click Save.
Creating the Cloud Sync Task
Go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.
Select the Google Photos backup credentials from the Credentials dropdown list.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the Direction as PUSH or PULL and select the Transfer Mode as SYNC, COPY, or MOVE.
Select the Google Photos location to back up data to or from in Folder.
Browse to and select the album folder or enter /album.
Note: Pull tasks only access albums created by the TrueNAS cloud sync client.
Full-library pulls or shared albums are not accessible.
Select the local dataset in Directory/Files.
This is the dataset sent to Google Photos for push tasks or the write destination for pull tasks.
Push tasks containing media files saved to the local dataset root level fail with the error: Failed to sync: can’t upload files here.
Save files to child directories, not to the root level of the TrueNAS dataset.
Directories under the local dataset correspond to albums created by the TrueNAS cloud sync client in Google Photos.
Enter a Description for the cloud sync task.
Select the time to run the task from the Schedule options.
Click Save to add the task.
TrueNAS adds the task to the Cloud Sync Task widget with the status Pending, until the task runs on schedule.
Click Dry Run to test the task by connecting to Google Photos and simulating transferring a file.
During a dry run, TrueNAS sends or receives no data.
A dry run can report successful even for a task that fails to transfer data due to misconfiguration
Click the vertical ellipses more_vert on the task and select Run Job to start the cloud sync task immediately.
Troubleshooting
If a Google Photos cloud sync task fails, go to Data Protection and click the FAILED status in State on the Cloud Sync Tasks widget.
Review the logged error messages.
Common error messages for failed Google Photos tasks include:
Failed to copy: can't upload files here
Problem: A push task attempts to upload files to the root level / folder or the /upload folder.
Solution: Reconfigure the push task to target the /album folder and organize your files into child directories (albums).
Directories under the local dataset correspond to albums the TrueNAS cloud sync client creates in Google Photos.
Only albums the sync client creates are accessible to cloud sync tasks.
Pulling from the root directory is not allowed. Please, select a specific directory
Problem: A pull or push task targets the root level / folder.
Solution: Change the target folder to /album.
Pull tasks transfer only media that exist in albums created by the TrueNAS cloud sync client.
Full-library pulls and shared albums are not accessible via the API.
Do not rely on /media/all for a full export.
Failed to copy: directory not found
Problem: A pull task targets the /upload folder.
Solution: The /upload folder functions as a temporary upload queue.
rclone cannot pull from /upload.
Change the target folder to /album and organize files accordingly.
Remember that only albums created by the TrueNAS cloud sync client are accessible for pull tasks.
If a pull task runs but some or all files never appear in the local dataset, those files are not in albums created by the TrueNAS cloud sync client and the API does not expose them to the sync client.
To get originals from Google Photos you can:
Export your account via Google Takeout (download the archive and import the files into TrueNAS).
Download desired photos directly from Google Photos and copy them into your TrueNAS dataset.
If you want the sync client to manage media going forward, create and sync albums via TrueNAS.
Those albums then remain accessible to the TrueNAS cloud sync client.
Configuring Rsync Tasks
Rsync provides fast incremental data transfer to synchronize files between a TrueNAS system and a remote system.
The Push function copies data from TrueNAS to a remote system.
The Pull function copies data from a remote system to the TrueNAS local host system and stores it in the dataset defined in the Path field.
There are two ways to connect to a remote system and run an rsync task:
Module mode requires adding an rsync app to the remote system, configuring a module on that system, and then entering it in the rsync task in TrueNAS.
SSH mode has two connection options:
SSH private key stored in the user’s home directory
SSH connection for the keychain
Setting options change based on the SSH connection option selected.
Set up a home directory for the remote system administrator on the remote system.
Note the path to where home directories are stored to enter on the local host TrueNAS.
If the remote system is also a TrueNAS, go to Credentials, select Users to see the list of users.
Select the administration user and click Edit.
If creating a new administration user for rsync functions, click Add.
See Managing Users for more information.
Take note of the path to the home directory to use in setting up the connection.
Add an SSH connection for the remote server on the local TrueNAS host system.
Adding a remote TrueNAS system
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
TrueNAS allows configuring multiple admin users on the system. All admin users configured in the TrueNAS system show in the rsync task User dropdown list.
Adding an Rsync Task Using SSH
Enabled SSH on both the local host TrueNAS, and the remote destination system.
You can use the SSS connection created in Setting Up an SSH Connection or create a new connection while configuring the rsync task.
Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Enter or browse to the dataset or folder to sync with the remote server.
Use the arrow_right to the left of the /mnt folder and each folder listed on the tree to expand and browse through, then click on the name to populate the path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select the administration user for the local host TrueNAS system from the User dropdown. This is the user account to perform the rsync task.
The user must have read/write permissions for the local dataset.
Set the Direction for the rsync task.
Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.
Set the Rsync Mode to SSH, and then select the connection method from the Connect using dropdown list.
Settings fields for the selected connection type show.
If selecting SSH private key stored in the user home directory, the public key for the SSH connection must be alread be saved in the home directory for the admin user.
If selecting SSH connection from the keychain, choose either the existing SSH credential from the SSH Connection dropdown list or select Add New to open the New SSH Connection configuration screen. See Using an SSH Connection below for more information.
If the connection fails, the system lets you know what is wrong so you can correct the issue with the connection.
Enter the full path to the dataset on the remote server in Remote Path. The maximum path length is 255 characters.
To confirm the remote server is reachable and the path exists, leave Validate Remote Path selected.
Select a schedule for when to run this task and any other options you want to use.
If you need a custom schedule, select Custom to open the advanced scheduler window.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Leave Enabled selected. Clear the checkbox to disable the task without deleting the configuration.
Click Save. The system verifies the SSH connection and adds the task to the Rsync Tasks widget.
To run the rsync task at any time, select it on the Rsync Tasks widget, click on the vertical ellipses more_vert for the task, and select the Run Now.
Using an SSH Connection
The TrueNAS UI allows users to select an existing SSH connection or to create a new connection while configuring the task.
The New SSH Connection screen opened using the Add New option in the rsync task and accessed while on the Backup Credentials screen are essentially the same and show the same setting options.
To set up a new SSH connection before adding an rsync task, go to Credentials > Backup Credentials and click Add on the SSH Connections widget.
See Adding SSH Credentials for more information on adding SSH Connections and key pairs.
To add a new connection while configuring the rsync task on the Add Rsync Task screen, set the mode to SSH, select SSH connection for the keychain, and then select Add New on the SSH Connection dropdown list. The New SSH Connection screen opens.
Adding an SSH Connection to a TrueNAS System
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Adding an SSH Connection to a Non-TrueNAS System
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select Manual from the Setup Method dropdown list.
a. Enter a host name or host IP address for the remote non-TrueNAS system as a valid URL.
An IP address example is https://10.231.3.76.
This is a required field.
b. Enter the port number of the remote system to use for the SSH connection.
c. Enter a user name for logging into the remote system in Username.
d. Select the private key from the SSH key pair that you use to transfer the public key on the remote NAS from the Private Key dropdown.
e. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate the Remote Host Key field.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection widget.
To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.
Next, set up a home directory for the system administrator on the remote system if one does not already exist.
If the remote system is a TrueNAS, edit the user to add the public key. In TrueNAS, go to Users, click Edit, and paste the key into the pubic key field.
After adding the SSH connection, go to System > Services to turn on the SSH service.
We don’t recommend leaving the SSH service turned on when not in use for security hardening.
Turn it on before the rsync task is scheduled to run, then off again after the task completes to keep your system secured.
(Optional) To automatically start or restart the SSH service after a system restart, select this option.
Enable the SSH service on the remote system according to the configuration process for a non-TrueNAS system.
Setting Up an Rsync Task Using Module Mode
Before you create an rsync task in module mode, you must define at least one module per rsyncd.conf(5) on the remote rsync server.
The Rsync Daemon application is available in situations where configuring TrueNAS as an rsync server with an rsync module is necessary.
After configuring the remote server with rsync and a module, configure the rsync task in TrueNAS.
Setting Up an Rsync Module
If the non-TruNAS remote server includes an rsync service, make sure it is turned on. To configure a module on the remote server:
Create a dataset.
Write down the host and path to the data on the remote system you plan to sync with.
Create an rsync module.
If the remote system is not a TrueNAS and has an rsync app installed, create a module according to the configuration process for that app and system.
If the remote system is not a TrueNAS, install an rsync app, such as Rsyncd, and configure it per the instructions for the app and your remote non-TrueNAS system.
If the remote system is another TrueNAS, install an rsync app.
Debian-based TrueNAS systems include the Rsync Daemon app in the Community app catalog.
Install the app and use it to configure a module.
Configuring a module in the TrueNAS RsyncD app
To create the module, you need the IP address or host name of your TrueNAS (host) server.
The host server is configured with the rsync task that transfers your data to the remote server.
When the remote system is a Debian-based TrueNAS system, go to Apps > Discover Apps and search for the Rsync Daemon app.
Click on the widget, and then click Install to open the installation wizard.
To add a module, click Add to the right of Rsync Modules, then:
Assign a name. This name is added in the Add Rsync Task screen on your TrueNAS system when you set up a task using Module in the Rsync Mode field.
(Optional) Enter a comment to help you remember the purpose of this module or where it is used.
Select the host path for the rsyncd app.
You can use Create Dataset to add a new dataset, and repeat to add a new child dataset if not selecting an existing dataset.
Set the level of access by selecting the option on the Access Mode dropdown list.
(Optional) Add IP addresses to the Host Allow or Host Deny options if you want to narrow access to this module.
Take note of the name of the module and the host path to it or use in later when you add the rsync task in your TrueNAS system.
Complete the rest of the app configuration to suit your use case, and click Install.
The app shows in the TrueNAS UI on the Applications screen as Running when fully deployed.
Adding an Rsync Task Using Module Mode
To configure the rsync task using module mode, you need:
The name of the module
The IP address or host name for the remote server
The path to the dataset
Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Enter or browse to and select the dataset or folder to sync with the remote server.
Clicking on the dataset name populates the path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select the admin account to perform the rsync task on the User dropdown list.
The user must have permissions to run an rsync on the remote server and read/write permission for the local dataset.
Set the Direction for the rsync task.
Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.
Set the Rsync Mode to Module.
The module settings fields show.
Enter the remote host name or IP in Remote Host.
Set the schedule for when to run this task, and any other options you want to use.
If you need a custom schedule, select Custom to open the advanced scheduler window.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Leave the Enabled selected to enable the task.
Clear the checkbox to disable the task without deleting the configuration.
Click Save.
You can run the rsync task by clicking then the Run Nowplay_arrow icon for the rsync task on the Rsync Task widget.
Adding Periodic Snapshot Tasks
Periodic snapshot tasks allow you to schedule creating read-only versions of pools and datasets at a given point in time. You can also access VMWare snapshot integration and TrueNAS storage snapshots from the Periodic Snapshot Tasks widget.
How should I use snapshots?
Snapshots do not make copies of the data so creating one is quick and if little data changed, they take very little space.
It is common to take frequent snapshots as soon as every 15 minutes, even for large and active pools.
A snapshot where no files changed takes no storage space, but as files changes happen, the snapshot size changes to reflect the size of the changes.
In the same way as all pool data, after deleting the last reference to the data you recover the space.
Snapshots keep a history of files, providing a way to recover an older copy or even a deleted file.
For this reason, many administrators take snapshots often, store them for a period of time, and store them on another system, typically using the Replication Tasks function.
Such a strategy allows the administrator to roll the system back to a specific point in time.
If there is a catastrophic loss, an off-site snapshot can restore data up to the time of the last snapshot.
Creating a Periodic Snapshot Task
Create the required datasets or zvols before creating a snapshot task.
Go to Data Protection > Periodic Snapshot Tasks and click Add.
First, choose the dataset (or zvol) to schedule as a regular backup with snapshots, and how long to store the snapshots.
Next, define the task Schedule.
If you need a specific schedule, choose Custom and use the Advanced Scheduler section below.
Configure the remaining options for your use case.
For help with naming schema and lifetime settings refer to the sections below.
Click Save to save this task and add it to the list in Data Protection > Periodic Snapshot Tasks.
You can find any snapshots taken using this task in Storage > Snapshots.
To check the log for a saved snapshot schedule, go to Data Protection > Periodic Snapshot Tasks and click on the task. The Edit Periodic Snapshot Tasks screen displays where you can modify any settings for the task.
Using the Advanced Scheduler
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Using Naming Schemas
The Naming Schema determines how automated snapshot names generate.
A valid schema requires the %Y (year), %m (month), %d (day), %H (hour), and %M (minute) time strings, but you can add more identifiers to the schema too, using any identifiers from the Python strptime function.
For Periodic Snapshot Tasks used to set up a replication task with the Replication Task function:
You can use custom naming schema for full backup replication tasks. If you are going to use the snapshot for an incremental replication task, use the default naming schema.
This uses some letters differently from POSIX (Unix) time functions.
For example, including %z (time zone) ensures that snapshots do not have naming conflicts when daylight time starts and ends, and %S (second) adds finer time granularity.
When referencing snapshots from a Windows computer, avoid using characters like colon (:) that are invalid in a Windows file path.
Some applications limit filename or path length, and there might be limitations related to spaces and other characters.
Always consider future uses and ensure the name given to a periodic snapshot is acceptable.
Setting Snapshot Lifetimes
A snapshot lifetime value defines how long the snapshot schedule ignores that snapshot when it looks for obsolete snapshots to remove.
For example, defining a lifetime of two weeks on a snapshot created after a weekly snapshot schedule runs can result in that snapshot actually being deleted three weeks later.
This is because the snapshot has a timestamp and defined lifetime that preserves the snapshot until the next time the scheduled snapshot task runs.
TrueNAS also preserves snapshots when at least one periodic task requires it.
For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for 3 years.
Each has an hourly snapshot taken.
After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task.
These snapshots get destroyed at the end of 3 years.
Creating VMWare Snapshots
Use this procedure to create ZFS snapshots when using TrueNAS as a VMWare datastore.
You must have a paid edition of VMWare ESXi to use the TrueNAS VMWare Snapshots feature.
ESXi free has a locked (read-only) API that prevents using TrueNAS VMWare Snapshots.
This tutorial uses ESXi version 8.
When creating a ZFS snapshot of the connected dataset, VMWare automatically takes a snapshot of any running virtual machines on the associated datastore.
VMware snapshots can integrate VMware Tools, making it possible to quiesce VM snapshots, sync filesystems, take shadow copy snapshots, and more.
Quiescing snapshots is the process of bringing VM data into a consistent state, suitable for creating automatic backups.
Quiesced snapshots can be file-system consistent, where all pending data or file-system changes complete, or application consistent, where applications complete all tasks and flush buffers, prior to creating the snapshot.See Manage Snapshots from VMWare for more information.
VM snapshots are included as part of the connected Virtual Machine File System (VMFS) datastore and stored as a point-in-time within the scheduled or manual TrueNAS ZFS snapshot of the data or zvol backing that VMWare datastore.
The temporary VMware snapshots are automatically deleted on the VMWare side, but still exist in the ZFS snapshot and are available as stable restore points.
TrueNAS Enterprise
TrueNAS Enterprise customers with TrueNAS 12.0 and newer and TrueNAS 22.12.4 (Bluefin) and newer deployed can access the iXsystems TrueNAS vCenter plugin.
This activates management options for TrueNAS hardware attached to vCenter Server and enables limited management of TrueNAS systems from a single interface.
Please contact TrueNAS Enterprise Support to learn more and schedule a time to deploy or upgrade the plugin.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Before using TrueNAS to create VMWare snapshots, configure TrueNAS to present a VMFS datastore or NFS export to your ESXi host(s) (this tutorial uses iSCSI) and then create and start your VM(s) in ESXi.
Virtual machines must be running for TrueNAS to include them in VMWare snapshots, because powered-off virtual machines are already in a consistent state
Go to Datasets and click Add Zvol to create a dedicated zvol for VMWare. This tutorial uses virtual/vmware/zvol-01.
Create an iSCSI share.
Go to Shares and click Wizard on the Block (iSCSI) Shares Targets widget.
a. Enter a name for the share. For example, vmware. Select Device for Extent Type and select the zvol from the Device dropdown.
Leave Sharing Platform set to VMware and Target set to Create New, then click Next.
b. Set Portal to Create New.
You can leave Discovery Authentication Method set to NONE, or select CHAP or Mutual CHAP and enter a Discovery Authentication Group ID.
Click Add next to IP Address and select either 0.0.0.0 for IPv4 or :: for IPv6 to listen on all ports.
c. Leave Initiators blank and click Save.
In the VMWare ESXi Host Client, go to Storage, select Adapters, and then click Software iSCSI to configure the iSCSI connection.
c. Click Rescan to discover the iSCSI initiator.
ESXi automatically adds static targets for discovered initiators.
Click Software iSCSI again to confirm.
d. Go to Devices and click Rescan to discover the shared storage. ESXi adds the TrueNAS iSCSI disk to the list of devices.
Go to Datastores and click New Datastore to create a new VMFS datastore using the TrueNAS device.
Then go to Virtual Machines and create your new virtual machine(s), using the new datastore for storage.
Creating a VMWare Snapshot
To configure TrueNAS to create VMWare snapshots, go to Data Protection and click the VMware Snapshot Integration button in the Periodic Snapshot Tasks widget to open the VMWare Snapshots screen.
Note that you can organize information in the columns of the table(s) below by clicking on each column title. This allows you to toggle the information between a descending an ascending order.
You must follow the exact sequence to add the VMware snapshot or the ZFS Filesystem and Datastore fields do not populate with options available on your system.
If you click in ZFS Filestore* or Datastores before you click Fetch Datastores the creation process fails, the two fields do not populate with the information from the VMWare host, and you must exit the add form or click Cancel and start again.
Enter the IP address or host name for your VMWare system in Hostname.
Enter the user credentials on the VMware host with ‘Create Snapshot’ and ‘Remove Snapshot’ permissions in VMware.
See Virtual Machine Snapshot Management Privileges from VMware for more information.
Click Fetch Datastores. This connects TrueNAS to the VMWare host and populates the ZFS Filesystem and Datastore dropdown fields.
Make sure the correct TrueNAS ZFS dataset or zvol matching the VMware datastore is populated.
Select the TrueNAS dataset from the ZFS Filesystem dropdown list of options.
Select the VMFS datastore from the Datastore dropdown list of options.
Click Save.
The saved snapshot configuration appears on the VMware Snapshots screen.
State indicates the current status of the VMware connection as PENDING, SUCCESS, or ERROR.
Create a new periodic snapshot task for the zvol or a parent dataset.
If there is an existing snapshot task for the zvol or a parent dataset, VMWare snapshots are automatically integrated with any snapshots created after the VMWare snapshot is configured.
Expand the configured task on the Periodic Snapshot Tasks screen and ensure that VMware Sync is true.
Reverting to a ZFS Snapshot in VMWare ESXi
To revert a VM using a ZFS snapshot, first clone the snapshot as a new dataset in TrueNAS, present the cloned dataset to ESXi as a new LUN, resignature the snapshot to create a new datastore, then stop the old VM and re-register the existing machine from the new datastore.
Clone the snapshot to a new dataset.
a. Go to Data Protection and click Snapshots on the Periodic Snapshot Tasks widget and locate the snapshot you want to recover and click on that row to expand details.
b. Click Clone to New Dataset.
Enter a name for the new dataset or accept the one provided then click Clone.
Share the cloned zvol to VMWare using NFS or iSCSI (this tutorial uses iSCSI).
a. Go to Shares and click Block (iSCSI) Shares Targets to access the iSCSI screen.
b. Click Extents and then click Add to open the Add Extent screen.
c. Enter a name for the new extent, select Device from the Extent Type dropdown, and select the cloned zvol from the Device dropdown.
Edit other settings according to your use case and then click Save.
d. Click Associated Targets and then click Add to open the Add Associated Target screen.
e. Select the existing VMWare target from the Target dropdown.
Enter a new LUN ID number or leave it blank to automatically assign the next available number.
Select the new extent from the Extent dropdown and then click Save.
Go to Storage > Adapters and click Rescan to discover the new LUN.
Then go to the Devices tab and click Rescan again to discover VMFS filesystems on the LUN.
At this point, ESXi discovers the cloned device snapshot, but is unable to mount it because the original device is still online.
Resignature the snapshot so that it can be mounted.
a. Access the ESXi host shell using SSH or a local console connection to resignature the snapshot
b. Go back to Storage > Devices in the ESXi Host Client UI and click Refresh.
The mounted snapshot appears in the list of devices.
Select the VM(s) you want to revert and click Next.
e. Review selections on the Ready to complete screen/ If correct, click Finish.
Start the new VM(s) and verify functionality, then delete or archive the previous VM(s).
Copy or migrate the VMware virtual machine to the original, non-snapshot datastore.
Replication Tasks
TrueNAS replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their TrueNAS system as a way to back up stored data.
When properly configured and scheduled, replication takes regular snapshots of storage pools or datasets and saves them in the destination location either on the same system or a different system.
Setting Up a Simple Replication Task Overview
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The sections below provide overviews on what to do before you begin configuring a replication task.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
Contents
Setting Up a Local Replication Task: Provides instructions on adding a replication task using different pools or datasets on the same TrueNAS system.
A local replication creates a ZFS snapshot and saves it to another location on the same TrueNAS system using different pools, datasets, or zvols.
This allows users with only one system to take quick data backups or snapshots of their data when they have only one system.
If you have only one pool, create a dataset in that pool to store the replication snapshots. You can use a zvol for this purpose.
If configuring local replication on a system with more than one pool, create a dataset for the replicated snapshots on one of those pools.
While we recommend regularly scheduled replications to a remote location as the optimal backup scenario, local replication is useful when a remote backup location is available or when a disk is in immediate danger of failure.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused.
Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume.
Do not assign capacity that exceeds what is required for TrueNAS to operate properly. For more information, see TrueNAS Hardware Guide for CPU, memory and storage capacity information.
Setting up replication tasks as an admin user has a few differences from setting up replication tasks when logged in as root.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
To configure the local replication task, follow the instructions in the section below.
Configuring a Local Replication Task
Use the Replication Task Wizard to create and copy ZFS snapshots to another system, which streamlines creating simple replication tasks.
After creating the replication task, TrueNAS automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list.
This loads the configuration settings for that task into the wizard, where you can make changes such as assigning it a different destination, setting a new schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task originally loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify that the destination dataset where you plan to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
After completing the basic preparation steps in the section above, go to Data Protection > Replication and click Add to open the replication wizard.
To configure advanced settings, click Advanced Replication Creation to open the Add Replication Task screen before you enter any settings in the wizard.
Refer to the Advanced Replication Tasks for configuration instructions using the Add Replication Task screen.
On the What and Where replication wizard screen:
Select an existing replication task from the Load Previous Replication Task dropdown.
If one does not exist, leave this set to the default, which is the double dashes.
Select the source and destination locations. You can select these in any order.
Local replication sends or receives data from one storage location to another on the same (local) system.
Remote replication sends data to or receives data from a storage location on a different (remote) TruNAS system.
To set up a local replication in the replication wizard, set both Source Location and Destination Location to On this System.
To set up a push remote replication in the replication wizard, set the Source Location to On this System and set Destination Location to On a Different System.
To set up a pull remote replication in the replication wizard, set the Source location to On a Different System and the Destination Location to On this System.
Setting either source or destination to On a Different System automatically sets the other to On This System. You cannot set both to On a Different System.
Click on Source Location or Destination Location to show additional setting options and the file browser. Additional settings shown are based on the selection.
Configure the settings for local replication after selecting On This System in either Source Location or Destination Location.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
a. Use the file browser for Source Location to browse to the location of the dataset with the data to replicate.
Clicking on the dataset(s) populates the Source path.
When setting up the Source, you can select multiple sources or manually type the names into the Source field.
b. Use the file browser for Destination Location to browse to the location of the pool or dataset to receive the replicated snapshots.
Clicking on the dataset populates Destination path.
When setting up the Destination, the Destination path allows adding a directory/dataset by entering /name, where /name is the name of a directory or dataset. The source path does not allow adding a new dataset/directory.
You can use zvols as a local replication destination. Add a name to the end of the path to create a new dataset in that location.
c. (Optional) Enter a name for the snapshot in Task Name.
TrueNAS populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
(Optional) Select Recursive to replicate all snapshots contained within the parent dataset and any child datasets.
(Optional) Accept the default name in Task Name, or enter a name of your choosing.
TrueNAS populates this field with a default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to show the scheduling options.
Select the schedule and snapshot retention lifetime.
LeaveReplication Schedule set to Run On a Schedule and select the option in the Schedule dropdown.
Select Run Once to set up a replication task you run one time.
Select the Destination Snapshot Lifetime option to specify how long TrueNAS should store copied snapshots in the destination dataset before TrueNAS deletes it.
Same as Source is selected by default.
Select Never Delete to keep all snapshots until you delete them manually.
Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click Save.
The task shows on the Replication Task widget with the status as PENDING.
Select Run Now if you want to run the task immediately.
Click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset.
Click Show extra columns to add more information columns to the table, such as the date created, which can help you locate a specific snapshot or enter part of or the full name in the search field to narrow the list of snapshots.
Remote replication backs up data stored on an originating TrueNAS system to a second remote destination TrueNAS system.
TrueNAS allows scheduling a one-time or regularly scheduled ZFS snapshot of data stored in pools, datasets, or zvols, and saves them in another system.
With the implementation of the administration user and role-based permissions, setting up replication tasks as an admin user has a few differences from those set up when logged in as the root user.
Setting up remote replication when logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
To configure the remote replication task, follow the instructions in the section below.
Creating a Remote Replication Task
Use the Replication Task Wizard to create and copy ZFS snapshots to another system, which streamlines creating simple replication tasks.
After creating the replication task, TrueNAS automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list.
This loads the configuration settings for that task into the wizard, where you can make changes such as assigning it a different destination, setting a new schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task originally loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify that the destination dataset where you plan to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
After completing the basic preparation steps in the section above, go to Data Protection > Replication and click Add to open the replication wizard.
To configure advanced settings, click Advanced Replication Creation to open the Add Replication Task screen before you enter any settings in the wizard.
Refer to the Advanced Replication Tasks for configuration instructions using the Add Replication Task screen.
On the What and Where replication wizard screen:
Select an existing replication task from the Load Previous Replication Task dropdown.
If one does not exist, leave this set to the default, which is the double dashes.
Select the source and destination locations. You can select these in any order.
Local replication sends or receives data from one storage location to another on the same (local) system.
Remote replication sends data to or receives data from a storage location on a different (remote) TruNAS system.
To set up a local replication in the replication wizard, set both Source Location and Destination Location to On this System.
To set up a push remote replication in the replication wizard, set the Source Location to On this System and set Destination Location to On a Different System.
To set up a pull remote replication in the replication wizard, set the Source location to On a Different System and the Destination Location to On this System.
Setting either source or destination to On a Different System automatically sets the other to On This System. You cannot set both to On a Different System.
Click on Source Location or Destination Location to show additional setting options and the file browser. Additional settings shown are based on the selection.
Configure the settings for remote replication after selecting On a Different System in either Source Location or Destination Location.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
a. Select an existing SSH connection from the dropdown list or select Add New to open the New SSH Connection screen.
If you created the SSH connection in the section above, select it.
When adding a new connection in the wizard, if TrueNAS detects other configuration issues, such as the user not correctly set up, an error indicating what the issue is shows in the wizard.
Exit the replication wizard to correct issues, then return to the wizard to begin the task configuration again.
After completing the replication wizard task creation, where you added a new SSH connection in the wizard, return to the remote system user configuration to add the new public key for the SSH connection to the admin user configuration.
b. Use the file browser to browse and select the parent dataset with the data to replicate. Clicking on the dataset(s) populates the path.
When setting up the Source, you can select multiple sources or manually type the names into the Source field.
When setting up the Destination, the Destination path allows adding a directory/dataset by entering /name, where rname is the name of a directory or dataset. The source path does not allow adding a new dataset/directory.
You cannot use zvols as a remote replication destination. Add a name to the end of the path to create a new dataset in that location.
c. Select Use Sudo for ZFS Commands.
A dialog opens prompting you to add this capability. Selecting this removes the need to issue the cli zfs allow command in Shell on the remote system.
Click Use Sudo for ZFS Commands. If the dialog closes before clicking this option, you can select this option on the wizard screen.
(Optional) Select Replicate Custom Snapshots, then leave the default value in Naming Schema.
If you know how and want to enter the schema, enter it in Naming Schema.
A snapshot naming schema identifies the snapshots to replicate, and might be required by the remote system.
A naming schema is a string of strftime(3) %Y, %m, %d, %H, and %M variables that name custom snapshots you want to replicate.
Separate entries by pressing Enter. The number of snapshots matching the pattern entered shows on a dropdown list.
Selecting Matching regular expression does not automatically destroy snapshots, whereas selecting Matching naming schema does.
When using a regular expression, the snapshots on the destination host are not automatically destroyed when they are destroyed on the source host due to the snapshot lifetime.
Snapshots on the destination host display as “Will not be destroyed automatically” and do not display with a retention period.
Use naming schema for these.
(Optional) Select Recursive to replicate all snapshots contained within the parent dataset and any child datasets.
(Optional) Accept the default name in Task Name, or enter a name of your choosing.
TrueNAS populates this field with a default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to show the scheduling options.
Select the schedule and snapshot retention lifetime.
LeaveReplication Schedule set to Run On a Schedule and select the option in the Schedule dropdown.
Select Run Once to set up a replication task you run one time.
Select the Destination Snapshot Lifetime option to specify how long TrueNAS should store copied snapshots in the destination dataset before TrueNAS deletes it.
Same as Source is selected by default.
Select Never Delete to keep all snapshots until you delete them manually.
Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click Save.
The task shows on the Replication Task widget with the status as PENDING.
Select Run Now if you want to run the task immediately.
Click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset.
Click Show extra columns to add more information columns to the table, such as the date created, which can help you locate a specific snapshot or enter part of or the full name in the search field to narrow the list of snapshots.
Select the Setup Method from the dropdown list. Leave this set to Semi-Automatic for a connection to another TrueNAS system.
Enter the remote TrueNAS host name or IP address as a URL in TrueNAS URL.
Enter the administration user (i.e., root or admin) that logs into the remote system with the web UI in Admin Username.
Enter the password in Admin Password.
If using a TrueNAS 13.0-U6.x system as the remote server, the remote user is always root.
When using an earlier TrueNAS 22.12.1 system or if you installed TrueNAS as the root user and then created an admin user after initial installation, you must verify that the admin user is correctly configured.
Enter the administration user (i.e., root or admin) for the remote system SSH session.
If you clear root as the the user and type any other name the Enable passwordless sudo for ZFS commands option displays.
This option does nothing, so leave it cleared.
Select Generate New from the Private Key dropdown list.
(Optional) Enter a new value in seconds for the Connection Timeout if you want to change the defaults.
Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.
After creating a new SSH connection, go to Credentials > Backup Credentials > SSH Connections, click Edit to copy the public key, then edit the remote user configuration by pasting this in the Public SSH Key field.
Using SSH Transfer Security
We always recommend using encryption for SSH transfer security.
In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer.
However, the data is completely unprotected from eavesdropping.
Choosing No Encryption for the task is less secure but faster.
This method uses common port settings but you can override these when using the Advanced Replication Creation options or by editing the task after creating it in the wizard.
TrueNAS advanced replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets, or zvols on their TrueNAS system as a way to back up stored data.
When properly configured and scheduled, local or remote replication using the Advanced Replication Creation option takes regular snapshots of storage pools or datasets and saves them in the destination location on the same or another system.
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The Advanced Replication Creation option opens the Add Replication Task screen.
This screen provides access to the same settings found in the replication wizard, but has more options to specify:
Full file system replication
Stream compression
Replication speed
Attempts to replicate data before the task fails
Block size for data sent
Log level verbosity
You can also:
Change encrypted replication to allow an unencrypted dataset as the destination
Create replication from scratch
Include or exclude replication properties
Replicate specific snapshots that match a defined creation time.
Prevent the snapshot retention policy from removing source system snapshots that failed
With the implementation of the local administrator user to replace the root login, there are a few differences between setting up replication tasks as an admin user than with setting up replication tasks when logged in as root.
Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Setting Up a Replication Task Overview
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote.
It also covers the related steps you should take prior to configuring a replication task.
Setting Up a Simple Replication Task Overview
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The sections below provide overviews on what to do before you begin configuring a replication task.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
Configure your SSH connection before you begin configuring the replication task through the Add Replication Task screen.
If you have an existing SSH connection with the remote system the option displays on the SSH Connection dropdown list.
Turn on SSH service. Go to System > Services screen, verify the SSH service configuration, then enable it.
Creating a Simplified Advanced Replication Task
To access advanced replication settings, click Advanced Replication Creation at the bottom of the first replication wizard screen.
The Add Replication Task configuration screen opens.
Give the task a name.
Unlike the wizard, the Name does not automatically populate with the source/destination task name after you set the source and destination for the task.
Each task name must be unique, and we recommend naming it in a way that makes it easy to remember what the task is doing.
Select the direction of the task. Pull pulls data from a remote system to the local system. Push sends data from the local system to the remote.
Select the transfer method for this replication from the Transport dropdown list.
Select LOCAL to replicate data to another location on the same system.
Select SSH is the standard option for sending or receiving data from a remote system.
When selected, also select an SSH connection from the SSH Connection dropdown list.
Select SSH+Netcat is a faster option for replication when it occurs within a completely secure network.
SSH+Netcat requires defining NETCAT ports and addresses to use for the NETCAT connection.
With SSH-based replications, select the SSH Connection with the remote system from which you want to receive snapshots or send snapshots to.
To create a new connection to use for replication from a destination to this local system, select newpullssh.
Select Use Sudo for Zfs Commands to control whether the user for SSH/SSH+NETCAT replication has passwordless sudo enabled to execute zfs commands on the remote host.
If not selected, you must enter zfs allow on the remote system to to grant non-user permissions to perform ZFS tasks.
Specify the source and destination paths. Destination paths allow adding /name to the end of the path to create a new dataset in that location.
Click the arrow to the left of each folder or dataset name to expand the options and browse to the dataset, then click on the dataset to populate the Source.
Choose a preconfigured periodic snapshot task as the source of snapshots to replicate.
Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories.
A remote destination requires you to specify an SSH connection before you can enter or select the path.
If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and configure it to allow SSH connections.
Define how long to keep snapshots in the destination.
Remote sources require defining a snapshot naming schema to identify the snapshots to replicate.
Local sources are replicated by snapshots that were generated from a periodic snapshot task and/or from a defined naming schema that matches manually created snapshots.
DO NOT use zvols as remote destinations.
Select a previously configured periodic snapshot task for this replication task in Periodic Snapshot Tasks.
The replication task selected must have the same values in Recursive and Exclude Child Datasets as the chosen periodic snapshot task.
Selecting a periodic snapshot schedule removes the Schedule field.
If a periodic snapshot task does not exist, before creating the advanced replication task, configure a periodic snapshot task, then return to the Add Replication Task screen to configure the replication Task.
Select Replicate Specific Snapshots to define specific snapshots from the periodic task to use for the replication.
This displays the schedule options for the snapshot task. Enter the schedule.
The only periodically generated snapshots included in the replication task are those that match your defined schedule.
Select the naming schema or regular expression option to use for this snapshot.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema custom-%Y-%m-%d_%H-%M finds and replicates snapshots like custom-2020-03-25_09-15.
Enter multiple schemas by pressing Enter to separate each schema.
Set the replication schedule to use and define when the replication task runs.
Leave Run Automatically selected to use the snapshot task specified and start the replication immediately after the related periodic snapshot task completes.
Select Schedule to display scheduling options for this replication task, and to run the task according to its own schedule.
Selecting Schedule allows scheduling the replication to run at a separate time.
Choose a time frame that gives the replication task enough time to finish and is during a time of day when network traffic for both source and destination systems is minimal.
Use the custom scheduler (recommended) when you need to fine-tune an exact time or day for the replication.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Click Save.
Setting up Replication with SSH+NETCAT
When setting Transport to SSH+NETCAT, the replication administration user on the remote system requires passwordless sudo access for both /usr/sbin/zfs and /usr/bin/python3. The automatic SSH configuration only grants sudo rights for /usr/sbin/zfs. Without the additional python3 entry, the task fails with:
[EFAULT] Unknown SSH+NETCAT transport error: ‘sudo: a terminal is required to read the password’
First, verify the root user password is enabled on the remote TrueNAS system.
Go to Credentials > Users, select the root user, and confirm the password is not disabled and has a password set.
Next, add the required sudo entry on the remote TrueNAS system:
Log in to the remote system as root through an SSH session or use the TrueNAS Shell.
Run visudo to open the sudoers file.
Add the following line for the replication user, replacing username with the actual user:
username ALL=(ALL) NOPASSWD: /usr/bin/python3
Save and exit.
You can then create the replication task on the local system using the Add Replication Task screen.
Click Add on the Data Protection > Replication card to open the wizard, then click Advanced Replication Task to open the Add Replication Task screen.
Setting a Replication Compression Level
Options for compressing data, adding a bandwidth limit, or other data stream customizations are available.
Stream Compression options are only available when using SSH.
Before enabling Compressed WRITE Records, verify that the destination system also supports compressed write records.
Setting Block Size
Allow Blocks Larger than 128KB is a one-way toggle.
Replication tasks using large block replication only continue to work as long as this option remains enabled.
Setting Full File System Replication
By default, the replication task uses snapshots to quickly transfer data to the receiving system.
Selecting Full Filesystem Replication means the task completely replicates the chosen Source, including all dataset properties, snapshots, child datasets, and clones.
When using this option, we recommend allocating additional time for the replication task to run.
Replicating Dataset Properties
Leave Full Filesystem Replication unselected and select Include Dataset Properties to include just the dataset properties in the snapshots to replicate.
Leave this option unselected on an encrypted dataset to replicate the data to another unencrypted dataset.
Replicating Child Datasets
Select Recursive to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
Defining Replication Properties
Enter newly defined properties in Properties Override to replace existing dataset properties with the newly defined properties in the replicated files.
List any existing dataset properties to remove from the replicated files in Properties Exclude.
Saving Pending Snapshots
When a replication task is having difficulty completing, it is a good idea to select Save Pending Snapshots.
This prevents the source TrueNAS from automatically deleting any snapshots that failed to replicate to the destination system.
Changing Destination Dataset from Read-Only
By default, the destination dataset is set to be read-only after the replication completes.
You can change the Destination Dataset Read-only Policy to only start replication when the destination is read-only (set to REQUIRE) or to disable it by setting it to IGNORE.
Adding Transfer Encryption
The Encryption option adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system.
Selecting Encryption adds the additional setting options HEX key or PASSPHRASE.
You can store the encryption key either in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination and Source Snapshots
Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots.
TrueNAS also does a full replication of the source snapshots as if the replication task had not run, which can lead to excessive bandwidth consumption.
This can be a very destructive option.
Make sure that any snapshots deleted from the destination are obsolete or otherwise backed up in a different location.
Defining Snapshot Retention
Defining the Snapshot Retention Policy is generally recommended to prevent cluttering the system with obsolete snapshots.
Choosing Same as Source keeps the snapshots on the destination system for the same amount of time as the defined Snapshot Lifetime from the source system periodic snapshot task.
TrueNAS always preserves the latest snapshot so replication can resume later.
If you delete a dataset or zvol on the source, you must manually delete the replicated dataset or zvol and the most recent snapshot on the destination.
You can use Custom to define your own lifetime for snapshots on the destination system.
Replicating Snapshots Matching a Schedule
Selecting Only Replicate Snapshots Matching Schedule restricts the replication to only those snapshots created at the same time as the replication schedule.
TrueNAS replication allows users to create replicated snapshots of data stored in encrypted pools, datasets or zvols as a way to back up stored data to a remote system.
You can use encrypted datasets in a local replication.
You can set up a replication task for a dataset encrypted with a passphrase or a hex encryption key, but you must unlock the dataset before the task runs or the task fails.
With the implementation of the Local Administrator user and role-based permissions, when setting up remote replication tasks when logged in as an admin user, requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Remote replication with datasets also require an SSH connection in TrueNAS. You can use an existing SSH connection if it has the same user credentials you want to use for the new replication task.
Creating a Remote Replication Task for an Encrypted Dataset
To streamline creating simple replication tasks, use the Replication Task Wizard to create and copy ZFS snapshots to another system.
The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make changes such as assigning it a different destination, selecting other options like encryption, schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Unlock the source dataset and export the encryption key to a text editor such as Notepad.
Go to Datasets select the source dataset, locate the ZFS Encryption widget and unlock the dataset if locked.
Export the key and paste it in any text editor such as Notepad. If you set up encryption to use a passphrase, you do not need to export a key.
After the replication task runs and creates the snapshot on the destination, you must unlock the dataset to access the data.
Click the from the replication task options to download a key file that unlocks the destination dataset.
Replicating to an Unencrypted Destination Dataset
TrueNAS does not support preserving encrypted dataset properties when trying to re-encrypt an already encrypted source dataset.
To replicate an encrypted dataset to an unencrypted dataset on the remote destination system, follow the instructions above to configure the task, then to clear the dataset properties for the replication task:
Select the task on the Replication Task widget. The Edit Replication Task screen opens.
Scroll down to and select Include Dataset Properties to clear the checkbox.
This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.
Using Additional Encryption Options
When you replicate an encrypted pool or dataset, you have one level of encryption applied at the data storage level.
Use the passphrase or key created or exported from the dataset or pool to unlock the dataset on the destination server.
To add a second layer of encryption at the replication task level, select Encryption on the Replication Task Wizard or on the Add Replication Task screen, then select the type of encryption you want to apply.
Select either Hex (base-16 numeral format) or Passphrase (alphanumeric format) from the Encryption Key Format dropdown list to open settings for that type of encryption.
Selecting Hex displays Generate Encryption Key preselected. Select the checkbox to clear it and display the Encryption Key field where you can import a custom hex key.
Selecting Passphrase displays the Passphrase field where you enter your alphanumeric passphrase.
Select Store Encryption key in Sending TrueNAS database to store the encryption key in the sending TrueNAS database or leave unselected to choose a temporary location for the encryption key that decrypts replicated data.
Unlocking a Replication Encrypted Dataset or Zvol
Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase
TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.
Method 1: Construct JSON Manifest.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.
Method 2: Replicate Encrypted Dataset/zvol Without Properties.
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Method 3: Replicate Key Encrypted Dataset/zvol.
Go to Datasets on the system you are replicating from.
Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset.
Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
Network
The System > Network menu option has several screens that enable configuring network interfaces and general system-level network settings.
The tutorials in this section guide with the various screens and configuration forms contained within this menu item.
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.
Configuring Static Routes: Provides instructions on configuring a static route using the TrueNAS web UI.
Setting Up IPMI: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.
Accessing NAS from VMs and Containers: Provides instructions on how to create a bridge interface for virtual machines or applications and provides Linux and Windows examples.
Interface Configurations
TrueNAS supports configuring different types of network interfaces such as a standard interface, network bridge, LAGG, and VLAN interfaces to use as part of the various backup, sharing, and virtualization features in TrueNAS.
The tutorials in this section guide you through each of the various network interface configurations.
Why should I use different interface types?
A LAGG (Link Aggregation) optimizes multi-user performance, balances network traffic, and provides network failover protection.
In a failover, it prevents a network outage by dynamically reassigning traffic to another interface when a physical link, like a cable or NIC, fails.
A network bridge enables communication between two networks and provides a way for them to work as a single network.
Bridges can serve IP addresses to multiple VMs on one interface, which allows your VMs to be on the same network as the host.
A VLAN (virtual LAN) segments a single physical network into multiple logical networks, allowing network traffic isolation and security boundaries without requiring separate physical hardware.
VLANs provide separate traffic management for storage (iSCSI/NFS), VMs, and multi-tenant environments while improving security, reducing broadcast domains, and enabling multiple networks on a single NIC.
The Network screen shows network settings for interfaces, global network settings, adding static routes, and IPMI connections.
This article describes adding new or changing existing network interfaces.
For information on configuring IPv6 addresses, see Configuring IPv6.
You must know the DNS name server and default gateway addresses for your IP address.
Static IP or DHCP-Assigned?
By default, TrueNAS configures the primary network interface for Dynamic Host Configuration Protocol (DHCP) IP address management during installation.
However, some administrators might choose to assign a static IP address to the primary network interface.
This choice can be made if TrueNAS is deployed on a system that does not allow DHCP for security, stability, or other reasons.
In all deployments, only one interface can be set up for DHCP, which is typically the primary network interface configured during the installation process.
Any additional interfaces must be manually configured with one or more static IP addresses.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Adding an Interface
TrueNAS uses DHCP to assign an IP address to the primary network interface during installation to provide access to the web UI.
DHCP provides the IP address for only one network interface.
After initially installing TrueNAS, you can change the DHCP-assigned IP address to a static IP address by:
Logging into the UI using the DHCP-assigned IP address, and going to the Network screen and editing the interface
We recommend using the UI to make network changes as it has safeguards in place to prevent you from losing access to the system due to incorrectly configured interfaces.
To add another network interface in the UI, go to System > Network and click Add on the Interfaces widget to open the Add Interface screen.
You must specify the type of interface to create.
Select the interface type from the Type dropdown options: Bridge, Link Aggregation (LAGG), or VLAN (virtual LAN).
The interface type cannot be changed after clicking Save.
To revert the interface to default network settings, select Reset Configuration on the more_vert for the interface.
This resets the interface from a static IP address to a DHCP-assigned address and resets the domain to the TrueNAS default local.
Enter a name for the interface using the format that corresponds to the type of interface you are adding. Naming differs between physical and virtual interfaces.
The name assigned to the primary physical network interface on your system is based on the systemd predictable naming scheme, and reflects the hardware type and location. The names vary based on your hardware configuration.
For example, eno1 for onboard NICs, ens3 for PCIe slot NICs, and you might see eno1np0, which is an onboard NIC with more than one port on the NIC.
When selecting a virtual interface type, enter a name based on the type.
For example, bondX, vlanX, or brX and where X is a number.
To allow DHCP to assign the interface IP address, select Get IP address Automatically from DHCP.
To use a fixed (static) IP address, select the Define Static IP Addresses, and then click Add to the right of Static IP Addresses to show the IP address and netmask (CIDR) fields. Enter the assigned IP address and select the netmask from the dropdown list.
Click Add for each IP address you want to associate with the interface.
If adding an IPv6 IP address, refer to Configuring IPv6 for details on this type of network configuration.
Click Save when you are certain of your configuration. You cannot change the interface type or name after clicking Save!
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Editing an Interface
To change an existing interface, click on the more_vert icon at the right of the interface, and then click Edit to open the Edit Interface screen.
The Edit Interface and Add Interface screen settings are identical, but the Type and Name fields are not editable for an existing interface.
If you created the wrong type of virtual interface (i.e., a bridge, vlan, lagg), delete the interface and add a new interface with the correct type.
When changing from a DHCP-provided IP address to a static IP, first verify your current default gateway and name servers work with the new IP address.
You must add the new default gateway and DNS name servers that work with the new IP address to the global configuration.
If you need to change these settings, do this before you change the interface so you can test the interface change.
Click Save after making all changes.
Test the change as described above in Testing Network Interface Changes.
Resetting an Interface Configuration
Resetting the configuration for a network interface can result in lost access to the TrueNAS UI and losing the connection to TrueNAS!
Clicking Reset Configuration resets the domain name back to the default value, and changes the static IP address to DHCP-assigned.
When saved, changes cause lost access to the UI. You might need command line knowledge, and either IPMI or physical access to the TrueNAS system to fix misconfigured network settings.
If using IPMI or a physical connect to the system, you can change network and interface settings through the Console Setup menu.
The TrueNAS UI does not offer a way to delete the interface. Do not delete the primary network interface in the CLI!
Click on the more_vert dropdown list for the interface, then select Reset Configuration.
The current IP address resets to a DHCP-assigned IP address and the domain name reverts to the default setting.
Confirm validates the reset activity and activates the Reset button.
Reset clears the configuration for that interface.
After making the changes and clicking Save, the test change options show on the Network screen.
Follow the procedure above to test your changes and validate you still have access to the UI and the TrueNAS system.
Changing from DHCP to a Static IP Address
TrueNAS allows assigning static IP addresses to an interface when not using a DHCP-assigned address.
Static IP addresses set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access.
You can add an additional IP address for a network interface configured with another primary IP address.
Verify the default gateway and nameservers for the DHCP-assigned address and new static IP address are the same before making a change.
If not the same, edit the global network settings before changing the interface so you can properly test the change.
Changing the Global Network Settings
Go to System > Network:
Check the name servers and default router information in the Global Information widget.
If the current settings are not on the same network, click Settings and modify each setting as needed to allow the static IP to communicate over the network.
Enter the IP addresses for the DNS name servers in the Primary, Secondary, and the optional Tertiary fields.
For home users, enter 8.8.8.8 for a DNS name server address so you can communicate with external networks.
Enter the IP address for the default gateway in the appropriate field.
If the static network is IPv4 enter the gateway in IPv4 Default Gateway, if the static network is IPv6 use IPv6 Default Gateway.
Click Save.
If in an IPMI session, you can use the Console Setup menu to change settings.
Enter 2 to configure general network settings like the default gateway and name servers.
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (LAGG) or network bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
To use the UI to change an interface from DHCP to a static IP address, go to System > Network:
Verify the default gateway and name servers work with the new static IP address.
If not, click the link above and follow the instructions to update the global network settings.
Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Click Add to the right of Static IP Addresses to show the IP address and netmask (CIDR) fields.
Click Add for each static IP address you want to add to this interface.
Enter the IP address and select the netmask value for each static address you add.
Multiple interfaces cannot be members of the same subnet!
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (LAGG) or network bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
If an error displays or the Save button remains inactive when setting the IP addresses on multiple interfaces, check the subnet and ensure the netmask (CIDR) numbers are different.
Click Save.
Click Test Changes when prompted. Follow the procedure above to test network changes.
Returning to a DHCP-Assigned IP Address
Only one interface can use DHCP to assign the IP address and that is likely the primary network interface.
If you do not have an existing network interface set to use DHCP you can convert an interface from static IP to DHCP.
To switch back to using DHCP:
Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Select Get IP Address Automatically from DHCP.
Click Save.
Verify the current default gateway and name servers work with the new DHCP-assigned IP address.
If yes, test the network change. Click on 60 above the Test Changes button to extend the number of seconds you have to test the network change.
If the current settings do not work with the new DHCP-assigned IP address, click the link in the Changing from DHCP to a static IP Address section, and follow the directions to change these settings.
If the test network operation fails or the system times out, your system returns to the network settings before you attempted the change.
Edit the global network settings and click save, then edit the interface and click save. Test the network changes again.
In general, a bridge refers to various methods of combining (aggregating) multiple network connections into a single aggregate network.
TrueNAS uses bridge(4) as the kernel bridge driver.
Bridge(8) is a command for configuring the bridge in Linux.
While the examples focus on the deprecated brctl(8) from the bridge-utilities package, we use ip(8) and bridge(8) from iproute2 instead.
Refer to the FAQ section that covers bridging topics more generally.
Network bridging does not inherently aggregate bandwidth like link aggregation (LAGG).
Bridging is often used for scenarios that require extending a network segment or combining different types of network traffic.
You can use bridging to integrate different types of networks (e.g., wireless and wired networks) or to segment traffic within the same network.
You can also use a bridge to allow a VM, container, or app configured on TrueNAS to communicate with the host system.
See Accessing NAS from Containers for more information.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a Bridge
To set up a bridge interface:
Go to Apps and the Containers screens to verify all apps and containers are stopped.
If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM.
Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Click the more_vert icon for the interface, to open the Edit Interface screen.
Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
a. Set Type to Bridge. Name automatically populates with the correct name.
You cannot change the Type field value or the name after clicking Save!
b. (Optional) Enter a short description for the bridge. This is optional but recommended if configuring multiple bridges on your system to help identify their use or location.
c. Select Define Static IP Addresses, then click Add to the right of Static IP Addresses.
Enter the IP address and select the netmask for the interface edited in step 4 above. Refer to the screenshot if you do not remember the IP address and netmask.
d. Select the interface name in Bridge Members. You only need to add the interface name edited in step 4 above.
Leave Enable Learning selected for normal use. With learning enabled, the bridge learns which MAC addresses are reachable through each member and sends traffic only to the relevant member. Without learning, the bridge floods all traffic to every member instead. Disable this option only when a bridge member might not be available at startup, to prevent the bridge from learning incorrect addresses before all members are up.
See Bridge Settings for details on both settings.
e. Click Save.
TrueNAS shows the bridge on the Interfaces widget.
Click Test Changes. See Testing Network Changes above for details on testing and saving network changes.
TrueNAS shows the bridge as working.
Troubleshooting Network Changes
Occasionally, a misconfigured bridge or a conflict with a running application, VM, or service can cause the network changes test to fail.
Typically, this is because the bridge is configured using an IP address that is already in use.
If the system does not receive a Save Changes check-in before the test times out (default 60 seconds), TrueNAS automatically reverts all unsaved changes.
The following troubleshooting options are available if you cannot save the new bridge and network changes.
Options are ordered from the least to the most disruptive.
Try options one and two before proceeding with options three and four.
Ensure that there are no currently running applications.
Stop any running VMs.
(Optional) Go to Services.
Click editConfigure to view the current configuration of sharing services, including SMB and NFS.
Stop any services that have a bind IP address matching the bridge IP address.
Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.
Setting Up a Link Aggregation
In general, a link aggregation (LAGG) is a method of combining (aggregating) multiple network connections in parallel to provide additional bandwidth or redundancy for critical networking situations.
TrueNAS uses lagg(4) to manage LAGGs.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
If configuring an LACP link aggregation, configure a port-channel or link aggregation group on your network switch before creating the LAGG interface in TrueNAS.
The switch ports connected to your TrueNAS interfaces must be configured for LACP (IEEE 802.3ad) and active before TrueNAS can successfully negotiate the link aggregation.
Consult your switch documentation for specific configuration steps.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a Link Aggregation Interface
To set up a LAGG, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select Link Aggregation from the Type dropdown list. You cannot change the Type field value after you click Save.
In LACP mode, the interfaces negotiate with the network switch to form a group of ports that are all active at once.
The network switch must support LACP for this option to function.
a. Select the hash policy from the Transmit Hash Policy dropdown list. LAYER2+3 is the default selection.
b. Select the LACPDU Rate options are Slow or Fast.
SLOW (default) sets the heartbeat request to every second and the timeout to a three-consecutive heartbeat loss that is three seconds.
FAST sets the timeout rate at one per second, even after synchronization. FAST allows for rapid detection of faults.
FAILOVER
TrueNAS Enterprise
TrueNAS Support strongly discourages using the FAILOVER protocol setting when configuring Link Aggregation (bond) interfaces in HA systems.
Using this setting in HA systems might delay moving the virtual IP address from one controller to the other during a failover, causing network access delays.
Additionally, TrueNAS does not allow marking a bond interface in HA systems as Critical when the FAILOVER protocol is used but it is allowed in non-HA systems.
Select FAILOVER to send traffic through the primary interface of the group. If the primary interface fails, traffic diverts to the next available interface in the bond group.
LOADBALANCE
Select LOADBALANCE to accept traffic on any port of the LAGG group and balance the outgoing traffic on the active ports in the LAGG group.
LOADBALANCE is a static setup that does not monitor the link state or negotiate with the switch.
Select the Transmit Hash Policy option from the dropdown list. LAYER2+3 is the default selection.
Select the interfaces to use in the aggregation from the Link Aggregation Interface dropdown list.
(Optional) Click Add to the right of Static IP Addresses to show additional IP address fields for each additional IP address to add to this LAGG interface.
Click Save when finished.
Test the network change when prompted.
Setting Up a Network VLAN
A virtual LAN (VLAN) is a partitioned and isolated domain in a computer network at the data link layer (OSI layer 2).
Click here for more information on VLANs.
Before you begin, make sure you have an Ethernet card connected to a switch port and configured for your VLAN.
Ensure that you have also preconfigured the VLAN tag in the switched network.
Consult with your IT department to obtain this VLAN tag if you are not the network administrator for your systems.
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a VLAN Interface
To set up a VLAN interface, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select VLAN from the Type dropdown list. You cannot change the Type field value after clicking Apply.
Name populates with the default name vlan1. You cannot change the Name of the interface after clicking Save.
Leave Define Static IP Addresses selected under DHCP.
(Optional, but recommended) Enter any notes or reminders about this VLAN in Description.
Select the interface in the Parent Interface dropdown list. This is typically an Ethernet card connected to a switch port already configured for the VLAN.
Enter the numeric tag for the interface in the VLAN Tag field. This is typically preconfigured in the switched network.
Select the VLAN Class of Service from the Priority Code Point dropdown list.
(Optional) Click Add to the right of Aliases to show additional IP address fields for each additional IP address to add to this VLAN interface.
Click Save.
Test the network change when prompted.
Managing Network Configurations
Use the Network Configuration Settings widget shows existing general network settings like the default gateway and DNS servers, set services allowed to externally communicate, enter an HTTP proxy, or host name database.
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Do not configure network settings to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers.
This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started.
Can I configure these options elsewhere?
Users can configure many of the interface, DNS, and gateway options using the Console Setup menu.
Be sure to check both locations when troubleshooting network connectivity issues.
Adding Network Settings
Use the Network Configuration widget to add general network settings like the default gateway and DNS name servers to allow external communication.
Go to System > Network, and click Settings on the Network Configuration widget to open the Edit Global Configuration screen.
Enter the host name for your TrueNAS in Hostname. For example, replace the default value truenas with something like localnas.
If you plan to use Active Directory or SMB services, the hostname is also used as the NetBIOS name and must comply with NetBIOS naming restrictions: maximum 15 characters, cannot contain \ / : * ? " < > |, and cannot use Microsoft or RFC 852 reserved words (ANONYMOUS, AUTHENTICATED USER, BATCH, BUILTIN, DIALUP, DOMAIN, ENTERPRISE, INTERACTIVE, INTERNET, LOCAL, NETWORK, NULL, PROXY, RESTRICTED, SELF, SERVER, USERS, WORLD, GATEWAY, GW, TAC). TrueNAS 25.04 and later enforce these restrictions through validation.
Enter the system domain name in Domain. For example, replace the default local with example.com.
Enter the IP addresses for your DNS name servers in Primary, Secondary, and/or Tertiary.
For home users, enter 8.8.8.8 in the Primary field so your TrueNAS can communicate externally with the Internet.
Enter the IP address for your default gateway into the IPv4 Default Gateway if you are using IPv4 IP addresses.
Enter the IPv6 address in the IPv6 Default Gateway if you are using IPv6 addresses.
Select the desired Outbound Network option.
Selecting Allow All permits all services to communicate externally.
Selecting Deny All prevents services from communicating externally.
Selecting Allow Specific shows a dropdown list of services that you can choose to allow to communicate externally.
Services not selected cannot communicate externally.
Selecting Allow All Except shows the same dropdown list of services that you can choose to deny the ability to communicate externally.
Services not selected for this option are allowed external communication
Click Save. The Network Configuration widget on the Network screen shows the new settings.
Configuring IPv6
TrueNAS provides the option to configure network interfaces using either IPv4 or IPv6 addresses.
IPv4 networks cannot see or communicate with an IPv6 website or network unless a gateway or some other implementation is configured to allow it.
See Understanding IPv6 for more information.
Configuring IPv6 Addresses
After configuring your network infrastructure for IPv6, assign the IP addresses for your TrueNAS system.
Use the TrueNAS UI to configure your network settings.
If setting TrueNAS up for the first time after a clean install, use the Console Setup menu to enter IPv6 addresses.
Configuring an Interface Using the Console Setup Menu
If configuring your network settings using the Console Setup menu for the first time after installing TrueNAS, first configure the interface address.
Type 1, then press Enter.
Enter eno1 in name, then the IPv6 address in aliases.
Save, then select a to apply and p to make it persist. Type q to return to the Console Setup menu.
Next, configure the IPv6 gateway address, and the nameserver addresses. Type 2, then press Enter.
Enter the name server addresses provided by your IT department or Internet Service Provider (ISP), and then the gateways.
Save, then select a to apply and p to make it persist.
Adding an IPv6 Interface in the UI
Navigate to System > Network screen to enter your network settings.
Click on Add in the Interfaces to open the Add Interface screen.
Enter en8s0 as the name for the interface if it is the primary interface.
Clear the DHCP checkbox, then select Autoconfigure IPv6 if you want to create the IP address using SLAAC.
This automatically configures the IPv6 address.
You can only use this option one time to configure an IPv6 address for the system.
Enter the IPv6 address assigned to the NIC port if using a fixed IP address assignment.
Click Save
Test the change.
If adding the primary interface test the network connection by opening a new browser window.
Enter the IPv6 address inside square brackets in the URL address field, for example, [ipv6 address].
After the system comes up, save the changes to the network interface.
To access the UI after configuring an IPv6 address, enter the IPv6 address inside square brackets in the browser URL field.
You cannot access the UI with the assigned host name when the system is configured on an IPv6 network.
Configuring Dual Stacking
TrueNAS supports dual-stacking IPv4 and IPv6 addresses in the same interface.
An IPv4 network cannot see or communicate with an IPv6 network unless some gateway is configured to allow IPv6 communication.
Dual stacking these two protocols allows TrueNAS to see and communicate with an all IPv6 address or website.
You must have IPv6 configured in your networking infrastructure.
Add IPv6 to your network router to permit the incoming and outgoing traffic. This provides the required gateway to permit communication with this IP protocol.
Assign a static IPv6 address and netmask, the network gateway address, and name servers to configure in TrueNAS.
When configuring dual stacking, the order in which you configure the two network IP protocols does not matter.
If IPv4 networking is already configured in TrueNAS, to set up dual stacking of IPv6 in the UI, go to System > Network:
Add the IPv6 gateway information.
Click Settings on the Global Configuration widget to open the Edit Global Configuration screen.
Enter the IPv6 address for the gateway in IPv6 Default Gateway.
Click Save.
Add the IPv6 static IP address to the primary interface.
Select the primary interface, en8s0, then click Edit.
Click Add* to the right of Aliases to add another set of IP Address fields.
Enter the IPv6 address, then select the netmask.
Click Save
Test the network change.
To verify the IPv6 address, in a new browser window, enter the address inside square brackets. For example, [ffff:ff:59f8:100::12].
Log into the UI, and click Save Changes.
Log out of that browser session, return to your other UI session.
Both IPv4 and IPv6 addresses should show on the screen for the primary interface.
After installing TrueNAS and using the Console Setup menu to configure system networking and set up dual stacking, add the name servers and both IP protocol default gateways in general network settings (option 2 on the menu), then add both IP address, with netmasks as aliases, on the primary network interface (option 1 on the menu).
If using the Console Setup menu to set up IPv6 on an already IPv4-configured system, add the v6 default gateway in general network, then add the IPv6 IP address with netmask as an alias on the primary interface.
Connecting to the UI IPv6 Address
Unlike IPv4, you must enter the IPv6 address with a square bracket preceding and following the address.
You cannot enter the host name assigned to the TrueNAS system to access the UI.
For example, enter [ffff:ff:59f8:100::12] into the URL field of the browser window to access the UI.
Using IPv6 with Sharing Protocols
When configuring an SMB or NFS share, first configure the bind address in the share service.
Next, configure the share user, and add the share and dataset.
Finally, add the share owner to the dataset permissions.
Go to System > Services click Advanced Options then edit the share service.
For SMB, scroll down and select the IPv6 address as the Bind IP Address and click Save.
For NFS, also select the IPv6 address in Bind IP Addresses.
Select Allow non-root mount, then click Save.
Go to Credentials > Local User to create the share user.
Modify the ACL permissions.
Either click on Edit Filesystem ACL on the Shares screen or go to Datasets, select the dataset row, scroll down and click Edit on the Permissions widget.
Leave the dataset permissions @owner and @group set to root or change them to the admin user.
Next click Add New to create a new ACL entry for the share user(s).
See Setting Up Permissions for more information on adding new entries and modifying dataset permissions.
To mount or access the share in Windows, you must enter the share information using a particular syntax or it cannot find nor connect to the share.
The syntax requires you to replace each colon (:) in the IPv6 address with a dash (-).
Enter two forward slashes, followed by the IPv6 address with .ipv6-literal.net after it, then enter another forward slash, and finally the share name.
For example, \\ffff-ff-59f8-100–12.ipv6-literal.net\v6smbshare.
Configuring an SSH Connection
Both replication to a remote server and rsync tasks require configuring an SSH connection credential.
When both systems are using IPv6 addresses and the protocol to communicate, you must enclose the IPv6 address in square brackets when defining the remote system URL in the TrueNAS URL field on the New SSH Connection configuration screen.
Managing Network Settings (Enterprise HA)
TrueNAS Enterprise
The instructions in the article only apply to TrueNAS Enterprise (HA) systems.
Configuring Enterprise (HA) Network Settings
Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready, click Sync to Peer to haveTrueNAS apply settings to controller 2.
TrueNAS Enterprise (HA) systems use three static IP addresses for access to the UI:
VIP to provide UI access regardless of which controller is active.
If your system fails over from controller 1 to 2, then fails back over to controller 1 later you might not know which controller is active.
IP for controller 1. Do not use DHCP to assign the IP address! If enabled, DHCP assigns an IP to the primary network interface on non-HA systems.
Disable DHCP, and then manually enter the Controller 1 static IP address your network administrator assigned for this controller.
IP for Controller 2. Manually enter the second IP address assigned for this controller.
Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.
TrueNAS safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes.
This is to prevent users from breaking their network connection in TrueNAS.
TrueNAS Enterprise
TrueNAS Support strongly discourages using the FAILOVER protocol setting when configuring Link Aggregation (bond) interfaces in HA systems.
Using this setting in HA systems might delay moving the virtual IP address from one controller to the other during a failover, causing network access delays.
Additionally, TrueNAS does not allow marking a bond interface in HA systems as Critical when the FAILOVER protocol is used but it is allowed in non-HA systems.
To configure network settings on controller 1:
Disable the failover service.
Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to clear the checkmark, then select Default TruNAS Controller to enable it, and then click Save to disable failover.
Go to System > Network and click Settings to edit the global network settings.
Add the controller and virtual host names and update any other network settings.
Edit the primary network interface to add failover settings.
Click on the more_vert to the right of the the primary interface eno1, and select Edit to open the Edit Interface screen for this interface.
a. Turn DHCP off if it is on by selecting Define Static Ip Addresses. Click Add to show IP address fields for each interface.
Enter the IP address assigned to controller 1 in IP Address (TrueNAS Controller 1), the IP address assigned to controller 2 in IP Address (This Controller), and the IP address assigned as the virtual IP in Virtual IP Address (Failover Address).
If Define Static IP Addresses is already selected, verify the three static IP addresses assigned to the system show in the correct fields.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
b. Add the failover settings. Select 1 on the Failover Group dropdown list.
Click Test Changes after editing the interface settings. Open a new browser window and enter the VIP IP address to access the web UI.
Go to System > Network and click Save Changes to make the changes permanent.
You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Enable failover. Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to re-enable failover, then click save.
Turn failover back on.
Go to System > Failover and select Disable Failover to clear the checkmark and turn failover back on, then click Save.
The system might restart.
Monitor the status of controller 2 and wait until the controller is back up and running, then click Sync To Peer.
Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation.
The controller restarts, and TrueNAS syncs controller 2 with controller 1, which adds the network settings and pool to controller 2.
TrueNAS does not pre-define static routes by default, but TrueNAS administrators can manually add static routes if they want or need to enter routes to a router to send packets to a destination network.
Static routes are not aliases, they are fixed IP addresses assigned as alternative routes for network traffic sent to a specific destination (server, device) in the network.
You can use the Console Setup menu during installation or any time after the initial system configuration to add a static route through an SSH session or by connecting a monitor and keyboard to the system, but we recommend using the web UI to make changes to the network configuration.
We recommend using the TrueNAS web UI to make network changes because it includes safeguards that prevent breaking access to the UI or connections to TrueNAS that can result from incorrectly configured network settings.
If you need a static route to reach portions of the network:
Go to System > Network and click Add on the Static Routes widget.
Enter an IP address and netmask (CIDR) for the destination in the format A.B.C.D/E where E is the CIDR mask in Destination.
Enter the default gateway IP address for the destination address in Gateway.
(Optional) Enter a brief description for this static route, such as the part of the network it reaches.
Click Save.
Setting Up IPMI
IPMI requires a compatible motherboard with IPMI support.
Refer to your hardware documentation to determine compatibility.
Many TrueNAS systems include a built-in out-of-band management port, enabling system access even when the web interface is unavailable.
Intelligent Platform Management Interface (IPMI) allows users to check the log, access the BIOS setup, and boot the system without physical access.
IPMI also enables users to remotely access the system to assist with configuration or troubleshooting issues.
The IPMI widget on the Network screen shows the available IPMI channels and gives access to IPMI configuration and event logs.
On TrueNAS Enterprise High Availability (HA) systems, the IPMI configuration screen includes a Remote Controller section that allows you to select which controller to configure.
Select the controller you want to configure IPMI settings for or use the identify light feature on.
All IPMI configuration changes and the identify light feature apply only to the selected controller.
To configure a static IPv4 connection for IPMI, do not select DHCP.
Enter the IPv4 address for the IPMI web interface.
Enter the IPv4 address subnet mask in IPv4 Netmask, such as 255.255.240.0.
Enter the IPv4 connection default gateway.
If needed, enter the VLAN identifier of the IPMI interface in VLAN ID.
We recommend configuring IPMI on a separate VLAN that is isolated from the main TrueNAS network.
This allows for IPMI access even if the main network is down.
Click Save to update IPMI configuration.
After saving the configuration, access the IPMI interface using a web browser and the IP address specified in Network > IPMI or click to open the IPMI manager in a new browser tab.
The management interface prompts for login credentials.
IPMI utility appearance and available functions vary by hardware.
Refer to your IPMI device documentation to learn the default administrator account credentials.
After logging in to the management interface, change the default administrative user name.
We recommend setting a strong IPMI password.
Refer to your IPMI device documentation for password requirements.
Document your password in a secure location.
Alternately, enter a new password in IPMI Password Reset on the IPMI configuration screen.
IPMI Alerts
Click Show Events on the IPMI widget to show the IPMI Events log.
Use the Alert Settings Screen under the Hardware category to adjust IPMI alerts.
Configure the minimum warning level and frequency to display IPMI alerts in the TrueNAS UI.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Accessing NAS from VMs and Containers
If you want to access your TrueNAS directories from within a virtual machine or container hosted on the system, you have multiple options:
Allow TrueNAS to create an automatic bridge (default).
Manually create a bridge interface if you have only one physical interface.
Assign a NIC other than the primary one your TrueNAS server use if you have more than one physical interface.
This method makes communication more flexible but does not offer the potential speed benefits of a bridge.
Containers allow you to configure a MACVLAN NIC, which creates a virtual interface based on an existing physical one.
The assigned unique MAC address allows the instance to appear as a separate device on the network.
A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host.
MACVLAN sends traffic directly to the external network without passing through the host network stack.
The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.
Using Default Network Settings
Leave Use default network settings selected while creating a new instance to allow TrueNAS to automatically assign the default network bridge.
This is the simplest way to allow communication between containers and the TrueNAS host.
If your system only has a single physical interface, and you prefer to manually configure a network bridge, complete these steps.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Adding a Bridge
To set up a bridge interface:
Go to Apps and the Containers screens to verify all apps and containers are stopped.
If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM.
Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Click the more_vert icon for the interface, to open the Edit Interface screen.
Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
a. Set Type to Bridge. Name automatically populates with the correct name.
You cannot change the Type field value or the name after clicking Save!
b. (Optional) Enter a short description for the bridge. This is optional but recommended if configuring multiple bridges on your system to help identify their use or location.
c. Select Define Static IP Addresses, then click Add to the right of Static IP Addresses.
Enter the IP address and select the netmask for the interface edited in step 4 above. Refer to the screenshot if you do not remember the IP address and netmask.
d. Select the interface name in Bridge Members. You only need to add the interface name edited in step 4 above.
Leave Enable Learning selected for normal use. With learning enabled, the bridge learns which MAC addresses are reachable through each member and sends traffic only to the relevant member. Without learning, the bridge floods all traffic to every member instead. Disable this option only when a bridge member might not be available at startup, to prevent the bridge from learning incorrect addresses before all members are up.
See Bridge Settings for details on both settings.
e. Click Save.
TrueNAS shows the bridge on the Interfaces widget.
Click Test Changes. See Testing Network Changes above for details on testing and saving network changes.
TrueNAS shows the bridge as working.
Troubleshooting Network Changes
Occasionally, a misconfigured bridge or a conflict with a running application, VM, or service can cause the network changes test to fail.
Typically, this is because the bridge is configured using an IP address that is already in use.
If the system does not receive a Save Changes check-in before the test times out (default 60 seconds), TrueNAS automatically reverts all unsaved changes.
The following troubleshooting options are available if you cannot save the new bridge and network changes.
Options are ordered from the least to the most disruptive.
Try options one and two before proceeding with options three and four.
Ensure that there are no currently running applications.
Stop any running VMs.
(Optional) Go to Services.
Click editConfigure to view the current configuration of sharing services, including SMB and NFS.
Stop any services that have a bind IP address matching the bridge IP address.
Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.
After adding the bridge and to assign the bridge to a VM or container, go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget.
Click Add and select the new bridge interface from the dropdown list.
You can now access your TrueNAS storage from the container.
You might have to set up shares or users with home directories to access certain files.
Assigning a Secondary NIC: Multiple Physical Interfaces
If you have more than one NIC on your system, you can assign container traffic to a secondary NIC.
Configure the secondary interface as described in Managing Interfaces before attaching it to an instance.
If you are creating a new instance, use the Network settings to disable Use default network Settings and select the secondary NIC from Macvlan NICs.
TrueNAS Credential options are collected in this section of the UI and organized into a few different screens:
Users allows those with permissions to add, configure, and delete users on the system.
There are options to search for keywords in usernames, view or edit user characteristics, and a dropdown to select whether the screen shows built-in, local, and/or directory services users.
Groups allows those with permissions to add, configure, and delete user groups on the system.
There are options to search for keywords in group names, display or hide group characteristics, and toggle whether the screen shows built-in groups.
Directory Services contains options to edit directory domain and account settings, set up Idmapping, and configure access and authentication protocols.
Specific options include configuring Kerberos realms and key tables (keytab), as well as setting up LDAP validation.
Backup Credentials stores credentials for cloud backup services, SSH Connections, and SSH Keypairs.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
Certificates contains all the information for certificates, certificate signing requests, certificate authorities, and DNS-authenticators.
TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
2FA allows users to set up Two-Factor Authentication for their system.
Users can set up 2FA, then link the system to an authenticator app (such as Google Authenticator, LastPass Authenticator, etc.) on a mobile device.
Contents
Using Administrator Logins: Explains role-based administrator logins and functions. Provides instructions on configuring SSH and working with the admin and root user passwords.
Managing Users: Provides instructions on adding and managing administrator and user accounts.
Managing Groups: Provides instructions on adding and managing groups.
Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.
Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.
Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.
Backup Credentials: Backup credential tutorials for integrating TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Adding Cloud Credentials: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.
Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.
Certificates: Information about adding and managing certificates, CSRs, CAs, and ACME DNS-Authenticators in TrueNAS.
Managing Certificates: Provides information on adding or managing certificates in TrueNAS.
Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.
Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.
Using Administrator Logins
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
Administrator accounts have roles and privileges that are FIPS compliant and allow more control over access to TrueNAS functions.
TrueNAS has three predefined admin user account levels:
Full Admin - Assigned to the local administrator account created by the system when clean installing TrueNAS using an iso file.
Also assigned when manually creating an admin user if logged in as the root user account after upgrading from a pre-22.12.3 release of TrueNAS or migrating from FreeBSD- to Linux-based TrueNAS releases.
Sharing Admin - Assigned to users responsible for only managing shares (SMB, NFS, iSCSI).
This user can create shares and the datasets for shares, start/restart the share service, and modify the ACL for the share dataset.
Readonly Admin - Assigned to users that can monitor the system but not make changes to settings.
For more information on the different administrator scenarios users can encounter, read Logging In for the First Time.
Changing Administrator Account Passwords
Administrator passwords can be changed on the Edit User screen or, if currently logged in as that admin user, by clicking the Settingsaccount_circle icon on the top toolbar and clicking Change Password.
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.
Use the Privileges dropdown to select assign permissions as Local Administrator to allow full administrative access or select Read-Only Administrator or Sharing Administrator to limit permissions.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
Click Save.
After creating a new group, click groupMembers to open the Update Members screen and assign one or more administrative user accounts to the group.
Click Save.
Log out of the TrueNAS system and then log back in using the new user credentials to verify that the admin credentials work properly with your network configuration.
The root account group membership cannot be modified and is permanently assigned to the builtin_administrators group (gid 544).
This restriction prevents accidental removal of required privileges that could cause system functions like scheduled tasks, cloud sync operations, and cron jobs to fail.
To disable root account access to the TrueNAS UI while maintaining proper system functionality, use the Disable Password option in Credentials > Local Users instead of modifying group membership.
Allowing Sudo Commands
As a security hardening feature, administrator accounts in Linux-based TrueNAS releases (22.12.0 or newer) cannot execute certain root-level commands in a shell or SSH session by default.
If a user attempts to execute one of these commands without root-level access, TrueNAS returns a command not found error.
Administrative users who need to execute root-level commands to complete a task should temporarily enable sudo permissions for that user by going to Credentials and editing the user or group to allow some or all sudo commands.
For best security, enable only the required commands to perform the task and require password authentication, unless the task or app prevents it.
Disable sudo permissions when the task completes and you no longer need them.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password, and Allow all sudo commands with no password, on the Add Group and Edit Group screens, grant limited root-like permissions using the sudo command.
Use Allowed sudo commands or Allowed sudo commands with no password to list specific sudo commands to allow.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press Enter after each command.
To allow full access to sudo commands, select either Allow all sudo commands or Allow all sudo commands with no password.
If you allow sudo commands with password protection, TrueNAS prompts you for a password the first time you enter a sudo command, but not again in the same session.
Disable these settings after completing the task to return to a security-hardened system.
Do not allow sudo permissions for read-only administrators.
Disabling Root and Admin User Passwords
As a security measure, the root user is no longer the default account and TrueNAS disables the root password when you create the truenas_admin or admin user during installation.
Do not disable the default admin account, root, and any custom admin account passwords at the same time.
If all root and administrator account passwords become disabled at the same time and the web interface session times out, a one-time sign-in screen allows access to the system.
Enter and confirm a password to gain access to the UI.
After logging in, immediately go to Credentials > Users to enable the password for an administrator account before the session times out again.
TrueNAS does not save the temporary password as a new password or enable the admin or root passwords. It only provides one-time access to the UI.
Disabling a password for UI login also disables it for SSH access.
Accessing the System Through an SSH Session
To enable SSH access to the system as an admin user (or root user), you must first configure the SSH service.
Go to System > Services, then click Edit for the SSH service.
Enter the groups (truenas_admin, root, etc.) you want to enable for password authentication in the Password Login Groups field.
Enable Allow Password Authentication.
Click Save and restart the SSH service.
Now you must verify the user configuration options to allow SSH access.
Using the Root User in SSH
If you want to SSH into the system as the root:
Go to Credentials > Users and click the root user, then click Edit.
Make sure Disable Password is disabled. If the root user has Disable Password enabled, you cannot use it to gain SSH access to the system.
Click Save.
Allowing an Admin User to Enter Commands in SSH
To allow an admin user to issue commands in an SSH session:
Go to Credentials > Users, click the admin user, then click Edit.
Select SSH Access.
Enable SSH password login enabled under Authentication.
Click Save.
Disable this after completing the SSH session to return to a security-hardened system.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
Two-Factor Authentication (2FA) and Administrator Account Log In
To use two-factor authentication with an administrator account, configure and enable SSH service to allow SSH access, then configure two-factor authentication.
If you have the root user configured with a password and it is enabled, you can SSH into the system as the root user.
Disable the root user password and only use a local administrator account for more security.
Allowing Directory Service Users WebUI Access
TrueNAS Enterprise
Enterprise-licensed systems include the Allow Directory Service users to access WebUI option on the System > Advanced Settings > Access Settings configuration screen.
To configure this access, first add the selected AD users to a group that is granted a TrueNAS privilege that permits it, then enable the Allow Directory Service users to access WebUI option on the Access Settings screen. This option only shows on Enterprise-licensed systems.
After TrueNAS joins AD, it automatically creates a new privilege entry in the Privileges screen table, and this privilege is automatically populated with the domain admins group for the domain.
For example, if the domain is ad03.mydomain.net, then you should see a group of that name listed as well as any of the groups AD creates on the system.
You can edit this privilege by selecting the table row and clicking Edit.
Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges are:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/exeute permissions) to the user.
Administrator Logins and TrueCommand
Administrator logins work with TrueCommand, but you need to set up the TrueNAS connection using an API key.
Managing Users
In TrueNAS, user accounts allow flexibility for accessing shared data.
Typically, administrators create users and assign them to groups.
Doing so makes tuning permissions for large numbers of users more efficient.
When the network uses a directory service, import the existing account information using the instructions in Directory Services.
Using Active Directory requires setting Windows user passwords in Windows.
TrueNAS hides all built-in users (except root) by default.
Click the down arrow in the Filter by Type dropdown field to see all user options, including Built-In, Local (default option), and Directory Services.
You can select any or all options to show all users configured in TrueNAS.
To filter the user table, click the header column name to sort in ascending/descending order. You can also use the advanced search option to select the search criteria you want to use for a user or type of user.
Creating an Administrator User Account
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
Assigning Administrative Group Privileges
TrueNAS 24.04 or newer supports administrator privileges for role-based administrator accounts.
Users can create new administrator accounts with limited privileges based on their needs.
Predefined administrator roles are read-only, share admin, and the default full access administrator account.
See Using Administrator Logins for more information.
Go to Credentials > Groups and select the row for primary group of the admin user to expand it.
Click editEdit.
Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.
Use the Privileges dropdown to select assign permissions as Local Administrator to allow full administrative access or select Read-Only Administrator or Sharing Administrator to limit permissions.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
Click Save.
After creating a new group, click groupMembers to open the Update Members screen and assign one or more administrative user accounts to the group.
Click Save.
Log out of the TrueNAS system and then log back in using the new user credentials to verify that the admin credentials work properly with your network configuration.
Creating User Accounts
User Access Levels
Users are assigned different access levels by TrueNAS administrators. All user accounts are assigned access levels based on their roles or system privileges.
All users are assigned the SMB Access by default.
SMB Access is the default user access type that allows using the account credentials to access data shared with SMB.
TrueNAS requires other options based on the level of access
TrueNAS Access shows the predefined roles available in TrueNAS. Assigning TrueNAS Access requires setting one of the options or roles: Full Admin, Readonly Admin, or Sharing Admin.
Some administration users require access to the TrueNAS shell or might require access using an SSH session.
These users must be assigned the Shell option and or the SSH Access options.
If a user only requires access to the TrueNAS Shell screen, assign the user Shell Access.
If the user requires SSH session access, assign the SSH Access to the user. This provides access to the Shell screen and an SSH session.
SSH Access requires adding an SSH keypair to TrueNAS, and then copying the public key into the Add User or Edit User screen.
Turn on the SSH service before establishing an SSH session, and then turn it off when access is no longer required to maintain a security-hardened system.
When creating a user, you must:
Enter a value in Full Name or description for the user, such as a first and last name.
Enter a value in Username.
Enter a value in Password and confirm that password.
Specify or accept the default user ID (UID)
To manually add a new user, click Credentials > Users, and then click Add to open the Add User screen.
Enter a username for the user. Names are case sensitive!
Set the level of access given to this user.
SMB Access is selected by default, and required for a user to have access to an SMB share.
Select TrueNAS Access and then the administration role from the dropdown list that shows after selecting the TrueNAS Access option.
To create an administrator with full access, select Full Admin.
To create an administrator with access to manage shares, select Sharing Admin.
To create an administrator with read-only access, select Readonly Admin.
To allow the user to access the Shell in the UI, select Shell Access.
To allow the user to establish an SSH session with the system, select SSH Access.
Selecting this option also selects the Shell Access option by default.
To limit the user to only Shell access, do not select the SSH Access option.
Enter a password for the user, and confirm it.
Setting Up SSH Access.
These options only show when you select the SSH Access option. Only Full Admin users who require SSH session access should be configured with this option.
Select the optional Allow SSH Login with Password if you want to allow this user to log in to an SSH session and not be prompted to enter a password.
This is not recommended as it presents a security vulnerability!
Manually enter or copy/paste the public key in the Public SSH Key field to assign a public SSH key to the user for key-based authentication.
Do not enter the private key!
After adding authentication settings, complete the SSH access by setting up sudo commands in the next step.
Always keep a backup of an SSH public key if you are using one.
Enter additional details for the user. Setting options change based on the access option selected in Allow Access.
If this is an SMB share user, leave the default SMB Access selected.
When Shell Access and SSH Access are assigned to the user, the Shell and Sudo Command settings show in the Additional Details section.
Enter the full name for the user. The full user name is not case sensitive.
(Optional) Enter the email for the user.
Starting in TrueNAS 25.10, system notifications are sent to recipients configured in system email settings rather than user account emails.
Set up a group.
Accept the default group setting, which is Create New Primary Group. This creates a group with the same name as the admin user.
The role setting adds the user to the appropriate auxiliary group for that role.
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list.
Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID.
TrueNAS suggests a user ID starting at 3000, but you can change it if you wish.
We recommend using an ID of 3000 or greater for non-built-in users.(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty.
This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.
If set to this path, TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory.
The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset.
After clicking on a dataset, the Create Dataset option activates.
Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist.
pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure.
This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did.
This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished.
Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password.
To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password.
To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.
Disabling a Password
To disable a password, select the user, click Edit, and then select Disable Password.
Note that Disable Password is not available when SMB Access is enabled.
Setting Disable Password hides the Password widget, and TrueNAS removes any existing password from the account.
TrueNAS restricts the account from password-based logins for services like SMB shares and SSH sessions.
To disable all password-based functionality for the account, select the Lock User option on the Access widget.
This toggles to Unlock User when locked.
Adding Home Directories
You can add a home directory to a new or an existing user account.
You can create a dataset to use for user home directories if one does not exist before you add or edit a user. You can also create one while adding or editing the user.
To add a home directory to an existing user, go to Credentials > Users, click on the user row, and then click Edit to open the Edit User screen.
Scroll down to the Home Directory option, click in the field to show the settings.
Select Create Home Directory, then enter or browse to select the path to the dataset for home directories in Home Directory. For example, change /var/empty/ to the path to a new dataset.For example, /tank/homedirs.
Accept the default permissions or clear the checkmark to select the level of permissions you want to apply.
We recommend leaving the default selections, Read/Write/Execute selected for the user home directory.
Click Save. TrueNAS creates a new home directory for the user.
Editing User Accounts
To edit an existing user account, go to Credentials > Users.
Click anywhere on the user row, then click Edit to open the Edit User configuration screen.
See Users Screen for details on all settings.
Setting Up and Using API Keys
To view API keys that are linked to different user accounts, go to the Settings icon on the top toolbar and select My API Keys.
You can also go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.
If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.
The Users API Keys screen shows a table of all API keys linked to user accounts on your TrueNAS.
You can edit or delete your API keys in the User API Keys screen.
Click editEdit to open the Edit API Key screen.
Click deleteDelete to delete an API key.
Adding an API Key
To add an API key for a user, select the user row on the Users table, and then click Add API Key to open the Add API Key screen.
Enter a name for the key, select the user in the Username dropdown list field if not already populated with the correct username, and click Save.
To set the API key to expire, clear the checkmark in Non-expiring, then select the date using the calendar option in the field to set when this key expires.
After setting the date, click Save. The Access widget for this user shows the API Key icon and the View API Keys link.
Clearing Two-Factor Authentication for a User
Administrators can clear two-factor authentication (2FA) for a user from the Users screen. This is typically necessary when:
A user has lost access to their authenticator device (lost phone, broken device, etc.)
A user cannot generate valid 2FA codes due to device time synchronization issues
A user needs to switch to a different authenticator app or device
Troubleshooting 2FA-related login problems
Clearing 2FA should only be done when necessary, as it temporarily reduces account security. When Global 2FA is enabled, users are prompted to reconfigure 2FA on their next login.
To clear 2FA for a user:
Go to Credentials > Users.
Click on the user row to select the user whose 2FA needs to be cleared.
On the Access widget, click Clear Two-Factor Authentication.
Click Clear to confirm, or Cancel to abort the operation.
After clearing, the user can log in without 2FA codes. If Global 2FA is enabled on the system, the user is prompted to set up 2FA again on their next login.
User Self-Clearing vs Admin Clearing
Users can also remove their own 2FA configuration using the Settings menu:
User self-clearing: The logged-in user accesses Settings > Two-Factor Authentication and clicks Unset 2FA Secret. This allows users to manage their own 2FA settings.
Admin clearing: Administrators use Credentials > Users > Access Widget > Clear Two-Factor Authentication to clear 2FA for another user. This is specifically for helping users who cannot access their accounts.
For more information on 2FA configuration and management, see Managing Global 2FA.
Managing Groups
TrueNAS offers groups as an efficient way to manage permissions for many similar user accounts.
See Users for managing users.
The interface lets you manage UNIX-style groups.
If the network uses a directory service, import the existing account information using the instructions in Active Directory.
By default, TrueNAS hides the built-in groups in the system.
To see built-in groups, click the Show Built-In Groups toggle. The toggle turns blue and shows all built-in groups.
Click the Show Built-In Groups toggle again to show only non-built-in groups on the system.
Adding a New Group
To create a group, go to Credentials > Groups and click Add.
Enter a unique number for the group ID in GID. TrueNAS uses this to identify a Unix group.
Enter a number above 3000 for a group with user accounts or enter the default port number as the GID for a system service.
Enter a name for the group.
The group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?) greater or less than (<) (>), equal (=). The dollar sign ($) can be the last character in a group name.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To allow Samba permissions and authentication to use this group, select SMB Group.
Using the same group ID (GID) is not permitted as it can create confusion. The operating system treats it as the same group, even if a different name is assigned.
Select SMB Group to make this group available for permissions editors over SMB protocol, and add the share ACL editor.
This is not used for SMB authentication or when determining the user session token or internal permissions checks.
Click Save.
Managing Groups
Click anywhere on a row to expand that group and show the group management buttons.
To add a user account to the group, select the user and then click the right arrow .
To remove a user account from the group, select the user and then click the left arrow .
To select multiple users, press Ctrl and click on each entry.
Click Save.
Edit Group
To edit an existing group, go to Credentials > Groups, expand the group entry, and click editEdit to open the Edit Group configuration screen. See Groups Screens for details on all settings.
Managing Privileges
Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges ares:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/execute permissions) to the user.
Active Directory can provision groups in TrueNAS or you can add new groups that you assign to users in AD.
After adding a group, verify or edit the privilege(s) granted to the users in the group.
Adding a Privilege
To configure a new privilege, go to Credentials > Groups, click on Privileges to open the Privileges screen.
Click Add to define a new privilege. For example, if you want to create an group with the ability to only perform and manage backup, replication, or some other task.
You can create a new privilege to customize the functional access you want to grant.
On the New Privilege screen:
Enter a name for the new privilege. Names can include the dash (-) or underscore (_) special characters, and upper and lowercase alphanumeric characters.
Make the name descriptive of the privilege. For example, Replication Administrator, Backup Administrator, iSCSI Share Admin, etc.
You can create a privilege that can only manage iSCSI shares or one that can manage applications based on the selections made in the Roles field.
Click in the Local Groups field to see a list of groups on the system. To add another group, click in the field to select another group.
Click the x to the right of the group name to remove that group from the privilege.
Click the down arrow at the right of the Roles field to show the list of roles configured on the system. Select all roles to include.
Use the scroll bar at the right of the field to see all options.
Select Web Shell Access to allow access to the shell screen in the TrueNAS UI.
Click Save to create the new privilege.
Users assigned to the group show on the Users screen with the new privilege granted to the user in the Roles column, and the new group shows on the Groups screen with privilege listed in the Roles column.
Setting Up Directory Services
The TrueNAS Directory Services tutorials contain options to edit directory domain and account settings, set up ID mapping, and configure authentication and authorization services in TrueNAS.
About Directory Services
TrueNAS provides unified directory services configuration that supports connecting to Active Directory domains or LDAP servers through a single, streamlined interface. The directory services configuration screen allows you to set up authentication credentials, connection parameters, and advanced options in one location.
Only one directory service type can be configured and enabled at a time.
To view Idmap and Kerberos Services, click Show next to Advanced Settings.
Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.
Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.
Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.
Configuring Active Directory
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Configuring TrueNAS Active Directory Access
The Active Directory (AD) service shares resources in a Windows network.
AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.
When joined to an AD domain, you can use domain users and groups in local ACLs on files and directories.
You can also set up shares to act as a file server.
Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.
Users can configure AD services on Windows or Unix-like operating systems using Samba version 4.
Enterprise-licensed systems include the Allow Directory Service users to access WebUI option on the System > Advanced Settings > Access Settings configuration screen. For more information on how to configure this, see Allowing Directory Service Users WebUI Access
Preparing to Configure AD in TrueNAS
Before configuring Active Directory (AD) in TrueNAS:
You need to know the hostname assigned to the TrueNAS system. The default value is truenas.
The Domain Account Name default is Administrator, or enter a name for TrueNAS to generate as the computer account upon domain join.
Enter the password for this account.
Verify name resolution.
Go to Network > Global Network Settings to verify your TrueNAS network DNS name servers are configured with the target domain controller address that you plan to add on the Active Directory screen.
Change the default hostname of the system from truenas to the name assigned to the TrueNAS system.
NetBIOS names (workgroup, domain, and computer names) are limited to 15 characters and cannot contain the following characters: \ / : * ? " < > |
Microsoft and RFC 852 define reserved words that should not be used as NetBIOS names. TrueNAS 25.04 and later enforce these restrictions through validation.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
If you encounter validation errors when joining Active Directory or configuring SMB services, verify that your NetBIOS Name, Workgroup, and Domain Name comply with these requirements.
Setting Time Synchronization
Active Directory relies on the time-sensitive Kerberos protocol.
TrueNAS adds the AD domain controller with the PDC Emulator FSMO Role as the preferred NTP server during the domain join process.
If your environment requires something different, go to System > Advanced Settings, click Add to open the NTP Servers screen, then add a new or edit a listed server.
Keep the local system time sync within five (5) minutes of the AD domain controller time in a default AD environment.
Use an external time source when configuring a virtualized domain controller.
TrueNAS generates alerts if the system time gets out of sync with the AD domain controller time.
TrueNAS has a few options to ensure both systems are synchronized. Either:
Go to System > General Settings, click Settings in the Localization widget, and set Timezone to the value that matches the location of the AD domain controller.
Set the system BIOS to either local time or universal time.
Connecting to the Active Directory Domain
Before you begin, modify the system DNS server settings.
Take a screenshot of your current settings to refer to if you need to revert to pre-AD settings for any reason.
Change the nameserver 1 setting to the IP address of the AD server and clear the other name server settings.
Make sure the domain name is set to something other than the default value truenas.
To connect TrueNAS to Active Directory:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select Active Directory from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the AD configuration.
Leave the Enable Account Cache checkbox selected to cache user and group information.
Caching makes directory users and groups available in UI dropdown menus.
Users with large domains should consider disabling account caching in order to reduce the load on domain controllers.
Leave the Enable DNS Updates checkbox selected to allow the directory service to update DNS records.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds).
Enter the Kerberos realm in Kerberos Realm. TrueNAS auto-populates this field after joining the domain.
Select Kerberos User from the Credential Type dropdown list. Required.
Enter the AD domain administrator username in Username. Required. Enter only the username (for example, Administrator), not the domain-prefixed format.
Enter the password for the administrator account in Password. Required.
Enter the required Active Directory Configuration settings:
Enter the TrueNAS hostname in TrueNAS Hostname. This value must match the Hostname setting on the Network > Global Configuration screen and cannot exceed 15 characters.
Enter the Active Directory domain name in Domain Name. For example, example.com or sales.example.com if configuring access to a child domain.
(Optional) Enter the site name in Site Name.
(Optional) Enter the organizational unit in Computer Account OU. This controls the location where the TrueNAS computer object is created when joining the Active Directory domain for the first time. The OU string includes the distinguished name (DN) of the Computer Account OU. For example, OU=Computers,DC=example,DC=com.
(Optional) Select the Use Default Domain checkbox to remove the domain name prefix from AD users and groups. This setting might be required for specific configurations such as Kerberos authentication with NFS for AD users. Using this setting can cause collisions with local user account names.
(Optional) Configure trusted domains:
Select the Enable Trusted Domains checkbox to allow clients to access TrueNAS if they are members of domains with a trust relationship.
Starting in TrueNAS 25.10, trusted domains are configured as part of the Active Directory configuration rather than as separate IDmap entries.
When selected, you can add trusted domain configurations. Each trusted domain requires an IDMAP Backend selection.
Configure IDMAP settings:
IDMAP (Identity Mapping) ensures that UIDs and GIDs assigned to Active Directory users and groups have consistent values domain-wide. By default, TrueNAS uses an algorithmic method based on the RID component of the user or group SID, which is suitable for most environments. Only administrators experienced with configuring ID mapping should customize IDMAP settings. Misconfiguration can lead to permissions incorrectly assigned to users or groups when data is transferred via ZFS replication or rsync, or when accessed via NFS or other protocols that directly access UIDs/GIDs on files.
TrueNAS creates the default Kerberos realm and principal, and the Computer Account OU value.
If you get a DNS server error, go to Network > Global Configuration, click Settings, and verify the DNS nameserver IP addresses are correctly configured with addresses that permit access to the Active Directory domain controller.
Correct any network configuration settings, then reconfigure the Active Directory settings.
TrueNAS offers advanced options for fine-tuning the AD configuration, but the preconfigured defaults are generally suitable.
I don't see any AD information!
TrueNAS can take a few minutes to populate the Active Directory information after configuration.
To check the AD join progress, open the assignmentTask Manager in the upper-right corner.
TrueNAS displays any errors during the join process in the Task Manager.
When the import completes, AD users and groups become available while configuring basic dataset permissions or an ACL with TrueNAS cache enabled (enabled by default).
Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab.
TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.
Understanding IDMAP Backends
When customizing IDMAP settings, you can select from several backend options. Each backend uses a different method to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs:
AD - Reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions.
AUTORID - Automatically allocates UID and GID ranges for each domain. Useful for environments with multiple trusted domains.
LDAP - Reads and writes UID / GID mapping tables from an external LDAP server.
NSS - Uses the Name Service Switch (NSS) to retrieve Unix user and group information from local or network sources.
RFC2307 - Reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only.
RID - Uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low.
TDB - Stores ID mappings in a local Trivial Database (TDB) file. Allocates new UIDs and GIDs as needed. Useful for standalone servers but not recommended for multi-server environments as mappings are not shared.
For most environments, the default RID backend provides consistent, reliable ID mapping without additional configuration.
Troubleshooting - Resyncing the Cache
If the cache becomes out of sync or fewer users than expected are available in the permissions editors, click Settings in the Active Directory widget, then click Rebuild Directory Service Cache to resync the cache.
The name in TrueNAS Hostname should match the name in Hostname on the Network > Global Configuration screen.
Disabling Active Directory
To disable your AD server connection without deleting your configuration or leaving the AD domain, click Settings in the Active Directory widget to open the Active Directory settings screen.
Clear the Enable Service checkbox and click Save to disable the AD service.
This returns you to the main Directory Services screen.
Click Configure Directory Services to open the Directory Services Configuration form with your existing configuration settings.
Select Enable Service again, and click Save to reactivate your connection to your AD server.
Leaving Active Directory
Users must cleanly leave an Active Directory for TrueNAS to delete the configuration.
To cleanly leave AD, click Leave Domain on the Active Directory settings screen to remove the AD object.
Remove the computer account and associated DNS records from the Active Directory.
If the AD server moves or shuts down without you using Leave Domain, TrueNAS does not remove the AD object, and you have to clean up the Active Directory.
Rolling Back to Earlier Boot Environments with AD Joined
When the system is joined to Active Directory and you roll back to (activate) an earlier boot environment, or in the case where you migrated from a FreeBSD-based version to a current Debian-Linux version of TrueNAS and then need to revert back to FreeBSD-based, this can result in desynchronization of the system account password in AD between the different environments.
The directory service-stored secret moves forward with upgrades, while the rolled-back boot environment retains the old one.
If desynchronization occurs, you might see a Kerberos credentials not valid error message.
To avoid possible issues, leave AD, then rollback or revert to the earlier version, and then rejoin AD.
To recover from the error, leave and then rejoin Active Directory.
Configuring IPA
TrueNAS supports IPA (Identity, Policy, and Audit) as a comprehensive identity management solution.
IPA integrates LDAP, Kerberos, NTP, and DNS services in a single package, providing centralized authentication and authorization for network resources.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Does IPA work with SMB?
IPA can work with SMB shares when properly configured.
IPA includes integrated Samba support and can provide user and group information for SMB authentication.
TrueNAS validates the full certificate chain when certificate validation is enabled.
TrueNAS does not support non-CA certificates when certificate validation is required.
Configuring IPA
Configure TrueNAS to use an IPA directory server:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select IPA from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the IPA configuration. Selected by default.
Select the Enable Account Cache checkbox to cache user and group information. Caching makes directory users and groups available in UI dropdown menus. Selected by default.
Select the Enable DNS Updates checkbox to allow the directory service to update DNS records. Selected by default.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds). Required.
Enter the domain name in Kerberos Realm. This is usually the uppercase version of the domain name, for example, EXAMPLE.COM.
Enter the IPA server hostname or IP address in Target Server. Required.
Enter the hostname for your TrueNAS system in TrueNAS Hostname. Required.
Enter the domain name in Domain. Required.
Enter the base distinguished name for the IPA directory in Base DN. Required. For example, dc=example,dc=com.
(Optional) Select the Validate Certificates checkbox to verify certificate authenticity when connecting to the IPA server. TrueNAS validates the full certificate chain when this option is selected.
Select Use Default SMB Domain Configuration to use default SMB domain settings. Selected by default.
To customize SMB domain settings, clear Use Default SMB Domain Configuration to reveal additional configuration options: Name, Domain Name, Range Low, Range High, and Domain SID.
Click Save.
Disabling IPA
Clear the Enable Service checkbox to disable the IPA directory server. This does not remove the configuration.
The main Directory Services screen returns to the default view showing the option to configure directory services.
Click Configure Directory Services to open the Directory Services Configuration form with the saved IPA configuration to enable IPA again. Select Enable Service again to reactivate your IPA directory server configuration.
Removing IPA from TrueNAS
Click Settings to open the IPA screen to remove the IPA configuration.
Clear all settings and click Save.
Configuring LDAP
TrueNAS has an Open LDAP client for accessing the information on an LDAP server.
An LDAP server provides directory services for finding network resources like users and their associated permissions.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Configuring LDAP
To configure TrueNAS to use an LDAP directory server:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select LDAP from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the LDAP configuration. Selected by default.
Select the Enable Account Cache checkbox to cache user and group information. Caching makes directory users and groups available in UI dropdown menus. Selected by default.
Select the Enable DNS Updates checkbox to allow the directory service to update DNS records. Selected by default.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds). Required.
(Optional) Enter the Kerberos realm in Kerberos Realm. This is usually the uppercase version of the domain name, for example, EXAMPLE.COM.
Enter the Credential Configuration settings:
Select the credential type from the Credential Type dropdown list. Options are LDAP Anonymous, LDAP Plain, LDAP MTLS, Kerberos Principal, or Kerberos User. Required.
If you selected Kerberos User, enter the LDAP administrative account username and password in the respective Username and Password fields. Required.
If you selected LDAP Plain, enter the applicable credentials in the Bind DN and Bind Password fields. Required.
If you selected LDAP MTLS, select the desired Client Certificate from the dropdown menu. Required.
If you selected Kerberos Principal, select the desired Kerberos Principal from the dropdown menu. Required.
Enter the LDAP server URLs in Server URLs. Required. Separate multiple entries by pressing Enter. If using a cloud service LDAP server, do not include the full URL.
Enter the LDAP server base DN in Base DN. Required. This is the top level of the LDAP directory tree to use when searching for resources. For example, dc=example,dc=org.
(Optional) Select the Start TLS checkbox if needed for your environment.
(Optional) Select the Validate Certificates checkbox to verify certificate authenticity when connecting to the LDAP server.
Select the LDAP NSS schema from the Schema dropdown list. Required. Options are RFC2307 or RFC2307BIS.
(Optional) Configure auxiliary parameters:
Select Use Standard Auxiliary Parameters to use default auxiliary parameters. Selected by default.
To customize auxiliary parameters, clear Use Standard Auxiliary Parameters to reveal the Auxiliary Parameters text field where you can enter custom options for nslcd.conf.
(Optional) Configure search bases:
Select Use Standard Search Bases to use default search bases. Selected by default.
To customize search bases, clear Use Standard Search Bases to reveal additional configuration options: User Base DN, Group Base DN, and Netgroup Base DN.
(Optional) Configure attribute maps:
Select Use Standard Attribute Maps to use default attribute mappings. Selected by default.
To customize attribute maps, clear Use Standard Attribute Maps to reveal four subsections for customization:
LDAP Password Attributes - Enter custom password attribute mappings.
LDAP Shadow Attributes - Enter custom shadow attribute mappings.
LDAP Group Attributes - Enter custom group attribute mappings.
LDAP Net Group Attributes - Enter custom net group attribute mappings.
Click Save.
Disabling LDAP
To disable LDAP but not remove the configuration, clear the Enable Service checkbox. The main Directory Services screen returns to the default view showing the option to configure directory services.
To enable LDAP again, click Configure Directory Services to open the Directory Services Configuration form with your saved LDAP configuration. Select Enable Service again to reactivate your LDAP directory server configuration.
Removing LDAP from TrueNAS
To remove the LDAP configuration, click Settings on the LDAP widget to open the Directory Services Configuration screen.
Click Clear Config to open the confirmation dialog.
Click Confirm to remove the LDAP configuration. The main Directory Services screen returns to the default view showing the option to configure directory services.
Configuring Kerberos
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD.
You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos uses realms and keytabs to authenticate clients and servers.
A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client.
By default, TrueNAS creates a Kerberos realm for the local system.
A keytab (“key table”) is a file that stores encryption keys for authentication.
TrueNAS allows users to configure general Kerberos settings, as well as realms and keytabs.
Kerberos Realms
TrueNAS automatically generates a realm after you configure AD.
To configure Kerberos realms:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Realms widget to open the Add Kerberos Realm screen.
Enter the realm name in Realm. Required. Enter the name as a domain name, for example, example.com.
(Optional) Enter the Key Distribution Center name in KDC. The KDC acts as the third-party authentication service for Kerberos. If left blank, TrueNAS uses DNS discovery to locate the KDC. Separate multiple values by pressing Enter.
(Optional) Enter the primary KDC in Primary KDC. The Kerberos client uses this KDC when acquiring credentials if the current KDC fails with a bad password error. This is valuable for domains with hub-and-spoke topology.
(Optional) Enter the server that performs all database changes in Admin Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
(Optional) Enter the server that performs all password changes in Password Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
Click Save.
Kerberos Keytabs
TrueNAS automatically generates a keytab after you configure AD.
A Kerberos keytab is a file containing one or more Kerberos principals with their associated encryption keys. TrueNAS automatically generates a keytab during the Active Directory domain join process. The keytab principals are typically associated with the TrueNAS host computer account.
Keytabs allow authentication without requiring password storage. TrueNAS does not store the Active Directory or LDAP administrator account password in the system database after the keytab is created.
Adding a Keytab to TrueNAS
After generating the keytab:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Keytabs widget to open the Add Kerberos Keytab screen.
Enter a name for the keytab in Name. If configured, TrueNAS populates this field with what it detects in Active Directory.
Browse to the keytab file in Kerberos Keytab and upload it.
Click Save.
Using a Keytab with Active Directory or LDAP
To configure AD to use a keytab, go to the Directory Services screen, click Settings in the Active Directory widget, and select the keytab using the Kerberos Principal dropdown list.
The keytab must correspond to the computer account created during the domain join process.
To configure LDAP to use a keytab principal, click Settings in the LDAP widget and select the keytab using the Kerberos Principal dropdown list.
Synchronizing Keytabs with Active Directory
When TrueNAS is joined to Active Directory, you can synchronize Kerberos keytabs with Active Directory to ensure keytab data remains current.
To synchronize keytabs:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Sync in the Kerberos Keytabs widget header to open the synchronization confirmation dialog.
Click Sync to synchronize the keytabs with Active Directory.
The Sync button only appears when the system is joined to Active Directory.
Kerberos Settings
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
The Kerberos Settings screen is available in Advanced Settings for configuring auxiliary parameters.
To access Kerberos Settings:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Settings in the Kerberos Settings widget to open the Kerberos Settings screen.
(Optional) Enter additional Kerberos application settings in Appdefaults Auxiliary Parameters. See the appdefaults section of krb.conf(5) for available settings and usage syntax.
(Optional) Enter additional Kerberos library settings in Libdefaults Auxiliary Parameters. See the libdefaults section of krb.conf(5) for available settings and usage syntax.
Click Save.
Backup Credentials
TrueNAS backup credentials store cloud backup services credentials, SSH connections, and SSH keypairs.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
Contents
Adding Cloud Credentials: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.
Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.
Adding Cloud Credentials
The Cloud Credentials screen, accessed from the Backup Credentials screen allows users to integrate TrueNAS with cloud storage providers.
These providers are supported for Cloud Sync tasks in TrueNAS:
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
To maximize security, TrueNAS encrypts cloud credentials when saving them.
However, this means that to restore any cloud credentials from a TrueNAS configuration file, you must enable Export Password Secret Seed when generating that configuration backup.
Remember to protect any downloaded TrueNAS configuration files.
Authentication methods for each provider could differ based on the provider security requirements.
You can add credentials for many of the supported cloud storage providers from the information on the Cloud Credentials Screens.
This article provides instructions for the more involved providers.
Adding a Cloud Credential
We recommend you open another browser tab and log into the cloud storage provider account you intend to link with TrueNAS.
Some TrueNAS providers credentials require entering additional information generated while creating the provider account.
For example, the Storj iX account produces an access and secret key that must be entered in the Cloud Credential screen to create the credential.
Have the authentication information required by your cloud storage provider on hand to make the process easier.
Authentication information can include but is not limited to user credentials, access tokens, and access and security keys.
To add a cloud credential:
Select the cloud service from the Provider dropdown list. The provider required authentication option settings display.
Enter the required authentication credentials, such as access token, access key and/or secret keys, and user credentials for the account into the appropriate fields.
Click Verify Credentials to verify the entered credentials work.
Click Save.
Adding Storj Cloud Credentials
Storj iX is the default cloud storage provider in TrueNAS.
Go to Credentials > Backup Credentials and click Add on the Cloud Credentials widget.
The Cloud Credentials screen opens with Storj displayed as the default provider in the Provider field.
You must use this link to create your Storj account to take advantage of the benefits of the Storj iX pricing!
Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, and click the button at the bottom of the screen.
The Storj main dashboard opens.
The endpoint set in the Storj credential applies to all Cloud Sync Tasks that use that credential.
After creating your Storj account and obtaining your S3 credentials, optionally specify a custom Endpoint to use a specific Storj tier (such as Global or Select). Leave the Endpoint field blank to use the default Storj endpoint.
Creating the Storj iX Account
Setting Up S3 Access
After creating your Storj iX account, add S3 access credentials.
Click Access Keys to open the Access Keys dashboard, then click New Access Key.
Select the permissions you want to allow this access key.
Choose Full Access to allow permanent full permissions to all buckets and data then click Create Access or select Advanced then click Next to customize access configuration.
b. Select the buckets to allow access to.
Click All Buckets or click Select Buckets and use the Buckets dropdown to select one or more bucket(s).
Click Next.
c. Select an expiration date if you want to set the duration or length of time to allow this credential to exist.
You can select a preset period, click Set Custom Expiration Date to use the calendar to set the duration, or select No expiration.
Click Next to open the Access Encryption window.
You can either create a TrueNAS compatible Storj bucket while configuring cloud credentials or wait to do so while configuring a TrueCloud back up or Cloud Sync task.
Not all Storj buckets are TrueNAS compatible.
To create a TrueNAS-compatible bucket, either log in to Storj using the ix Storj affiliate link before creating the bucket in the Storj UI, or use the TrueNAS UI to create the bucket using the Add New option.
To create a Storj bucket from the TrueNAS UI:
Go to Data Protection.
Click Add on either the TrueCloud Backup Tasks or Cloud Sync Tasks widget.
Select the stored Storj cloud credential from the Provider > Credentials dropdown.
Do this as part of setting up a task or use the wizard to create the bucket without saving a configured task.
Click Verify Credential for verification, then click Next to go to the What and When screen.
Click Save.
TrueNAS creates the remote bucket on Storj and then returns to the Cloud Sync Task Wizard.
Adding Amazon S3 Cloud Credentials
When adding an Amazon S3 cloud credential, you can either use the default authentication settings or advanced settings if you want to include endpoint settings.
To add a cloud credential for Amazon S3, select Amazon S3 in Provider, enter a name and then:
Navigate to My account > Security Credentials > Access Keys to obtain the Amazon S3 secret access key ID.
Access keys are alphanumeric and between 5 and 20 characters.
If you cannot find or remember the secret access key, go to My Account > Security Credentials > Access Keys and create a new key pair.
Enter or copy/paste the access key into Access Key ID.
Enter or copy/paste the Amazon Web Services alphanumeric password that is between 8 and 40 characters into Secret Access Key
(Optional) Enter a value to define the maximum number of chunks for a multipart upload in Maximum Upload Ports.
Setting a maximum is necessary if a service does not support the 10,000-chunk AWS S3 specification.
(Optional) Select Advanced Settings to display the endpoint settings.
To use the default endpoint for the region and automatically fetch available buckets leave this field blank.
For more information refer to the AWS Documentation for a list of Simple Storage Service Website Endpoints.
To detect the correct public region for the selected bucket leave the field blank.
Entering a private region name allows interaction with Amazon buckets created in that region.
c. (Optional) Configure a custom endpoint URL.
d. (Optional) Select Disable Endpoint Region to prevent automatic detection of the bucket region.
Enable only if your AWS provider does not support regions.
d. (Optional) Select Use Signature Version 2 to force using signature version 2 with the custom endpoint URL.
Select only if your AWS provider does not support default version 4 signatures.
For more information on using this to sign API requests see Signature Version 2.
Click Verify Credentials to check your credentials for any issues.
Click Save
Adding Cloud Credentials that Authenticate with OAuth
Cloud storage providers using OAuth as an authentication method are Box, Dropbox, Google Drive, Google Photos, pCloud, and Yandex.
Some providers like Google Drive and pCloud use additional settings to authenticate credentials.
Open the Cloud Credentials screen, select the name of the cloud storage provider on the Provider dropdown list, enter a name for the credential, and then:
Enter the provider account email in OAuth Client ID and the password for that user account in OAuth Client Secret.
Click Log In To Provider. The Authentication window opens. Click Proceed to open the OAuth credential account sign-in window.
Yandex displays a cookies message you must accept before you can enter credentials.
Enter the provider account user name and password to verify the credentials.
(Optional) Enter the value for any additional authentication method.
For pCloud, enter the pCloud host name for the host you connect to in Hostname.
For Google Drive when connecting to Team Drive, enter the Google Drive top-level folder ID.
Enter the access token from the provider if not populated by the provider after OAuth authentication. Obtaining the access token varies by provider.
Provider
Access Token
Box
For more information on the user access token for Box click here. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
The authentication process creates the token for Google Drive and populates the Access Token field automatically. Access tokens expire periodically, so you must refresh them.
Google Photo
Does not use an access token.
pCloud
Create the pCloud access token here. These tokens can expire and require an extension.
Click Verify Credentials to make sure you can connect with the entered credentials.
Click Save.
Adding BackBlaze B2 Cloud Credentials
BackBlaze B2 uses an application key and key ID to authenticate credentials.
Open the Cloud Credentials screen, select BackBlaze B2 in Provider, enter a name and then:
Log into the BackBlaze account, go to the App Keys page, and add a new application key. Copy and paste this into Key ID.
Generate a new application key on the BackBlaze B2 website.
From the App Keys page, add a new application key. Copy the application Key string Application Key.
Click Verify Credentials.
Click Save.
Adding Google Cloud Storage Credentials
Google Cloud Storage uses a service account JSON file to authenticate credentials.
Open the Cloud Credentials screen, select Google Cloud Storage in Provider, enter a name and then:
Go to your Google Cloud Storage website to download this file to the TrueNAS server.
The Google Cloud Platform Console creates the file.
Click Choose File to browse the server to locate the downloaded JSON file and upload it. The file populates Preview JSON Service Account Key
For help uploading a Google Service Account credential file click here.
Click Verify Credentials.
Click Save.
Adding OpenStack Swift Cloud Credentials
OpenStack Swift authentication credentials change based on selections made in AuthVersion.
All options use the user name, API key or password, and authentication URL, and can use the optional endpoint settings.
For more information on OpenStack Swift settings, see rclone documentation.
Open the Cloud Credentials screen, select OpenStack Swift Cloud in Provider, enter a name for the credential and then:
(Optional) Select the version from the AuthVersion. For more information see rclone documentation.
Select the desired option based on your use case.
Set Auth(vx) to V1 or V2
d. Enter the ID in Tenant ID. Required for v2 and v3 and (optional) enter a Tenant Domain.
e. (Optional) Enter the alternative authentication token in Auth Token.
f. Enter a region name in Region Name
g. (Optional) Enter the URL in Storage URL.
h. (Required) Select the service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended.
Click Verify Credentials.
Click Save.
Adding Microsoft OneDrive Credentials
Microsoft OneDrive uses OAuth authentication to connect TrueNAS to your cloud account.
Open the Cloud Credentials screen, select Microsoft OneDrive in Provider, enter a name and then:
Click Log In To provider to open the Microsoft sign-in page in a new window. You can confirm the intended authorization in the new window.
Confirm the authorization to enter your Microsoft login information. After logging in to your account, Microsoft prompts you to give TrueNAS access to your Microsoft information.
Give TrueNAS access to your Microsoft account and close the pop-up window. Your Cloud Credentials wizard should now say Logged In To Provider and have populated OAuth Client ID, OAuth Client Secret, Access Token, and Drive Account Type fields.
(Optional) Select an entry from the Drives List drop-down menu. This will also populate the Drive ID field.
Choose a drive from your OneDrive account and enter the ID in this field. If you selected an entry for Drives List, this field should already be populated with a valid ID.
Click Save.
Using Automatic Authentication
Some providers can automatically populate the required authentication strings by logging in to the account.
To automatically configure the credential, click Login to Provider and enter your account user name and password.
We recommend verifying the credential before saving it.
Adding SSH Credentials
The SSH Connections and SSH Keypairs widgets on the Backup Credentials screen display a list of SSH connections and key pairs configured on the system.
Using these widgets, users can establish Secure Socket Shell (SSH) connections.
You must also configure and activate the SSH Service to allow SSH access.
These SSH credentials are used to manage SSH connections specifically for automated tasks such as replication, backups, cloud sync, or other system-to-system operations. You can generate, store, and manage SSH key pairs and define SSH connections that TrueNAS uses for these automated processes. The key pairs managed here are not tied to individual user but are instead used by the system for secure communication with other systems or services.
For individual user SSH access, configure SSH keys in the user account settings under Credentials > Users.
Creating an SSH Connection
To begin setting up an SSH connection, go to Credentials > Backup Credentials.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Configuring a Semi-Automatic SSH Connection
The procedure in this section covers the semi-automatic setup method for creating an SSH connection with another TrueNAS system.
Semi-automatic simplifies setting up an SSH connection with another TrueNAS system without logging in to that system to transfer SSH keys.
This requires an SSH key pair on the local system and administrator account credentials for the remote TrueNAS.
You must configure the remote system to allow root access with SSH.
You can generate the key pair as part of the semiautomatic configuration or a manually created one using SSH Keypairs.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Configuring a Manual SSH Connection
The instructions in this section cover how to set up an SSH connection to a non-TrueNAS system.
To manually set up an SSH connection, you must copy a public encryption key from the local system to the remote system.
A manual setup allows a secure connection without a password prompt.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select Manual from the Setup Method dropdown list.
a. Enter a host name or host IP address for the remote non-TrueNAS system as a valid URL.
An IP address example is https://10.231.3.76.
This is a required field.
b. Enter the port number of the remote system to use for the SSH connection.
c. Enter a user name for logging into the remote system in Username.
d. Select the private key from the SSH key pair that you use to transfer the public key on the remote NAS from the Private Key dropdown.
e. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate the Remote Host Key field.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection widget.
To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.
Adding a Public SSH Key to an Admin User Account
This procedure covers adding a public SSH key to the admin account on the TrueNAS system and generating a new SSH Keypair to add to the remote system (TrueNAS or other).
Copy the SSH public key text or download it to a text file:
Log in to the TrueNAS system that generated the SSH key pair and go to Credentials > Backup Credentials.
Click on the name of the key pair on the SSH Keypairs widget to open the key pair for the SSH connection.
Copy the text of the public SSH key or download the public key as a text file.
Add the public key to the admin account on the system where you want to register the public key.
Log in to the TrueNAS system where you want to register the public key and go to Credentials > Users.
Edit the admin account. Select the user, and click Edit to open the Edit User screen.
If the remote NAS is not a TrueNAS system, refer to the documentation for that system and find its instructions on adding a public SSH key.
Generating SSH Keypairs
TrueNAS generates and stores RSA-encrypted SSH public and private key pairs on the SSH Keypairs widget found on the Credentials > Backup Credentials screen.
Key pairs are generally used when configuring SSH Connections or SFTP Cloud Credentials.
TrueNAS does not support encrypted key pairs or key pairs with passphrases.
TrueNAS automatically generates key pairs as needed when creating new SSH Connections or Replication tasks.
To manually create a new key pair:
Click Add on the SSH Keypairs widget.
Click Generate New on the SSH Keypairs screen.
Give the new key pair a unique name and click Save.
The key pair displays on the SSH Keypairs widget.
Click the vertical ellipsis more_vert at the bottom of the SSH Keypairs configuration screen to download these strings as text files for later use.
Certificates
Use the Credentials > Certificates screen to manage certificates, certificate signing requests (CSRs), and DNS authenticators with the Certificates, Certificate Signing Requests (CSRs), and ACME DNS-Authenticators widgets.
Each TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import custom certificates for authentication and validation while sharing data.
Contents
Managing Certificates: Provides information on adding or managing certificates in TrueNAS.
Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.
Managing Certificates
The Certificates screen shows information for certificates, certificate signing requests (CSRs), and ACME DNS-authenticators configured on the system, and provides the ability to import or edit them.
TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
The TrueNAS Connect service automatically creates a default truenas_connect_ certificate after registering your TrueNAS system in the TrueNAS Connect service.
The certificate shows in the Certificates widget on the Credentials > Certificates screen.
This certificate provides secure SSL access between the TrueNAS server and the TrueNAS Connect service.
If not listed on the Certificates screen, choose the truenas_default certificate.
For apps where certificates are used, you should see and be able to select the TNC certificate and get a full secure connection for the apps.
Adding Certificates
By default, TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import and edit existing certificates.
To add a certificate to TrueNAS, click Import on the Certificates widget to open the Import Certificates screen.
First, enter a name as a certificate identifier. A name can include the dash (-) or underscore (_) special characters.
Select Add To Trusted Store if you want to add the imported certificate to the trusted store in TrueNAS.
Copy/paste the certificate into the Certificate field, and the private key part of the certificate into the Private Key field.
Enter or copy/paste the password associated with the private key into the Password and Confirm Password fields.
Click Import to add the certificate to TrueNAS.
Editing a Certificate
TrueNAS allows you to rename a certificate or to add it to the TrueNAS trusted store.
Click on the more_vert icon, then select Edit on the dropdown list. The Edit Certificate screen for that certificate opens.
Enter a new name for the certificate.
Select Add To Trusted Store to add the certificate to the TrueNAS trusted store.
Click Save.
My TrueNAS SSL Certificate Has Expired
TrueNAS uses a self-signed default certificate (truenas_default) to encrypt access to the web interface.
Browsers show a warning for self-signed certificates because no external authority verifies them.
This warning becomes an error after the certificate expires.
Check the Until and Lifetime fields on the Edit Certificate screen for the current GUI certificate before it expires. See Certificates Screens for details.
TrueNAS automatically renews an unmodified default certificate shortly before it expires.
An expired truenas_default certificate usually means the system was offline through the renewal window, or the certificate subject, such as the Common Name or SAN, was changed from its default values.
Renaming the certificate or adding it to the trusted store does not affect automatic renewal.
TrueNAS 25.10 removed the internal certificate authority (CA) functionality that could sign a new certificate for you.
Replace an expired certificate using one of the following two options, then set the new certificate as the GUI certificate.
Get a certificate signed by an external CA
Create a CSR in TrueNAS, then have it signed by a trusted CA.
Options include free public CAs like Let’s Encrypt and ZeroSSL, paid commercial CAs like DigiCert and Sectigo, and internal CAs like Active Directory Certificate Services or step-ca.
Public CAs validate domain ownership and require a domain name reachable from the internet.
Internal CAs don’t have that requirement, but need to already exist in your environment.
Import the signed result back into TrueNAS as a certificate.
For a domain-validated certificate through Let’s Encrypt, TrueNAS can complete the CSR, signing, and renewal steps automatically using ACME.
This requires a public domain name pointed at your TrueNAS system.
See Creating ACME Certificates for the full procedure.
Import an existing certificate
If a valid certificate and private key are already available from an external CA, for example one issued by an enterprise CA, import them directly.
See Adding Certificates for the procedure.
Then, set the new certificate as the GUI certificate
After you import or create a new certificate, TrueNAS does not switch to it automatically.
Go to System > General Settings and click Settings in the GUI widget.
Select the new certificate from the GUI SSL Certificate dropdown, then click Save.
Select the Confirm checkbox, then click Continue to restart TrueNAS and apply the new certificate.
Downloading the Certificate or Public Key
Click on the more_vert icon, then select Edit or Download on the dropdown list.
On the Edit Certificate screen for the selected certificate, click View/Download Certificate
to open a window with the certificate string.
Click View/Download Key to open a window with the certificate private key.
To copy the certificate or private key to the clipboard, click on the assignment clipboard icon.
Click Download to put a copy of the certificate or private key on your server.
Keep the certificates and private keys in a secure area where you can back them up.
Managing Certificate Signing Requests
The Certificate Signing Requests widget allows users to configure a message the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
Adding a CSR
If you plan to create an ACME certificate, before adding a CSR, make sure the certificate authority provider account (i.e., Cloudflare, DigitalOcean, etc.) is correctly configured with all domains entered in this CSR.
When adding an ACME certificate for a CSR, it is created based on the settings in the selected CSR.
When adding an ACME certificate for a CSR, it is created based on the settings in the selected CSR.
For example, if using a Cloudflare DNS authenticator, in the Cloudflare account, register the domain(s) entered in the Subject Alternative Name field on the Certificate Subject screen in the Add CSR wizard.
If the CSR and provider accounts are not properly configured, a dialog with an error indicating the configuration problem opens.
You can only edit the name of the CSR after clicking Save.
If you make a mistake or want to change any setting, delete the CSR and create a new one with the desired or correct settings.
To add a CSR:
Enter a name and select the CSR type.
The Add CSR wizard allows creating a certificate signing request (CSR) or importing a certificate for a CSR.
Users can select a predefined certificate extension from the Profiles dropdown list.
Select or enter the certificate options for the CSR. TrueNAS shows default settings in each field.
Key Type shows the option matching the selection made in Profiles in step 1.
Accept the default values or choose the number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.
Click Next.
Enter the Certificate Subject settings. When entering values, enter short values for the geographic information, where possible.
For example, enter TN instead of Tennessee for the State. Enter all required values (indicated by the asterisk).
If specifying a value in Common Name, it can be the full domain assigned to the TrueNAS system or just the example.net portion of the domain name.
Include this in the Subject Alternative Name field.
You can enter any other system fully-qualified hostname (FQDN) and domains for multi-domain support.
When specifying an IP address in Subject Alternative Name do not enter the IP address of the system.
This results in an error if you try to create an ACME certificate for the CSR.
(Optional) Enter any extra constraints if needed for your scenario. The Extra Constraints step contains certificate extension options.
Basic Constraints limits the path length for a certificate chain.
Authority Key Identifier identifies the public key corresponding to the private key used to sign a certificate.
Key Usage defines the purpose of the public key contained in a certificate.
Extended Key Usage further refines key usage extensions.
Review the certificate options.
Click Back until reaching the screen with the setting option you want to change, make the change, and then click Next to advance to the Confirm Options step.
Click Save to add the CSR.
Importing a CSR
When importing a certificate into TrueNAS for the CSR, enter a name, and then select Import Certificate Signing Request in Type. Click Next.
Enter or copy/paste the certificate string into Signing Request, then enter or copy/paste the private key into Private Key.
Enter the password for the private key in Password and Confirm Password. Click Next, review the information, and then click Save.
Creating an ACME Certificate
TrueNAS provides a way to add a certificate for an ACNE DNS authenticator added to the system.
After adding the DNS authenticator, create a CSR for it.
Click on the more_vert for the CSR on the Certificate Signing Requests widget, then click on Create ACME Certificate to open the Create ACME Certificate screen.
You must configure a DNS authenticator to create an ACME certificate!
The ACME certificate is created based on the settings in the selected CSR.
You must have the domains added to the account providing the DNS authenticator.
For example, if using Cloudflare to create the DNS authenticator, the Cloudflare account must have the domain(s) entered in the Subject Alternative Name field in the Add CSR wizard on the Certificate Subject screen.
If not properly configured, a dialog with an error indicating the configuration problem opens.
Enter a name in Identifier. The underscore (_) and dash (-) are allowed characters in the name.
Select Terms of Service.
Enter a number that specifies the time (in days) before the certificate expires in Renew Certificate Days.
Select the URI of the ACME server directory from the ACME Server Directory URI dropdown list.
The Domains area shows domains for each entry made in the Subject Alternative Name field on the Certificate Subject screen of the Add CSR wizard.
Select the option from the dropdown list for each domain shown. This sets the authenticator to validate the domain.
Click Save.
The new ACME certificate shows on the Certificates and the Certificate Signing Requests widgets.
Adding ACME DNS Authenticators
Automatic Certificate Management Environment (ACME) DNS authenticators allow users to automate certificate issuing and renewal.
The user must verify ownership of the domain before TrueNAS allows certificate automation.
ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.
The system requires an ACME DNS Authenticator and CSR to configure ACME certificate automation to proceed.
Adding a DNS Authenticator
Before you begin this procedure, log in to your DNS authenticator provider service to obtain an API global key or an API token, whichever your service provider requires.
When configuring an ACME DNS authenticator in TrueNAS using Cloudflare as the provider, you need the global API key but not the API token.
This procedure uses Cloudflare as the example.
To add an authenticator:
Click Add on the ACME DNS-Authenticator widget to open the Add DNS Authenticator screen.
Select the authenticator you want to configure. Cloudflare shows by default.
Supported authenticator options are Cloudflare, DigitalOcean, Amazon Route 53, OVHcloud, and shell.
Authenticator selection changes the configuration fields.
When selecting cloudflare as the authenticator, enter the Cloudflare account email address associated API key and the DNS domain.
For Cloudflare, copy/paste the global API key from Cloudflare into the API Key field.
If using an API token, do not enter the Cloudflare account email address.
When selecting digitalocean as the authenticator, enter your DigitalOcean Token.
When selecting route53 as the authenticator, enter your Route53 Access key ID and secret access key.
When selecting OVH as the authenticator, enter your OVH application key, application secret, consumer key, and endpoint.
Click Save to add the authenticator.
The DNS authenticator shows on the ACME DNS-Authenticator widget. To make changes, click on the more_vert for the authenticator, and then on Edit.
After adding the authenticator, you can configure a certificate signing request (CSR) for this authentictor and create an ACME certificate.
For more information, see Managing Certificate Signing Requests.
Adding an Authenticator with a Shell Script
The shell authenticator option is intended for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.
If you select shell as the authenticator, you must enter the path to an authenticator script, the running user, a certificate timeout, and a domain propagation delay.
Advanced users can select this option to pass an authenticator script, such as acme.sh, to the shell and add an external DNS authenticator.
This requires an ACME authenticator script saved to the system.
Creating ACME Certificates
TrueNAS allows users to automatically generate custom domain certificates using Let’s Encrypt.
Requirements
An email address for your TrueNAS admin user.
A custom domain that uses Cloudflare, DigitalOcean, Amazon Route 53, or OVHcloud.
A DNS server that does not cache for your TrueNAS system.
Create an ACME DNS-Authenticator
Go to Credentials > Certificates and click ADD in the ACME DNS-Authenticators widget.
Enter the required fields depending on your provider, then click Save.
For Cloudflare, enter either your Cloudflare Email and API Key, or enter an API Token.
If you create an API Token, make sure to give the token the permission Zone.DNS:Edit, as it’s required by certbot.
For DigitalOcean, enter your Digitalocean Token.
For Route53, enter your Access Key ID and Secret Access Key. The associated IAM user must have permission to perform the Route53 actions ListHostedZones, ChangeResourceRecordSets, and GetChange.
For OVH, enter your OVH Application Key, OVH Application Secret, OVH Consumer Key, and OVH Endpoint.
Create a Certificate Signing Request (CSR)
Next, click ADD in the Certificate Signing Requests widget.
You can use default settings except for the Common Name and Subject Alternate Names fields.
Enter your primary domain name in the Common Name field, then enter additional domains you wish to secure in the Subject Alternate Names field.
For example, if your primary domain is domain1.com, entering www.domain1.com secures both addresses.
Create ACME Certificate
Click the icon next to the new CSR.
Fill out the ACME Certificate form. Under Domains, select the ACME DNS Authenticator you created for both domains, then click Save.
You can create testing and staging certificates for your domain.
Set the GUI SSL Certificate
Go to System > General Settings and click Settings in the GUI widget.
Select the new ACME certificate you created from the GUI SSL Certificate dropdown, then click Save.
Select the Confirm checkbox, then press Continue to restart TrueNAS and apply the changes.
Configuring KMIP
TrueNAS Enterprise
KMIP is only available for TrueNAS Enterprise licensed systems.
Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.
The Key Management Interoperability Protocol (KMIP) is an extensible client/server communication protocol for storing and maintaining keys, certificates, and secret objects.
KMIP on TrueNAS Enterprise integrates the system within an existing centralized key management infrastructure and uses a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
With KMIP, keys created on a single server are then retrieved by TrueNAS.
KMIP supports keys wrapped within keys, symmetric, and asymmetric keys.
KMIP enables clients to ask a server to encrypt or decrypt data without the client ever having direct access to a key.
You can also use KMIP to sign certificates.
Requirements
To simplify the TrueNAS connection process:
Have a KMIP server available with certificate authorities and certificates you can import into TrueNAS.
Have the KMIP server configuration open in a separate browser tab or copy the KMIP server certificate string and private key string to later paste into the TrueNAS web interface.
Connecting TrueNAS to a KMIP Server
To connect TrueNAS to a KMIP server, import a Certificate from the KMIP server, then configure the KMIP options.
How do I import these?
Log into the TrueNAS web interface and go to Credentials > Certificate.
Click Import on the Certificate widget.
Enter a memorable name for the certificate, then paste the KMIP server certificate and private key strings into the related TrueNAS fields.
Leave Passphrase empty.
Click Save.
For security reasons, we strongly recommend protecting the certificate values.
Enter the central key server host name or IP address in Server and, if not using the default port 5696, enter a number for an open connection port on the central key server in Port.
Select the certificate imported from the central key server in Certificate.
To ensure the certificate chain is correct, click on Validate Connection. Click Save.
When the certificate chain verifies, choose the encryption values, SED global password, or ZFS data pool encryption keys to move to the central key server.
Select Enabled to begin moving the passwords and keys immediately after clicking Save.
Refresh the KMIP screen to show the current KMIP Key Status.
To cancel a pending key synchronization, select Force Clear and click Save.
Containers
Virtual Machines and Containers in TrueNAS 25.10
TrueNAS 25.04 introduced support for Containers (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in FreeBSD-based TrueNAS.
In TrueNAS 25.04.2 and later, virtual machines are created and appear on the Virtual Machines screen.
Legacy VMs created in 25.04.0 or 25.04.1 using the instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the Containers screen.
Legacy VMs on the Containers screen do not autostart in 25.10 or later.
Users with existing VMs on the Containers screen should consider migrating associated zvols to the Virtual Machines screen at this time to ensure compatibility with future TrueNAS releases.
For information on migrating your zvol storage volume to a new VM created in 25.10 or later, see Migrating Legacy VMs to Virtual Machines.
Due to backend technology changes in TrueNAS 27, containers on the Containers screen require migration when you upgrade from TrueNAS 25.10.
Containers migrate automatically at the first boot after upgrading, except on HA-capable TrueNAS Enterprise systems.
Containers on a passphrase-encrypted pool do not migrate, because the pool is still locked at first boot and the migration does not retry.
Switch the pool to key encryption before you upgrade.
Contact TrueNAS Enterprise Support if you have containers on a TrueNAS Enterprise system that does not migrate them.
Legacy VMs on the Containers screen are not migrated automatically and are removed from the Containers screen in TrueNAS 27.
Complete the steps in Preparing to Upgrade to TrueNAS 27 before you upgrade.
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.
Containers allow users to configure linux containers in TrueNAS.
Linux containers, powered by LXC, offer a lightweight, isolated environment that shares the host system kernel while maintaining its own file system, processes, and network settings.
Containers start quickly, use fewer system resources than virtual machines (VMs), and scale efficiently, making them ideal for deploying and managing scalable applications with minimal overhead.
What system resources do containers require?
Containers are lightweight and share the host kernel, requiring fewer resources than virtual machines.
However, proper resource allocation ensures optimal performance and system stability.
You can leave CPU and memory settings blank to allow containers access to all available host resources, or configure specific limits based on your needs.
Key considerations for container deployment:
Storage Pool: Containers require a storage pool for volume creation and image storage.
SSD drives provide optimal performance.
CPU: No virtualization extensions required.
Multiple containers run efficiently on fewer resources than equivalent VMs.
Memory: More efficient than VMs with no guest OS overhead.
Memory allocated to containers reduces available memory for TrueNAS ZFS caching.
Setting Up the Containers Service
You must choose a pool before you can deploy a container.
The Containers screen header displays a Pool is not selected status before a pool for containers is selected.
See Choosing the Containers Pool below for more information about pool selection.
Click Global Settings on the Configuration menu to open the Global Settings screen, showing global options that apply to all containers.
Use these options to configure the storage pool for containers and network settings.
You must set a pool before you can add any containers.
Select Enabled to enable container storage.
Use the Pool dropdown to select one or more pools and click Save.
We recommend users keep the container use case in mind when choosing a containers pool.
Select a pool with enough storage space for all the containers you intend to host.
For stability and performance, we recommend using SSD/NVMe storage for the containers pool due to their faster speed and resilience for repeated read/writes.
Select additional pools to allow containers to access shared resources.
TrueNAS stores container data in a hidden .truenas_containers dataset on the selected pool.
See Container Storage Location in Containers Screens for details.
To select a different pool for containers to use, use the Pool dropdown to select a different pool.
Deselect Enabled to deactivate the pool and disable the containers service.
Configuring the Default Network
Use the Default Network settings on the Global Settings screen to define how containers connect to the network.
These settings apply to all new containers, unless configured otherwise.
Select Automatic from the Bridge dropdown list to use the default network bridge for communication between containers and the TrueNAS host.
To specify an existing bridge, select one from the dropdown list.
See Accessing NAS from VMs and Containers for details. When Bridge is set to Automatic, the IPv4 Network and IPv6 Network settings display.
Enter an IPv4 address and subnet (e.g., 192.168.1.0/24) in IPv4 Network to assign a specific network for containers.
Leave this field empty to allow TrueNAS to assign the default address.
Enter an IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) in IPv6 Network or leave this field empty to allow TrueNAS to assign the default address.
Adjust these settings as needed to match your network environment and ensure proper connectivity for containers.
Managing Volumes
Click Manage Volumes on the Configuration menu to open the Volumes screen, which lists all the volumes currently configured for the containers service.
Click Create Volume to open the Create New Volume dialog to configure a new volume.
Click Import Zvols to open the Import Zvol dialog to import an existing Zvol as a volume.
Click Import Zvols on the Volumes screen to open the Import Zvol dialog.
Importing a zvol as a volume allows its lifecycle to be managed, including backups, restores, and snapshots.
This allows portability between systems using standard tools.
Enter the path or browse to select an existing Zvol in Select Zvols.
Select Clone to clone and promote a temporary snapshot of the zvol into a custom storage volume.
This option retains the original zvol while creating an identical copy as a container volume.
Select Move to relocate the existing zvol to the ix-virt dataset as a volume.
Deleting Volumes
Click Configuration > Manage Volumes to access the Volumes screen.
Click delete on a volume row to delete that volume.
The Delete volume dialog displays.
Select Confirm and then click Continue to delete the volume.
TrueNAS disables the delete icon for active images to prevent accidental deletion.
Managing Container Permissions
Containers run as isolated environments from the host system. To give container processes access to host files and datasets, you must map user and group IDs (UIDs and GIDs) between the host and the container.
Click Map User/Group IDs from the Configuration dropdown to open the Map User and Group IDs screen. This screen allows you to configure how user and group IDs (UIDs and GIDs) appear inside containers.
By default, user and group accounts within a container are assigned UIDs and GIDs from a private range starting at 2147000001. This mapping ensures security isolation for containers.
You can override these mappings to meet specific access requirements.
Select Users or Groups to view mappings for individual user or group accounts.
Existing mappings appear in a table that lists the user or group name, host ID, and container ID. Click delete Delete on a row to remove a mapping.
To add a new mapping:
Type an account name to search or select it from the dropdown.
Enable Map to the same UID/GID in the container to use the same ID from the host in containers. This makes the selected user or group ID appear the same inside and outside the container.
Disable Map to the same UID/GID in the container to assign a different container ID. Enter the container UID or GID you want to use—for example, 1000.
Only local users and groups are supported for ID mapping in containers. Domain accounts from Active Directory or other directory services are not supported.
Click Set to create the mapping. Changes apply immediately, though restarting the container can be required for them to take effect.
Mapped IDs control access to mounted host datasets. For example, if you map a host user with UID 3000 to UID 1000 inside the container:
Assign permissions on the host dataset to UID 3000.
Inside the container, perform actions as UID 1000.
This setup grants user 1000 in the container the same access to the dataset as user 3000 has on the host. Assigning dataset permissions to a host user is not enough to grant container permissions to all users—you must also map that user and ensure the correct user and UID is used inside the container.
Incorrect or missing mappings can cause permission errors when containers access host paths.
Granting Root Access to Host Paths
To safely allow container root processes to access host datasets, TrueNAS provides a built-in unprivileged root user for containers truenas_container_unpriv_root.
This user has UID 2147000001 and is used automatically to represent the container root on the host.
No manual ID mapping is required.
To grant container root access to host data:
Assign permissions on the host dataset to the truenas_container_unpriv_root user.
Access the dataset from inside the container as root.
When the container root accesses the path, it uses the host permissions of truenas_container_unpriv_root.
This approach provides secure, controlled access for container root processes without exposing host root privileges.
Creating Containers
Click Create New Container to open the Create Container configuration wizard.
Enter values for CPU Configuration and Memory Size or leave blank to allow the container access to all host CPU and memory resources.
To configure resource allocation:
a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.
Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores.
For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node.
For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.
b. Allocate RAM in Memory Size.
This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB).
If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
(Optional) Configure environment variables to run on boot or execute.
a. Click Add in the Disks section to display a set of fields to mount a disk.
b. To create a new dataset, enter a path or browse to select a parent dataset from the dropdown list of datasets on the system.
Then click Create Dataset, enter a name for the new dataset in the Create Dataset window, and click Create.
To use an existing volume, enter a path or browse to select an existing dataset from the Source dropdown list.
c. Enter the file system Destination path to mount the disk in the container, for example /media or /var/lib/data.
d. Click Add again to mount additional storage volumes.
(Optional) Configure proxy settings to forward network connections between the host and the container.
This routes traffic from a specific address on the host to an address inside the container, or vice versa, allowing the container to connect externally through the host.
a. Click Add in the Proxies section to display a set of proxy configuration settings.
b. Select the protocol option from the Host Protocol dropdown list to set the connection protocol for the TrueNAS host as TCP or UDP.
c. Enter a port in Host Port to define the TrueNAS port to map to the container port on the container, for example 3600.
d. Select the connection protocol for the container in Instance Protocol.
Options are TCP or UDP.
e. Enter the port number within the container in Instance Port, for example 80, to map to the host port.
Configure the Network section settings to define how the container connects to the host and external networks.
Options include the default network bridge, an existing bridge interface, or a MACVLAN.
Use default network settings: Enable to connect the instance to the host using the automatic bridge defined in Global Settings. Disable to show the Bridged NICs (if available) and Macvlan NICs settings.
To configure non-default network settings, select one or more interface options:
Bridged NICs: Use to connect an existing bridge interface to the instance.
Macvlan NICs: Use to create a virtual network interface based on an existing interface.
A MACVLAN assigns a unique MAC address to the virtual interface so the instance appears as a separate device on the network.
A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host.
MACVLAN sends traffic directly to the external network without passing through the host network stack.
The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.
(Optional) Configure USB devices to attach available devices to the container by selecting one or more in USB Devices.
This allows the device to function as if physically connected.
(Optional) Configure GPU devices in the GPU Devices section to attach available GPU devices, enabling the container to utilize hardware acceleration for graphics or computation tasks.
TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPUs from NVIDIA, Intel, and AMD.
As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see Installing NVIDIA Drivers.
Click Create to deploy the container.
Managing Containers
Created containers appear in a table on the Containers screen.
The table lists each configured container, displaying its name, type, current status, and options to restart or stop it.
Stopped containers show the option to start the container.
Select the checkbox to the left of Name (select all) or select one or more container rows to access the Bulk Actions dropdown.
Enter the name of a container in the Search field above the Containers table to locate a configured container.
Click restart_alt to restart or stop_circle to stop a running container.
Choosing to stop a container shows a choice to stop immediately or after a small delay.
Click play_circle to start a stopped container.
Select a container row in the table to populate the Details for Container widgets with information and management options for the selected container.
Using Bulk Actions
Apply actions to one or more selected containers on your system using Bulk Actions.
Click Edit to open the Edit Container: Container screen.
The Edit Container: Container screen settings are a subset of those found on the Create Container screen.
It includes the general Container Configuration and CPU and Memory settings for containers.
Additionally, containers include Environment settings.
a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.
Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores.
For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node.
For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.
b. Allocate RAM in Memory Size.
This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB).
If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
Editing Environment Settings
These settings configure optional environment variables for the container.
Click Add to open a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices to attach.
Select a device to attach to a container.
To attach a PCI passthrough device, click Add Device under PCI Passthrough on the device list to open the Add PCI Passthrough Device.
PCI passthrough assigns a physical PCI device, such as a network card or controller, directly to a VM, allowing it to function as if physically attached.
The Add PCI Passthrough Device screen lists the available physical PCI devices that can be attached to a container.
Use Search Devices or the Type dropdown to filter available devices.
The selected PCI device(s) must not be in use by the host or share an IOMMU group with any device the host requires.
Click Select to attach the selected device.
Managing Disks
Use the Disks widget to view the storage devices attached to the container, along with their associated paths.
Click Add to open the Add Disk screen for adding new disks to the container.
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select to either Edit or Delete the disk mount.
For VMs, use the Disks widget to manage the root disk size and I/O Bus.
The root disk stores the OS and serves as the boot disk for the VM.
Click Change to open the Change Root Disk Setup dialog.
Adding or Editing Disks
Click Add to open the Add Disk screen for adding new disks to the container.
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select Edit to edit the disk mount.
Enter or browse to select the host Source path for the disk.
For a new dataset, enter or browse to select the parent path.
Enter the Destination path to mount the disk in the container.
Click Save to apply changes.
Deleting Disk Mounts
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select Delete to delete the disk mount.
The Delete Item dialog asks for confirmation to delete the selected disk mount.
Click Confirm to activate the Continue button.
Click Continue to start the delete operation.
Managing Proxies
Use the Proxies widget to view the network proxy settings configured for the container.
It allows you to manage these settings, including adding, editing, or removing proxies.
Proxies allow you to forward network connections between the host and the container.
Click Confirm to activate the Continue button.
Click Continue to start the delete operation.
Accessing Containers
After selecting the container row in the table to populate the Details for Container widgets, locate the Tools widget.
You can open a shell session directly from this widget.
Click Shell to open a Container Shell session for command-line interaction with the container.
Virtual Machines
TrueNAS has built-in virtualization capabilities that allow running multiple operating systems on a single system, maximizing hardware utilization, and consolidating workloads.
A virtual machine (VM) is a software-based computer that runs inside your TrueNAS system, and appears as a separate physical machine to the operating system installed within it.
VMs use virtualized hardware components, including, network interfaces, storage volumes, graphics adapters, and other devices, providing complete isolation between different operating systems and applications.
VMs offer stronger isolation than containers but require more system resources, making them ideal for running full operating systems, legacy applications, or services that need dedicated environments.
What system resources do VMs require?
TrueNAS assigns a portion of system RAM and a new zvol to each VM.
While a VM is running, these resources are not available to the host computer or other VMs.
Virtualization requires:
x86 machine running a recent Linux kernel
Intel processor with VT (Virtualization Technology) extensions, OR
AMD processor with SVM extensions (AMD-V)
Users cannot create VMs unless the host system supports these features.
Users with multiple GPUs who wish to pass a GPU to a VM must first isolate a GPU for VM use.
One GPU is always required by TrueNAS.
Creating a Virtual Machine
Before creating a VM:
Obtain an installer .iso or image file for the OS you intend to install
Create a zvol on a storage pool that is available for both the virtual disk and the OS install file.
If the VM needs to access local NAS storage, you must create a network bridge to allow communication.
See Accessing TrueNAS Storage from a VM below for more information.
Using the Create Virtual Machine Wizard
To create a new VM, go to Virtual Machines and click Add to open the Create Virtual Machine wizard.
If you have not yet added a virtual machine to your system, clicking Add Virtual Machines opens the same wizard.
Configure the Operating System settings.
a. Select the operating system for the VM from the Guest Operating System dropdown list.
Compare the recommended specifications for the guest operating system with your available host system resources when allocating virtual CPUs, cores, threads, and memory size.
b. Enter a name for the VM.
c. (Optional) Enter a description for the VM. This can be any short text string describing how the VM is used or which operating system is configured.
d. (Optional) Change the default settings in System Clock and Boot Method to suit your use case.
Select UTC as the VM system time from the System Clock dropdown if you do not want to use the default Local setting.
Select UEFI from the Boot Method dropdown, unless using an older OS that requires Legacy BIOS.
e. (Optional) Select Enable Secure Boot to enable cryptographic verification of boot loaders, operating system kernels, and drivers during VM startup.
This security feature prevents unauthorized or malicious code from running during the boot process by checking digital signatures against trusted certificates.
Secure Boot is required for Windows 11 and some Linux distributions, and can be optional or unsupported for older operating systems.
Secure boot is only available from the VM creation wizard.
f. (Optional) Select Enable Trusted Platform Module (TPM) to provide a virtual TPM 2.0 device for the VM.
TPM provides hardware-based security functions, including secure key storage, cryptographic operations, and platform attestation.
This is required for Windows 11 and enhances security for other operating systems that support TPM.
g. (Optional) Select Start on Boot to start the VM after the system is restarted or boots up.
h. (Optional) Select Enable Display (VNC) to enable a Virtual Network Computing (VNC) remote connection for the VM.
Enable Display (VNC) shows the Bind and Password fields.
i. Select the IP address or option to use in Bind. Shows if you select Enable Display.
The Bind and Password fields display. If it is selected, to change the default IP address to use a specific address as the display network interface; otherwise, leave it set to 0.0.0.0.
The Bind list populates with any existing logical interfaces, such as static routes, configured on the system.
You cannot edit the Bind setting after saving the VM settings.
j. Enter a password to secure access to the virtual display in Password. The Password field shows if you select Enable Display.
The login screen for the display shows a credential entry field for this password.
When the Guest Operating System is set to Windows, Virtual CPUs shows the default value of 2.
The VM operating system might have operational or licensing restrictions on the number of CPUs.
Do not allocate too much memory to a VM. Activating a VM with all available memory allocated to it can slow the host system or prevent other VMs from starting.
Leave CPU Mode set to Custom if you want to select a CPU model.
Use Memory Size and Minimum Memory Size to specify how much RAM to dedicate to this VM.
To dedicate a fixed amount of RAM, enter a value (minimum 256 MiB) in the Memory Size field and leave Minimum Memory Size empty.
To allow for memory usage flexibility (sometimes called ballooning), define a specific value in the Minimum Memory Size field and a larger value in Memory Size.
The VM uses the Minimum Memory Size for normal operations but can dynamically allocate up to the defined Memory Size value in situations where the VM requires additional memory.
Reviewing available memory from within the VM typically shows the Minimum Memory Size.
When you select Import Image, browse to and select the source disk image file in Image Source.
The system automatically detects the image format (QCOW2, QED, RAW, VDI, VHDX, or VMDK).
Select the destination dataset in Zvol Location where the system creates the converted zvol.
Select either AHCI or VirtIO from the Select Disk Type dropdown list. We recommend using AHCI for Windows VMs.
When creating a new disk image, select the location for the new zvol from the Zvol Location dropdown list and enter a value in Size (Examples: 500KiB, 500M, and 2TB) to indicate the amount of space to allocate for the new zvol.
Select the network interface type from the Adapter Type dropdown list. Select Intel e82585 (e1000) as it offers a higher level of compatibility with most operating systems.
Select VirtIO if the guest operating system supports para-virtualized network drivers.
The VirtIO network interface requires a guest OS that supports VirtIO para-virtualized network drivers.
Select the network interface card to use from the Attach NIC dropdown list.
If the VM needs to access local NAS storage, attach a network bridge interface.
Click Next.
Configure Installation Media settings to upload the operating system you selected in step 1.
You can create the VM without an OS installed, then edit the VM to add it later.
To add the installation media, type the path or browse to select the location of the image file, and then select it.
To upload an iso, click Upload New Image File. Enter the path or browse to select the location of the file.
TrueNAS does not have a list of approved GPUs at this time, but TrueNAS does support various NVIDIA, Intel, and AMD GPUs.
Confirm your VM settings, then click Save.
Adding and Removing Devices
Using the Create Virtual Machine wizard configures at least one disk and NIC, and optionally a CD-ROM and display as part of the process, but you can add more devices to suit your use case.
Go to Virtual Machines, then click anywhere on a VM entry to expand it and show the options for the VM.
An active VM displays options for settings_ethernetDisplay and keyboard_arrow_rightSerial Shell connections.
When a display device is configured, remote clients can connect to VM display sessions.
If the display connection screen appears distorted, try adjusting the display device resolution.
Use the Running toggle or click stopStop to follow a standard procedure to do a clean shutdown of the running VM.
Click power_settings_newPower Off to halt and deactivate the VM, which is similar to unplugging a computer.
If the VM does not have a guest OS installed, the VM Running toggle and stopStop button might not function as expected.
The Running toggle and stopStop buttons send an ACPI power down command to the VM operating system, but since an OS is not installed, these commands time out.
Use the Power Off button instead.
Deleting a Virtual Machine
To delete a VM, first stop it if it is running, then click deleteDelete on the expanded VM details screen.
The Delete Virtual Machine dialog opens with options to control what data is removed.
Delete Virtual Machine Data removes the zvols and data associated with the VM. When selected, the dialog displays a list of disk and raw file devices to delete.
Deleting a VM with Delete Virtual Machine Data selected results in permanent data loss if the data is not backed up.
Do not select this option if you want to keep the VM zvols intact for use with another VM or for data recovery.
Force Delete ignores the VM status during the delete operation. Only select this if the VM is in an undefined state and cannot be stopped normally.
Enter the VM name in the confirmation field to enable the Delete button, then click Delete to remove the VM.
Installing an OS
After configuring the VM in TrueNAS and an OS .iso file is attached, start the VM and begin installing the operating system.
Some operating systems can require specific settings to function properly in a virtual machine.
For example, plain Debian can require advanced partitioning when installing the OS.
Refer to the documentation for your chosen operating system for tips and configuration instructions.
Installing Debian OS Example
Upload the Debian .iso to the TrueNAS system and attach it to the VM as a CD-ROM device.
This example uses Debian 12 and basic configuration recommendations.
Modify settings as needed to suit your use case.
Click Virtual Machines, then ADD to use the VM wizard.
Configure settings as needed.
Select the physical interface to associate with the VM.
Installation Media
The installation ISO is uploaded to local storage.
If the ISO is not uploaded, select Upload an installer image file.
Select a dataset to store the ISO, click Choose file, then click Upload. Wait for the upload to
complete.
GPU
Leave the default values.
Confirm Options
Verify the information is correct and then click Save.
After creating the VM, start it. Click on the VM to expand it, then use the **Running** toggle to start it.
Click Display to open a SPICE interface and see the Debian Graphical Installation screens.
Press Enter to start the Debian Graphical Install.
a. Enter your localization settings for Language, Location, and Keymap.
b. Debian automatically configures networking and assigns an IP address with DHCP.
If the network configuration fails, click Continue and do not configure the network yet.
c. Enter a name in Hostname.
d. Enter a Domain name.
e. Enter the root password and re-enter the root password.
f. Enter a name in New User.
g. Select the username for your account or accept the generated name.
h. Enter and re-enter the password for the user account.
j. Choose the time zone, Eastern in this case.
Detect and partition disks.
a. Select Guided - use entire disk to partition.
b. Select the available disk.
c. Select All files in one partition (recommended for new users).
d. Select Finish partitioning and write changes to disk.
e. Select Yes to Write the changes to disks?.
Install the base system:
a. Select No to the question Scan extra installation media.
b. Select Yes when asked Continue without a network mirror.
Install software packages:
a. Select No when asked Participate in the package usage survey.
b. Select Standard system utilities.
c. Click Continue when the installation finishes.
After the Debian installation finishes, close the display window.
Remove the device or edit the device order.
In the expanded section for the VM, click Power Off to stop the new VM.
a. Click Devices.
b. Remove the CD-ROM device containing the install media or edit the device order to boot from the Disk device.
To remove the CD-ROM from the devices, click the and select Delete.
Click Delete Device.
To edit the device boot order, click the and select Edit.
Change the CD-ROM Device Order to a value greater than that of the existing Disk device, such as 1005.
Click Save.
Return to the Virtual Machines screen and expand the new VM again.
Click Start, then click Display.
What if GRUB does not start automatically?
If GRUB does not run when you start the VM, enter the following commands after each start.
At the shell prompt:
Enter FS0: and press Enter.
Enter cd EFI and press Enter.
Enter cd Debian and press Enter.
Enter grubx64.efi and press Enter.
To ensure it starts automatically, create the startup.nsh file at the root directory on the VM. To create the file:
Go to the Shell.
At the shell prompt, enter edit startup.nsh.
In the editor, enter:
a. Enter FS0: and press Enter.
b. Enter cd EFI and press Enter.
c. Enter cd Debian and press Enter.
d. Enter grubx64.efi and press Enter.
Use the Control+s keys (Command+s for Mac OS) then press Enter.
Use the Control+q keys to quit.
Close the display window
To test if it boots up on startup:
a. Power off the VM.
b. Click Start.
c. Click Display.
d. Log into your Debian VM.
Configuring Virtual Machine Network Access
Configure VM network settings during or after installation of the guest OS.
To communicate with a VM from other parts of your local network, use the IP address configured or assigned by DHCP within the VM.
To confirm network connectivity, send a ping to and from the VM and other nodes on your local network.
Debian OS Example
Open a terminal in the Debian VM.
Enter ip addr and record the address.
Enter ping followed by the known IP or hostname of another client on the network, that is not your TrueNAS host.
Confirm the ping is successful.
To confirm internet access, you can ping a known web server, such as ping google.com.
Log in to another client on the network and ping the IP address of your new VM.
Confirm the ping is successful.
Accessing TrueNAS Storage From a VM
By default, VMs are unable to communicate directly with the host NAS.
If you want to access your TrueNAS SCALE directories from a VM, for example, to connect to a TrueNAS data share, you have multiple options.
If your system has more than one physical interface, you can assign your VMs to a NIC other than the primary one your TrueNAS server uses.
This method makes communication more flexible but does not offer the potential speed of a bridge.
If your system has only one physical interface, create a bridge interface for the VM to use.
Stop all existing apps, VMs, and services using the current interface, edit the interface and VMs, create the bridge, and add the bridge to the VM device.
See Accessing NAS from VM for more information.
Migrating Legacy VMs to Virtual Machines
The storage volumes (zvols) for virtual machines created using the Instances screen in TrueNAS 25.04.0 or 25.04.1 (renamed the Containers screen in 25.04.2 and later) can migrate to new VMs created using the Virtual Machines screen in 25.04.2 and later.
The process involves:
Identifying the hidden storage volumes (zvols) associated with the Legacy VMs.
Determining which zvol contains the actual VM data by checking the volume size.
Renaming (and moving) the zvols to a new dataset where they can be seen and used by a new VM.
(Highly Recommended) Configuring zvol properties to match those of natively-created VM zvols.
Creating a new VM and selecting the migrated zvol as the storage volume.
Before You Begin
Before beginning the process:
Identify the zvol names associated with the legacy VM.
Take a recursive snapshot or back up the pool configured for legacy VMs.
Using ZFS commands to rename and move an existing zvol can damage data stored in the volume.
Having a backup is a critical step to restoring data if something goes wrong in the process.
Verify the VM is operational and the network is functioning as expected. One way to do this is to verify it has Internet access.
Then stop the VM before you upgrade to the next release.
Identify the dataset where you want to move the volume.
We do not recommend renaming or moving the volume more than once, as it increases the risk of possible data corruption or loss.
You do not need to log in as the root user if the logged-in admin user has permission to use sudo commands.
If not, go to Credentials > Users, edit the user to allow sudo commands, or verify the root user has an active password to switch to this user when entering commands in the Shell screen.
Migrating a Zvol for a Legacy VM
This procedure applies to the zvol for a legacy VM that has data you want to preserve and access from a new VM using the Virtual Machines screens in later releases.
Go to Instances (or Containers), click on Configuration, and then Manage Volumes to open the Volumes window.
The Volumes window lists all legacy VMs and associated storage volumes (zvols).
Record the volume name or take a screenshot of the information to refer to later when entering commands in the Shell screen. Zvol names are similar to the VM name but not identical.
Optionally, you can highlight all the listed information and copy/paste it into a text file, but this is not necessary.
While on the Instances screen, verify the VM is operational and the network is operating as expected.
One way to verify external network access is to check Internet access. Stop the VM before upgrading.
Repeat for each zvol that you plan to migrate into a new VM in later releases.
Go to Datasets, locate the pool associated with instances (containers), and take a recursive snapshot to back up all legacy VM zvols.
These zvols are in the hidden .ix-virt directory created in the pool instances uses, selected when you configure the feature.
To verify the pool, you can go to Containers > Configure > Global Settings and look at the Pool setting.
Go to System > Update, and update to the next publicly available maintenance or major version release.
Follow the release migration paths outlined in the version release notes or the Software Releases article.
After updating to a 25.04.x release or later, VMs created using Instances screens show on the Containers screen, and are stopped.
Some VMs experience various issues like network connectivity, or are stopped and do not start.
Refer to the troubleshooting tips below for more information. 25.10 releases correct some issues encountered in 25.04.2.4 VMs that are migrated.
After upgrading to a release that shows the Virtual Machines screen and the Containers option:
Go to Containers to see which VMs are listed, then click Configuration, and then Manage Volumes to open the Volumes window.
Take a screenshot of the volumes listed, or copy/paste the volumes and VM information into a text file to use later in this procedure.
Zvol names are similar to the VM but not identical. Volume names are used in step 6 below.
Go to System > Shell. Exit to the Linux prompt for the system.
Note: This is where the logged-in admin user needs sudo permissions, or where the root user must have a password configured to enter the following commands to find, rename/move, and verify each instance zvol is properly configured.
Experienced users can switch to the root user if the root user has a password assigned and enabled.
Enter the following commands at the Linux system prompt:
Storage conventions differ based on VM history:
Migrated VMs (from pre-Incus TrueNAS) use custom/default_* zvols for actual VM data
VMs created in 25.04.0 or 25.04.1 use .block zvols for actual VM data
Small .block files (56K) are stubs and should not be migrated
a. Locate the hidden zvols for the legacy VMs, by entering:
sudo zfs list -t volume -r -d 10 poolname
Where:
-d 10 shows datasets up to 10 levels deep
poolname is the name of the pool associated with the legacy VMs.
If you have multiple pools associated with the legacy VMs, repeat this command with the name of that pool to show hidden zvols in that pool.
The .ix-virt directory contains the zvols used in legacy VMs. Check the USED or REFER columns to identify the actual VM storage:
For migrated VMs: Use the custom/default_* zvol (typically several GB or more)
For VMs created in 25.04.0 or 25.04.1: Use the .block zvol that shows significant storage usage (not 56K stubs)
Ignore: Stub .block files showing only 56K, and zvols not in the .ix-virt directory
The output includes other zvols in the pool if your system has non-instance VMs configured in the pool name entered in the command.
Example Command Output
Example showing migrated VMs (custom/ zvols with actual data):
re-minir-102% sudo zfs list -t volume -r tank
NAME USED AVAIL REFER MOUNTPOINT
tank/.ix-virt/custom/default_vm2410linux-8cppg 40.6G 1.66T 40.6G - ← Migrate this (actual data)
tank/.ix-virt/custom/default_vm2410win-mvqznj 40.2G 1.66T 40.2G - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/vm2410linux.block 56K 1.66T 56K - ← Stub (ignore)
tank/.ix-virt/virtual-machines/vm2410win.block 56K 1.66T 56K - ← Stub (ignore)
tank/vms/previously-migrated 35.1G 1.70T 35.1G -
Example showing VMs created in 25.04.0/25.04.1 (.block zvols with actual data):
qe-realmini% sudo zfs list -t volume -r tank
NAME USED AVAIL REFER MOUNTPOINT
tank/.ix-virt/virtual-machines/TrueNAS.block 6.98G 2.55T 6.98G - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/fdsa.block 25.9M 2.55T 248M - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/debian.block 56K 2.55T 56K - ← Stub (ignore)
tank/.ix-virt/virtual-machines/mint.block 56K 2.55T 56K - ← Stub (ignore)
In the examples above:
Zvols with custom/default_* in the path showing significant storage (40+GB) are migrated VMs to migrate
Zvols with .block extension showing significant storage (6.98G, 25.9M) are native Incus VMs to migrate
Small .block files at 56K are stubs and should be ignored
After successfully migrating and confirming functionality of all VMs, the remaining stub .block files (56K) in .ix-virt/virtual-machines/ can optionally be deleted to clean up the hidden dataset.
b. Rename (and move) each volume in the .ix-virt directory to a new location where you can select it when configuring a new VM.
Repeat for each volume you want to migrate to a new VM. Do not rename or move stub .block files (56K).
default_debian1-urec9f or TrueNAS.block is the name of a hidden zvol in the examples, and the name given to the migrated zvol.
We do not recommend renaming the migrated zvol to minimize potential issues with the migration process.
For .block zvols, you can keep or remove the .block extension in the target name.
vms is the dataset in the examples as the location to store the migrated zvols for VMs. Change this to the location on your system.
This renames and moves it to the specified location, and returns to the system Linux prompt.
To verify the zvol moved, enter the sudo zfs list -t volume -r tank command again. The output should show the zvol in the new location.
c. (Highly Recommended) Set zvol properties to match those of natively-created VM zvols.
Enter the following command for each zvol you migrated:
For migrated VMs (custom/ zvols):
sudo zfs set volmode=default primarycache=all secondarycache=all tank/vms/default_debian1-urec9f
For VMs created in 25.04.0 or 25.04.1 (.block zvols):
sudo zfs set volmode=default primarycache=all secondarycache=all tank/vms/TrueNAS.block
Where:
tank is the pool name.
vms is the dataset where the zvol is stored.
default_debian1-urec9f or TrueNAS.block is the name of the zvol
This command sets the volume properties to match those used by zvols created through the Virtual Machines screen, ensuring optimal performance and behavior.
Containers VMs used different property settings that are not optimal for virtual machine workloads.
After completing the commands listed above for each zvol you want to migrate, go to Datasets and verify all volumes you migrated show on the screen.
Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated.
Go to Virtual Machines, click on Add to open the Create Virtual Machine wizard.
For more information or details on using the Create Virtual Machine wizard, see Creating a Virtual Machine.
a. Complete the first screen by entering a name for the new VM, select the operating system used by the legacy VM, enter a brief description, and then if using the Bind setting, enter a password. Click Next.
b. Configure the CPU and Memory settings, and then click Next.
c. On the Disks wizard screen, select Use existing disk image, click in Select Existing Zvol and select the volume moved from the legacy VM.
If you move multiple zvols, refer to the screenshot or text file with the VM/zvol list to select the correct zvol for this new VM.
d. Click Next until you get to the confirmation screen, then click Create to add the VM.
After adding the new VM, click on the row to expand it, and click Devices.
Click Edit for the Disk device, and enter 1000 in the Device Order field.
Setting the disk to 1000 makes the disk device the first in the boot order for the VM.
Setting the disk to first in boot order over a CD-ROM device with an OS on it, if added when creating the VM, prevents the volume from being overwritten by booting from that CD-ROM device.
Click Save.
Return to the Virtual Machines screen, click on the VM to expand it, then use the Running toggle to start it and verify it opens as expected and has network access.
Preparing to Upgrade to TrueNAS 27
Legacy virtual machines created using the Instances screen in 25.04.0 and 25.04.1 are still shown on the Containers screen in 25.10.
TrueNAS 27 removes them from the Containers screen entirely.
No migration tool, wizard, or notification exists to move them automatically.
Complete the following steps while still running TrueNAS 25.10.
None of these steps are available after upgrading to TrueNAS 27.
TrueNAS does not delete a legacy VM disk during the upgrade to 27.
The disk remains on the pool, but TrueNAS does not preserve the VM configuration, UEFI variables, or Trusted Platform Module (TPM) state.
Go to Containers, and identify which instances are VMs.
Only VMs require this procedure. Containers do not.
See Containers for which systems migrate containers automatically.
Open each VM and record the CPU count, memory, disk size, network interface, MAC address, guest operating system, and secure boot setting.
A screenshot of the VM configuration is sufficient. You need these values to re-create the VM after upgrading.
Go to System > Shell and record the zvol names and sizes.
sudo zfs list -t volume -r -o name,volsize,used poolname/.ix-virt
Where poolname is the name of the pool used by the legacy VM.
Each VM root disk is poolname/.ix-virt/virtual-machines/VMNAME.block, where VMNAME is the name of the VM, unless that entry shows a USED value of about 56K.
A 56K USED value means the entry is an empty placeholder for a VM whose disk was imported from an existing image file. For this VM, record the default_-prefixed entry under poolname/.ix-virt/custom/ instead.
Start each VM, confirm it operates and has network access, then stop it.
Go to Datasets, select the pool used by instances, and take a recursive snapshot.
The snapshot preserves a copy of the data. Recovering from the snapshot requires renaming datasets back by hand. There is no single rollback that undoes the procedure in Migrating a Legacy VM Disk in the TrueNAS 27 documentation.
Upgrade to TrueNAS 27.
After the upgrade, complete Migrating a Legacy VM Disk in the TrueNAS 27 documentation to re-create the VM and attach the disk.
Using the Create Virtual Machine wizard configures at least one disk and NIC, and optionally a CD-ROM and display as part of the process, but you can add more devices to suit your use case.
Go to Virtual Machines, then click anywhere on a VM entry to expand it and show the options for the VM.
A virtual machine attempts to boot from devices according to the Device Order, starting with 1000, then ascending.
A CD-ROM device allows booting a VM from a CD-ROM image like an installation CD.
The CD image must be available in the system storage.
A Display device provides remote clients with a way to connect to VM display sessions.
Before You Begin
Before adding, editing, or deleting a VM device, stop the VM if it is running.
Click the Running toggle to stop a VM, or click on the VM row and use the Stop button.
Clicking the Running toggle for a stopped VM restarts it, or you can click on the VM row to expand it, and then click on the Restart button.
To access the devices for a VM, click on the VM row on the Virtual Machines screen to expand the VM, then click on Devices to open the Devices screen showing the devices for the selected VM.
Click Add to create a new device>
To edit an existing device, click on the more_vert at the right of each device row, click Edit to open the Edit Device screen.
Click Delete to open a delete confirmation dialog.
Editing a Device
After selecting the VM row on the Virtual Machines list and clicking on Devices to open the Devices screen, the devices configured for that selected VM show.
Devices added when you create the VM show by default. You can add additional or edit existing devices.
Click on the more_vert at the right of the device row.
Options for each device show. A disk device shows four options: Edit, Delete, Details, and Export to Image.
Other device types do not include the export option.
Click Edit* to open the Edit Device screen.
The screen settings change based on the device type selected.
For example, when editing a disk (example provided below), you can change the type of virtual hard disk, the storage volume to use, or change the boot order for the device.
Stop the VM on the Virtual Machines screen, click on Devices to open the Devices screen for that VM, and then click Edit.
The procedure below describes editing a disk device.
Steps below are optional. Change them based on your use case.
(Optional) Select the zvol created when setting up the VM on the Zvol dropdown list. The field populates with the path to the selected zvol.
(Optional) Select the type of hard disk emulation from the Mode dropdown list. The options are AHCI and VirtIO.
Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM has support for VirtIO disk devices.
(Optional) Specify the disk sector size in bytes in Disk Sector Size.
Leave set to Default if you want to leave the sector size unset and use the ZFS volume value.
Select either 512 or 4096 byte values from the dropdown list to specify a logical and physical sector size.
(Optional) Enter a number that reflects the boot order or priority level in Device Order.
Setting this value to 1000 puts the disk device in the boot order first position.
When first installing or changing an OS added to the CD-ROM device, the CD-ROM is assigned 1000 to boot up from and install an OS.
After installing the OS, change the boot order for the CD-ROM to a lower boot order so you do not keep booting into an installer and to run the OS in the VM.
The lower the number, the higher the priority in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen to return to the Virtual Machines screen. Click on the VM to expand it and restart it.
To edit display type or bind address after creating a VM
Go to Virtual Machines, locate the VM you want to modify, and click on it to expand it.
Click device_hubDevices to open the Devices screen associated with the VM.
Click the more_vert icon at the right of the display device and click on Edit to open the Edit Device screen for that display device.
Select the IP address or other option on the Bind dropdown.
You can assign a port number to your display device or use the default port number associated with the device.
You can add a second display device to have a VNC and SPICE display associated with the VM, but only one display device can be active at one time.
Adding a second display device assigns a different default port number to the second display device.
Deleting a Device
Deleting a device removes it from the list of available devices for the selected VM.
To delete a device:
Stop the VM if it is running, then click Devices to open the Devices screen showing the devices for the selected VM.
Click on the more_vert icon to the right of the device and then Delete to open the delete confirmation dialog for that display device.
The dialog shows the name or identifier for the selected device. The example below shows undefined 8 as the name.
Select Force Delete to force the system to delete the device (for example, device is a CD-ROM).
When deleting a disk, it forces the system to delete the zvol even if other devices or services are using it or are affiliated with the zvol device.
Click Delete Device.
Changing the Device Order
Changing the device order moves the device up or down in the boot order when the VM or system is restarted.
A VM attempts to boot from devices according to the Device Order, starting with 1000, then ascending.
After stopping the VM and clicking Devices to open the Devices screen:
Click on the more_vert at the right of the device row, then click on Edit to open the Edit Device screen.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence. 1000 is the first position in the boot order.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a CD-ROM Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select CD-ROM on the Device Type dropdown list.
Enter or browse to select the mount path to the CD-ROM device.
Click on the to the left of /mnt to expand or collapse the directory tree.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a NIC Device Type
After stopping the VM and clicking Devices to open the Devices screen:
Click Add to open the Add Device screen.
Select NIC on the Device Type dropdown list to show the network interface card settings.
Select the adapter type from the Adapter Type dropdown list.
Choose Intel e82585 (e1000) for maximum compatibility with most operating systems.
If the guest OS supports VirtIO paravirtualized network drivers, choose VirtIO for better performance.
Click Generate to have TrueNAS populate MAC Address with a new random MAC address to replace the default random address, or enter your own custom address.
Select a physical interface on your TrueNAS system from the NIC To Attach dropdown list.
(Optional) Select Trust Guest Filters to allow the virtual server to change its MAC address and join multicast groups.
This is required for the IPv6 Neighbor Discovery Protocol (NDP).
Setting this attribute has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address. Determine your network setup needs before setting this attribute.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Add a Disk Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select Disk from the Device Type dropdown list.
Select the path to the zvol created when setting up the VM on the Zvol dropdown list.
Select the hard disk emulation type from the Mode dropdown list.
Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM supports VirtIO disk devices.
Select the sector size in bytes in Disk Sector Size.
Leave set to Default or select either 512 or 4096 from the dropdown list.
Default uses the ZFS volume values.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Exporting a Disk to an Image
Use this function to convert a VM disk (zvol) to a portable disk image file.
Exported images can be imported into other VMs, transferred to different systems, or used as backups.
After stopping the VM and clicking Devices to open the Devices screen:
Click on the more_vert icon to the right of the disk device and then click Export to Image to open the Export Disk to Image window.
Browse to select the dataset/directory using the file browser. Click on the dataset/directory to select it and populate the mount path field.
Select the image format from the Image Format dropdown list.
Available formats include QCOW2 (QEMU Copy On Write), QED (QEMU Enhanced Disk), RAW (Raw Disk Image), VDI (VirtualBox Disk Image), VHDX (Hyper-V Virtual Hard Disk), and VMDK (VMware Virtual Machine Disk).
The system automatically adds the appropriate file extension to the name in Image Name.
Click Export. The system saves the disk as an image in the location you specified in Destination Directory.
Adding a PCI Passthrough Device
Depending upon the type of device installed in your system, you might see a warning: PCI device does not have a reset mechanism defined.
You may experience inconsistent or degraded behavior when starting or stopping the VM.
Determine if you want to proceed with this action in such an instance.
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select PCI Passthrough Device from the Device Type dropdown list.
Enter a value in PCI Passthrough Device using the format of bus#/slot#/fcn#.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a USB Passthrough Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select USB Passthrough Device from the Device Type dropdown list to configure the USB passthrough device.
Select the Controller Type from the dropdown list.
Select the hub controller type from the Device dropdown list.
If the type is not listed, select Specify custom, then enter the Vendor ID and Product ID.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a Display Device
Display devices have a 60-second inactivity timeout.
If the VM display session appears unresponsive, try refreshing the browser tab.
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select Display from the Device Type dropdown list to configure a new display device.
Select the Display Device option from the dropdown list.
TrueNAS allows a VM to have two different display devices: a VNC display device added through the VM creation wizard if the Enable Display (VNC) option is selected, and a second SPICE display device added to the VM using the Add Device screen with Device Type set to display.
If you created the VM without the display, the Display Type dropdown list shows the VNC and SPICE options.
Select the display type on the dropdown list. (VNC is recommended).
To add a second display device, repeat this procedure and select SPICE (the only option for the second display device).
Enter a fixed port number in Port.
To allow TrueNAS to assign the port after restarting the VM, set the value to zero (leave the field empty).
Specify the display session settings:
a. Select the screen resolution to use for the display from the Resolution dropdown.
b. Select an IP address for the display device to use in Bind. The default is 0.0.0.0.
c. Enter a unique password for the display device to securely access the VM.
Select Web Interface to allow access to the VNC web interface.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Reporting
TrueNAS has a built-in reporting engine that provides helpful graphs and information about the system.
TrueNAS uses Netdata to gather metrics, create visualizations, and provide reporting statistics.
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.
Reporting data is saved to permit viewing and monitoring usage trends over time.
This data is preserved across system upgrades and restarts.
TrueCommand offers enhanced features for reporting like creating custom graphs and comparing utilization across multiple systems.
Interacting with Graphs
Click on and drag a certain range of the graph to expand the information displayed in that selected area in the Graph.
Click on the icon to zoom in on the graph.
Click on the icon to zoom out on the graph.
Click the to move the graph forward.
Click the to move the graph backward.
Configuring Reporting Exporters
You can configure TrueNAS to export Netdata information to any time-series database, reporting cloud service or application installed on a server.
For example, Graphite, Grafana, etc., installed on a server or use their cloud service.
Creating reporting exporters enables TrueNAS to send Netdata data reporting metrics, formatted as a JSON object, to another reporting entity.
For more information on exporting Netdata records to other servers or services, refer to the Netdata exporting reference guide.
Graphite is a monitoring tool available as an application you can deploy on a server or use their cloud service.
It stores and renders time-series data based on a plaintext database.
Netdata exports data reporting metrics to Graphite in the format prefix.hostname.chart.dimension.
For additional information, see the Netdata Graphite exporting guide.
Adding a Reporting Exporter
To configure a reporting exporter in TrueNAS, you need the:
IP address of the reporting service or server.
If using another TrueNAS system with a data reporting application, this is the IP address of the TrueNAS running the application.
Port number the reporting service listens on.
If using another TrueNAS system with a reporting application, this is the port number the TrueNAS system listens on (port:80)
Go to Reporting and click on Exporters to open the Reporting Exporters screen.
Any reporting exporters configured on the system display on the Reporting Exporters screen.
Select Enable to send reporting metrics to the configured exporter instance.
Clearing the checkmark disables the exporter without removing configuration.
Enter the IP address for the data collection server or cloud service.
Enter the port number the report collecting server, etc. listens on.
Enter the file hierarchy structure, or where in the collecting server, etc. to send the data.
First enter the top-level in Prefix and then the data collection folder in the Namespace field.
For example, entering DF in Prefix and test in Namespace creates two folders in Graphite with DF as the parent to Test.
You can accept the defaults for all other settings, or enter configuration settings to match your use case.
Click Save.
To view the Graphite web UI, enter the IPaddress:Port# of the system hosting the application.
TrueNAS can now export the data records as Graphite-formatted JSON objects to the other report collection and processing application, service, or servers.
TrueNAS also populates the exporter screen with default settings.
To view these settings, click Edit on the row for the exporter.
System Settings
TrueNAS system management options are collected in this section of the UI and organized into a few different screens:
Update controls when the system applies a new version.
There are options to download and install an update, have the system check daily and stage updates, or apply a manual update file to the system.
General Settings shows system details and has basic, less intrusive management options, including web interface access, and localization of the UI and keyboard.
This is also where users can download a system debug, input an Enterprise license, or create a software bug ticket.
Advanced Settings contains options that are more central to the system configuration or meant for advanced users.
Specific options include configuring the system console, log, and dataset pool, managing sessions, adding custom system controls, kernel-level settings, scheduled scripting or commands, global two-factor authentication, NTP server connections, and determining any isolated GPU devices.
TrueNAS Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration.
Enterprise-licensed HA systems have access to the failover settings located on this screen.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Boot lists each ZFS boot environment stored on the system.
These restore the system to a previous version or a specific point in time.
Services displays each system component that runs continuously in the background.
These typically control data sharing or other external access to the system.
Individual services have their own configuration screens, start and stop buttons, and can be set to start automatically.
Shell allows users to use the Linux command-line interface (CLI) directly in the web UI.
Alert Settings allows users to configure Alert Services and to adjust the threshold and frequency of various alert types. See Alerts Settings Screens for more information.
Audit allows users to review auditing logs of all actions performed by a session, user, or service (SMB, middleware).
Enclosure appears when the system is attached to compatible TrueNAS hardware.
This is a visual representation of the system with additional details about disks and other physical hardware components.
Contents
Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.
Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.
Advanced Settings: Tutorials for configuring advanced system settings in TrueNAS.
Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.
Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.
Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.
Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.
Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.
FTP: Provides instructions on configuring the FTP service including storage, user, and access permissions.
NFS: Provides information on configuring NFS service in TrueNAS.
SMB: Provides instructions on configuring the SMB service in TrueNAS.
SNMP: Provides information on configuring SNMP service in TrueNAS.
SSH: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.
UPS: Provides information on configuring UPS service in TrueNAS.
Using Shell: Provides information on using the TrueNAS shell.
Using Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.
Updating TrueNAS
TrueNAS has several software branches (linear update paths) known as trains.
Update profiles offer updates to the release running on your system based on specific use cases.
Some profiles are not available or recommended for Enterprise customers.
TrueNAS systems are shipped with the profile set for the user based on their use case.
The Update screen shows the installed version, other installation or update options, and user profiles.
Some users can select a different profile option from the Select and update profile dropdown list.
Software Update Paths
When upgrading TrueNAS to a new major version, follow the upgrade path of major versions until the system is on the desired major version release.
For more information on the upgrade path from one version to the next, see Software Releases.
See the Software Status page for the latest recommendations for software usage.
Do not change to a prerelease or nightly release unless you intend to keep the system permanently on early versions and are not storing critical data on it.
The Developer update profile allows using a non-production train in active development, but be prepared to experience bugs or other problems.
Testers are encouraged to submit bug reports with debug files.
For information on how to file an issue ticket, see Filing an Issue Ticket in TrueNAS.
The TrueNAS Update screen provides users with automatic and manual update methods.
We recommend updating TrueNAS when the system is idle (no clients connected, no disk activity, etc.).
The system restarts after an upgrade.
Update during scheduled maintenance times to avoid disrupting user activities.
All auxiliary parameters are subject to change between major versions of TrueNAS due to security and development issues.
We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
Automatically Updating
If an update is available, it shows in the Update Available section on the Update screen.
Select Export Password Secret Seed, then click Save Configuration.
Why should I save the secret seed?
The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database.
TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields.
Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps.
Always select the Export Password Secret Seed option when you download the system config file.
What happens if I do not save the secret seed?
You can still log into the web UI with your existing password.
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.
TrueNAS disables SMB authentication for all local user accounts.
To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password.
TrueNAS requires a new password before it re-enables SMB authentication for that account.
TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs.
It empties the values of others, such as SED passwords, certificate private keys, and service passwords.
Reconfigure these settings after you log in.
After you log in, recheck all system settings to verify the configurations are correct.
Then test the system to verify it works as desired.
When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.
Always save the secret seed with the system configuration file after you change the system configuration.
This gives you a current backup copy to use if you need it.
TrueNAS downloads the configuration and the update files, then starts the installation.
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.
Manually Updating
If the system detects an available update, it and the Install Update button show below the current release running on the system.
Click Install Update. The Save configuration settings from this machine before updating? window opens.
Leave Export Password Secret Seed selected, and then click Save Configuration.
TrueNAS Manual update files are available from the TrueNAS Download page website.
If using the Developer update profile and a nightly build, you can use the manual update option to update the release running on your system if an update is not shown in the Update Available section of the Update screen.
Click Install to the right of Manual Update.
The Save configuration settings from this machine before updating? window opens.
Click Export Password Secret Seed, then click Save Configuration.
The Manual Update screen opens.
Click Choose File to locate the update file on your system.
Select a temporary location to store the update file.
Select Memory Device or the mount location from the dropdown list to keep a copy in the server.
Click Apply Update to start the update process. A status window opens and displays the installation progress.
When complete, the system automatically Restarts.
Update Progress
When a system update starts, appears in the toolbar at the top of the UI.
Click the icon to see the current status of the update and which TrueNAS administrative account initiated the update.
This procedure only applies to TrueNAS Enterprise (HA) systems.
If attempting to migrate from FreeBSD- to Linux-based TrueNAS versions, see TrueNAS Migrations.
Installing, upgrading, or making some changes to TrueNAS on High Availability (HA) systems is complicated and should be guided by Enterprise-level support.
Contact TrueNAS Enterprise Support for assistance whenever attempting to install or make some changes to TrueNAS on Enterprise HA hardware.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
If the system does not have an administrative user account, create the admin user as part of this procedure.
Take a screenshot of the license information found on the Support widget on the System > General Settings screen. You use this to verify the license after the update.
To update your Enterprise (HA) system to the latest TrueNAS release, log into the TrueNAS UI using the virtual IP (VIP) address and then:
Check for updates. Go to the main Dashboard and click Check for Updates on the System Information widget for the active controller.
This opens the System > Update screen. If an update is available for the Update Profile selected, it shows on this screen.
Click Install Update.
Save the password secret seed and configuration settings to a secure location.
The Save configuration settings window opens.
Leave Export Password Secret Seed selected, then click Save Configuration.
The system downloads the file with sensitive system data. Keep this file in a secure location.
Why should I save the secret seed?
The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database.
TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields.
Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps.
Always select the Export Password Secret Seed option when you download the system config file.
What happens if I do not save the secret seed?
You can still log into the web UI with your existing password.
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.
TrueNAS disables SMB authentication for all local user accounts.
To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password.
TrueNAS requires a new password before it re-enables SMB authentication for that account.
TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs.
It empties the values of others, such as SED passwords, certificate private keys, and service passwords.
Reconfigure these settings after you log in.
After you log in, recheck all system settings to verify the configurations are correct.
Then test the system to verify it works as desired.
When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.
Always save the secret seed with the system configuration file after you change the system configuration.
This gives you a current backup copy to use if you need it.
Click Install to begin the installation, click Cancel to return to the Update screen.
If manually updating your system:
click Install to the right of Manual Update.
Save the secret seed, and configuration file to a secure location, and click Save Configuration to show the Manual Install screen.
Click Choose File and use the file browser to select the update file downloaded to your system.
Click Apply Update to start the update process.
After the system finishes updating it restarts.
After the system sign-in screen shows:
Sign in to the TrueNAS UI. If using root to sign in, create the admin account (see step 3).
If using admin, continue to the next step.
Verify the system license after the update. Go to System > General Settings.
Verify the license information in the screenshot of the Support widget you took before the update matches the information on the Support widget after updating the system.
Verify the admin user settings, or if not created, create the admin user account now.
Before adding a new admin user, create a dataset for home directories if you do not have one already set up.
If editing an existing admin user, select the user on the Credentials > Users screen and click Edit.
If you want the admin account to have the ability to execute sudo commands in an SSH session, set Allow Access to both TrueNAS Access and SSH Access, assign the new admin user the Full Admin role.
Add the SSH pubic key, enter and confirm the password, then go to Sudo Commands to set the option for sudo access you want to allow.
Verify Shell is set to bash if you want to give the admin user the ability to execute commands in Shell.
To set a location where the admin user can save or browse files, and then select the dataset path in Home Directory.
If set to the default /nonexistent files are not saved for this user.
Click Save to create the user or save changes to the existing user.
Verify the admin user can log in to the UI.
a. Log out of the UI.
b. Enter the admin user credentials in the sign-in splash screen.
After validating access to the TrueNAS UI using the admin credentials, disable the root user password.
Go to Credentials > User, select the root user, then click Edit. Select Dissable Password and click Save.
The TrueNAS General Settings provide options to configure support, file a ticket or provide feedback on the UI or a feature, download a system debug, configure a graphic user interface (GUI), set UI and keyboard languages, and add system email.
The Support widget shows information about the TrueNAS version and system hardware.
Links to the open-source TrueNAS documentation, community forums, and official Enterprise licensing are provided.
Add License opens a screen where you can paste a copy of your TrueNAS Enterprise license (details).
After adding a license, the option changes to Update License.
Save Debug starts a download of the system debug file.
File Ticket opens the Send Feedback window with two options: Rate this page and Report a bug.
These options allow you to report a system bug or to send TrueNAS feedback on the UI and rate a screen. Feedback goes to the TrueNAS development team.
An icon shows on new UI feature screens where TrueNAS is asking you to send feedback, and it allow you to capture a screenshot of that screen.
Proactive Support shows for Enterprise-licensed systems.
It opens the Proactive Support window, where you enter configuration settings to set up proactive support for an Enterprise system.
For information on configuring proactive support, see Adding a License and Proactive Support.
Sending Feedback
TrueNAS provides two feedback options: one to rate a UI screen and the other to report a problem encountered with the system.
Some screens show the option to rate the screen.
Click on the Send Feedback icon to open the feedback window.
The window allows you to select the Report a bug option to open a Jira ticket.
To send feedback, go to System > General Settings, and click File Ticket on the Support widget.
The File Ticket option on Enterprise systems shows two options: File Ticket and Proactvie Support. Select File Ticket to open the Send Feedback window.
Rating a UI Screen
Select Rate this page to show the options to send feedback on a UI page, add comments, add a screenshot or additional images, or click the link to go to the TrueNAS forum where you can vote for new features on the community forum, report a problem, or suggest improvements directly to the TrueNAS development team.
Select Report a bug to show the options to open an engineering ticket and submit it directly to the TrueNAS development team when a TrueNAS screen or feature is not working as intended.
Submitting a bug report requires a free Atlassian account.
Select Report a bug to see the fields to create a Jira engineering ticket.
For example, reporting a bug where a middleware error and traceback occurred while saving a configuration change. You must have a Jira account to submit a ticket.
Enter a descriptive summary in the Subject.
For example, if an application does not update after clicking the update option for the app and you get an error message or traceback after attempting the update, enter XYZ application fails to update with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
Clicked on the XYZ app row, stopped the app, clicked Update, but the update failed, and showed the following traceback message (include the traceback text).
My system is running on TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug is enabled by default. You can also include screenshot files, which can speed up the issue resolution.
Attach Debug is selected by default. This uploads the debug file to a Private Attachment ticket to protect sensitive data in the log files, and it links this ticket to the Jira report ticket. Only authorized TrueNAS developers can access the debug file.
To attach a screenshot of the current page, select Take screenshot of the current page, or Attach additional images, which opens a file browser where you can select log.txt, image, or video files to attach to the ticket.
Before using this form, take screenshots of the screen, copy the traceback or other error messages to a text file, copy a log into a text file, or create any other file to attach.
After opening this form, attach those files by selecting Attach additional images and clicking Choose File opens a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Filling out the entire form with precise details and accurate contact information ensures a prompt response from the TrueNAS Customer Support team.
Configuring GUI Options
The GUI widget allows users to configure the TrueNAS web interface address. Click Settings on the widget to open the GUI Settings configuration screen.
The system uses a self-signed certificate to enable encrypted web interface connections.
To change the default certificate, create or import a certificate as described in Managing Certificates to add it to the dropdown list of certificates available on the system. Select the certificate from the GUI SSL Certificate dropdown list.
Setting the Web Interface IP Address
To set the WebUI IP address, when using IPv4 addresses, select a recent IP address on the Web Interface IPv4 Address dropdown list. This limits the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
When using an IPv6 address, select a recent IP address from the Web Interface IPv6 Address dropdown list.
Configuring HTTPS Options
To allow configuring a non-standard port to access the GUI over HTTPS, enter a port number in the Web Interface HTTPS Port field.
Select the cryptographic protocols for securing client/server connections from the HTTPS Protocols dropdown list.
Select the Transport Layer Security (TLS) versions TrueNAS can use for connection security.
To redirect HTTP connections to HTTPS, select Web Interface HTTP -> HTTPS Redirect. A GUI SSL Certificate is required for HTTPS.
Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year).
This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year.
A warning displays when setting this function.
Select Crash Reporting to send failed HTTP request data, which might include client and server IP addresses, tracebacks for failed method calls, and middleware log file contents to TrueNAS.
Sending Usage Statistics and UI Error Reports
To send anonymous usage statistics and WebUI errors to TrueNAS, select the Usage Collection & UI Error Reporting option.
When enabled, anonymous usage statistics and WebUI errors are reported to the TrueNAS engineering team.
No personally identifiable information is collected.
When disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g., TrueNAS 24.04.0, 55 TB) are collected.
To show real-time console messages at the bottom of the browser window, select Show Console Messages.
Localizing the TrueNAS System
Localizing the TrueNAS system consists of changing the UI language and the keyboard layout to support the selected language, setting the time zone to match where the TrueNAS server is located, and setting date and time formats.
To change the Web UI on-screen language and set the keyboard to work with the selected language, click Settings on the Localization widget to open the Localization Settings configuration screen.
Clear the field and begin typing in the field to filter the long list of languages, or scroll to select an option from the Language dropdown list.
Scroll to select the keyboard language layout in Console Keyboard Map.
Begin typing in the Timezone field to filter the long list or scroll down to select the geographic timezone that corresponds to the location of the TrueNAS server.
Select the local date and time formats to use.
Click Save.
Setting Up System Email
The Email widget displays information about current system mail settings.
When configured, an automatic script sends a nightly email to the administrator account containing important information, such as the health of the disks.
To configure the system email send method, click Settings to open the Email Options screen.
Select either SMTP or GMail OAuth to display the relevant configuration settings.
For more information on configuring system email, see Setting Up System Email.
Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.
Adding a License and Proactive Support
Adding a TrueNAS Enterprise License
For users with a valid TrueNAS license, click Add License.
Copy your license into the box and click Save.
You are prompted to reload the page for the license to take effect, click RELOAD NOW.
Log back into the WebUI where the End User License Agreement (EULA) displays.
Read it thoroughly and completely.
After you finish, click I AGREE.
The system information updates to reflect the licensing specifics for the system.
Silver and Gold level Support customers can also enable Proactive Support on their hardware to automatically notify iXsystems if an issue occurs.
To find more details about the different Warranty and Service Level Agreement (SLA) options available, see TrueNAS Enterprise Support.
When the system is ready to be in production, update the status by selecting This is a production system and then click the Proceed button.
This sends an email to iXsystems declaring that the system is in production.
While not required for declaring the system is in production, TrueNAS has the option to include an initial debug with the email that can assist support in the future.
Setting Up Proactive Support
Silver/Gold Coverage Customers can enable iXsystems Proactive Support.
This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
To configure proactive support, click Get Support on the Support widget located on the System > General Settings screen.
Select Proactive Support from the dropdown list.
Complete all available fields and select Enable iXsystems Proactive Support, then click Save.
Setting Up System Email
An automatic script sends a nightly email containing important information such as disk health to configured recipients.
For fast awareness and resolution of critical issues, configure TrueNAS system email with the recipient addresses that should receive these notifications.
TrueNAS mails Scrub Task issues separately to the address configured in those services.
Configuring Email Recipients
Starting with TrueNAS 25.10, system emails are sent to a configurable list of recipients rather than automatically using local administrator email addresses. Configure the recipient list in the system email settings to specify who receives system notifications.
Setting Up System Email
Configure the send method and recipients for the email service.
Go to System > General Settings and locate the Email widget to view the current configuration, or click the Alerts icon at the top right of the UI screen, then click the gear settings icon, and select Email to open the General Settings screen.
Click Settings on the Email Widget to open the Email Options screen.
The configuration options change based on the selected method.
After configuring the send method, click Send Test Mail to verify you can send email.
If the email test fails, verify the recipient addresses are correctly configured in the Email Recipients field.
Save stores the email configuration and closes the Email Options screen.
Configuring Email Using SMTP
To set up SMTP service as the system email send method, you need the outgoing mail server and port number for the email address.
Enter the email address that sends the alerts in From Email and the name that appears before the address in From Name.
Enter the SMTP server host name or IP address in Outgoing Mail Server.
Enter the SMTP port number in Mail Server Port. This is typically 25, 465 (secure SMTP) or 587 (submission).
Select the level of security from the Security dropdown list.
Options are Plain (No Encryption), SSL (Implicit TLS), or TLS (STARTTLS).
Select SMTP Authentication for TrueNAS to reuse authentication credentials from the SMTP server.
Enter the SMTP credentials in the new fields that appear.
Typically, Username is the full email address, and Password is the password for that account.
Click Send Test Email to verify you receive an email.
Click Save.
Configuring Email Using GMail OAuth
To set up the system email using Gmail OAuth, use the TrueNAS web UI to log in to your Gmail account.
Select the account to use for authentication or select Use another account.
When prompted, enter the Gmail account credentials.
Type in the GMail account to use and click Next.
Enter the password for the GMail account you entered.
When the TrueNAS wants to access your Google Account window opens, scroll down and click Allow to complete the setup or Cancel to exit setup and close the window.
After setting up Gmail OAuth authentication, the Email Options screen displays Gmail credentials have been applied, and the button changes to Log In To Gmail Again.
Enter the email, phone number, or Skype username associated with your Outlook account, then click Next to enter your password.
When the TrueNAS wants to access your Outlook Account window opens, scroll down and click Allow to complete the setup or Cancel to exit the setup process.
After setting up Outlook OAuth authentication, the Email Options screen shows Outlook credentials have been applied and the button changes to Logged In To Outlook.
Click Send Test Email to verify you receive an email.
Click Save.
Setting Up the Email Alert Service
After configuring the system email send method, configured recipients receive a system health email every night/morning.
To add or configure the Email Alert Service to send timely warnings when a system alert hits the warning level specified in Alert Settings:
Go to System > Alert Settings or from any screen, click on the Alertsnotifications icon at the top right of the screen to open the Alerts panel.
Click on the settings settings icon and then on Alert Settings.
Locate Email under Alert Services, select the more_vert icon, and then click Edit to open the Edit Alert Service screen.
Add the alert recipient email address in the Email Address field.
Use the Level dropdown to adjust the email warning threshold or accept the default Warning setting.
Click Send Test Alert to generate a test alert and confirm the email address and alert services work.
Advanced Settings
Advanced Settings provides configuration options for the console, syslog, kernel, sysctl, replication, cron jobs, init/shutdown scripts, system dataset pool, isolated GPU device(s), self-encrypting drives, system access sessions, allowed IP addresses, audit logging, and global two-factor authentication.
TrueNAS Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Audit widget displays the current audit storage and retention policy settings.
The public-facing TrueNAS API allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
Use Add on the Sysctl widget to add a tunable that configures a kernel module parameter at runtime.
The Add Sysctl or Edit Sysctl configuration screens display the settings.
Enter the sysctl variable name in Variable. Sysctl tunables configure kernel module parameters while the system runs and generally take effect immediately.
Enter a description and then select Enabled. To disable but not delete the variable, clear the Enabled checkbox.
Click Save.
Adding NTP Servers
The NTP Servers widget allows users to add Network Time Protocol (NTP) servers.
These sync the local system time with an accurate external reference.
By default, new installations use several existing NTP servers. TrueNAS supports adding custom NTP servers.
Managing the System Dataset
Storage widget shows the pool configured as the system dataset pool and allows users to select a different storage pool to hold the system dataset.
The system dataset stores core files for debugging and keys for encrypted pools.
It also stores Samba4 metadata, such as the user and group cache and share-level permissions.
It also includes the reslivering priority setting.
Configure opens the Storage Settings configuration screen.
Storage Settings Configuration Screen
If the system has one pool, TrueNAS configures that pool as the system dataset pool.
If your system has more than one pool, you can set the system dataset pool using the Select Pool dropdown.
Users can move the system dataset to an unencrypted or key-encrypted pool.
Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward.
If the encrypted pool already has a passphrase set, you cannot move the system dataset to that pool.
Changing Resilvering Priority
To set a different resiliver priority, select Run Resilvering At Higher Priority At Certain Times.
Two additional setting options show that allow you to configure the day and time range for resilvering to run.
To return to the default resilver prioirty, clear the checkbox and click Save.
Setting the Number of Replication Tasks
The Replication widget displays the number of replication tasks that can execute simultaneously on the system. It allows users to adjust the maximum number of replication tasks the system can execute simultaneously.
Click Configure to open the Replication configuration screen.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
Managing Allowed IP Addresses
Use the System > Advanced Settings screen Allowed IP Addresses configuration screen to restrict access to the TrueNAS web UI and API.
Entering an IP address limits access to the system to only the address(es) entered here. To allow unrestricted access to all IP addresses, leave this list empty.
Managing Access (WebSocket Sessions)
The Access widget shows a list of all active sessions including the current logged-in user and the time it started.
The Session Timeout setting shows the number of minutes for the current session.
The Login Banner shows the custom text entered on the Access Settings screen. This text shows before the login screen.
When configured, users see the login banner and must click Continue to show the TrueNAS login splash screen.
Administrators can manage other active sessions and configure the session timeout for their accounts.
Terminate Other Sessions ends all sessions except the current session.
To end individual sessions, click the logout button next to that session.
You must check a confirmation box before the system allows you to end sessions.
The logout icon is inactive for the currently logged-in administrator session and active for any other current sessions.
It cannot be used to terminate the currently logged-in active administrator session.
Session Timeout shows the configured token duration for the current session (default is five minutes).
TrueNAS logs out user sessions that are inactive for longer than the configured token setting for the user.
New activity resets the token counter.
When the configured session timeout is exceeded, TrueNAS displays a Logout dialog with the exceeded ticket lifetime value and the time the session is scheduled to terminate.
Enter a value in the number of seconds to suit your needs and security requirements. For example, to change the timeout to 10 minutes, enter 6000.
The default session timeout setting is 300 seconds or five minutes.
The minimum value allowed is 30 seconds, and the maximum is 2147482 seconds, or 20 hours, 31 minutes, and 22 seconds.
Click Save.
Adding a Banner
To show a login banner before the login screen shows, enter the text in the Login Banner field.
Use carriage returns to break up a large block of text and to improve the readability of the text.
After saving the text. The next time an administrative user logs into the UI, a banner screen shows.
To advance to the login screen, click Continue.
Allowing Directory Service Users to Access the UI
TrueNAS Enterprise
Only Enterprise-licensed systems allow TrueNAS web UI access for Directory Service accounts
TrueNAS allows Enterprise users to show the UI to users in an Active Directory group.
To configure this access, first, add the selected AD users to a group that is granted a TrueNAS privilege that permits it, and enable the Allow Directory Service users to access WebUI option on the Access Settings screen. This option only shows on Enterprise-licensed systems.
After TrueNAS joins AD, it automatically creates a new privilege entry in the Privileges screen table, and this privilege is automatically populated with the domain admins group for the domain.
You can edit this privilege by selecting the table row and clicking Edit.
Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges are:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/exeute permissions) to the user.
Security Settings
TrueNAS Enterprise
Only Enterprise-licensed systems show the Security widget and have access to the STIG and FIPS settings.
Administrators considering enabling STIG and FIPS security settings should contact TrueNAS Support before making any changes.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Review these topics and contact TrueNAS Support before enabling STIG and FIPS security settings.
When STIG (and FIPS) are enabled:
TrueNAS cannot issue API keys, and existing API keys cannot be used for authentication. Only the user credential with a two-factor authentication method is accepted.
SSH log-ins require a cryptographic algorithm.
SMB authentication for local TrueNAS accounts is disabled.
NTLM authentication passthrough to a domain controller is disabled.
Usage stats are not reported, and the Usage Collection option is disabled.
One-time passwords (OTP) configured for administrative users have a single use and expire after 24 hours.
After logging in with the OTP, the system prompts the user to immediately change the password and set up two-factor authentication.
TrueNAS is limited to a maximum of 10 concurrent sessions.
Accounts lock for 15 minutes after three consecutive failed login attempts.
Password aging rules are applied to the SMB protocol. After a failed login attempt, users with expired passwords receive a password-expired message.
TrueNAS prompts users to change their passwords when logging in, and the system flags the account as requiring this change.
Users cannot reuse a password if it is marked as used within the last five passwords in the history file. Passwords must be 15 characters in length.
TrueNAS updates can only use a signed update file provided by the TrueNAS team.
What features are not available?
When enabled, STIG disables these features:
Virtualization
Apps
TrueCommand connectivity
What events are included in auditing?
When STIG (and FIPS) are enabled, auditing includes these events:
Account creation events
Privilege commands (with full text of the commands run)
Privilege changes
Log-ins and other system access events.
Account log-ins are tracked from two distinct sources (UI and SSH)
Kernel module load/unload
Audit log modifications and attempts to modify audit logs
Security object modifications and attempts to modify security objects
Configuring STIG and FIPS
To set up FIPS or STIG compliance on a TrueNAS server, you must first configure two-factor authentication for an admin user with full permissions.
After configuring two-factor authentication, go to System > Advanced Settings and locate the Security widget.
Click Settings to open the System Security configuration screen.
Select the toggle to enable FIPS and STIG, then click Save.
You must enable FIPS with STIG!
The system prompts you to restart.
The system restart takes several minutes to complete before showing the login screen.
Highly Available (HA) systems must restart each storage controller before STIG mode is fully enabled.
TrueNAS Administrator Password Rules
The remaining options are for setting TrueNAS administrator password rules.
Options include defining a password lifetime, types of characters that must be present in the password, how many characters must be present in a valid password, and how many previously used passwords to remember for an account and prevent reuse in a new password.
Adjust these as needed for your security requirements.
Enabling STIG compatibility mode requires specific minimum values for these settings.
Note that TrueNAS begins warning all local account types (administrator, full admin, read-only, and sharing-only) seven days before password expiration. After expiration, the account locks and requires administrative action to unlock.
Additional Content
Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.
Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.
Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.
Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.
Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.
Developer Mode (Unsupported): Provides information on the unsupported TrueNAS developer mode and how to enable it.
Managing the System Configuration
TrueNAS allows users to manage the system configuration by uploading or downloading configurations or by resetting the system to the default configuration.
System Configuration Options
The Manage Configuration option on the System > Advanced Settings screen provides three options:
Download File that downloads your system configuration settings to a file on your system.
Upload File that allows you to upload a replacement configuration file.
Reset to Defaults resets system configuration settings back to factory settings.
Downloading the File
The Download File option downloads your TrueNAS current configuration to the local machine.
A system config file is a database file containing your settings, including accounts, directory services, networking, services, shares, storage configuration, system settings, data protection tasks, and more.
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.
When downloading the configuration (config) file, select the Export Password Secret Seed option to include the secret seed in the config file.
Downloading the config file allows you to restore the system to a different operating system device where the secret seed is not already present.
Why should I save the secret seed?
The secret seed is the key TrueNAS uses to decrypt encrypted fields in the configuration database.
TrueNAS encrypts these fields because they can contain sensitive information such as cryptographic certificates, service passwords, or weak hashing algorithms (for example, the NT hashes of SMB users).
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read the encrypted fields.
Services that rely on those fields stop working. Examples are SMB access for local user accounts and apps.
Always select the Export Password Secret Seed option when you download the system config file.
What happens if I do not save the secret seed?
You can still log into the web UI with your existing password.
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so a missing secret seed does not affect them.
TrueNAS disables SMB authentication for all local user accounts.
To restore SMB access for an account, go to Credentials > Users, edit the user, and set a new password.
TrueNAS requires a new password before it re-enables SMB authentication for that account.
TrueNAS deletes some encrypted items entirely, such as cloud credentials, SSH keychain credentials, and Kerberos keytabs.
It empties the values of others, such as SED passwords, certificate private keys, and service passwords.
Reconfigure these settings after you log in.
After you log in, recheck all system settings to verify the configurations are correct.
Then test the system to verify it works as desired.
When the system operates per the desired configuration, download and save the system configuration with the secret seed option selected, and keep it in a secure location.
Always save the secret seed with the system configuration file after you change the system configuration.
This gives you a current backup copy to use if you need it.
Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.
We recommend backing up the system configuration regularly.
Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues.
Save the configuration file each time the system configuration changes.
To download the configuration file:
Go to System > Advanced Settings and click on Manage Configuration.
Select Download File.
Select Export Password Secret Seed and then click Save. The system downloads the system configuration.
Keep this file in a safe location on your network where files are regularly backed up.
Configuration Backup Contents
A downloaded configuration file always contains the full settings database.
The Export Password Secret Seed option determines whether TrueNAS can restore the sensitive, encrypted fields in that database.
The secret seed (the pwenc_secret file) is the key TrueNAS uses to decrypt protected fields in the configuration database.
When you restore a configuration file that does not include the secret seed, TrueNAS generates a new seed and cannot read those fields.
It handles the affected settings in two ways:
TrueNAS deletes some items entirely, such as cloud credentials, SSH keychain credentials, Kerberos keytabs, and any replication or rsync task that uses an SSH connection.
It empties the values of others, such as SED passwords, certificate private keys, iSCSI CHAP secrets, two-factor authentication (2FA) secrets, and service passwords. The item remains, but the sensitive value it needs is blank.
TrueNAS also disables SMB authentication for all local user accounts.
In this table, Yes means the item is present and usable after a restore.
TrueNAS does not store items marked Never in the configuration file, so back them up separately.
Directory services credentials and Kerberos keytabs
No
Yes
Service passwords (email, UPS, SNMP v3, and similar)
No
Yes
App and container registry credentials
No
Yes
IPMI/BMC password
Never
Never
TrueNAS stores login passwords and API keys as one-way hashes rather than encrypted values, so it restores them correctly with or without the secret seed.
Only you know ZFS passphrases, and TrueNAS never writes them to the configuration file.
The BMC hardware stores the IPMI/BMC password, not TrueNAS.
When you configure KMIP, the KMIP server holds SED keys and ZFS key-type encryption keys, and the configuration file does not contain them.
Always back up encryption key files and passphrases separately in a secure location.
Uploading the File
The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS configuration file.
Do I need to upload a config file?
Uploading a config file after a TrueNAS migration or fresh install makes it easy to migrate most system settings with one click. However, you can choose to manually recreate the previous configuration if desired or if some part of the previous configuration causes conflicts with a later TrueNAS version.
If you choose to manually recreate settings, carefully document your original configuration and ensure each setting is recreated exactly.
For example, re-creating a user account named bob after migration does not restore access to existing datasets for the bob user account unless the new account uses the same UID or you manually update the dataset ACLs to grant access.
Upload a configuration file that includes the secret seed whenever possible.
For details on what TrueNAS preserves with and without the seed, see Configuration Backup Contents.
Uploading a configuration file from a FreeBSD-based release wipes any existing administrative users and replaces with the original root user and password from the uploaded configuration file.
To secure the system after restoring from a FreeBSD-based TrueNAS config file, log in with the original root user credentials, recreate an administrative account, and finally re-disable the root account password.
Resetting to Defaults
TrueNAS Enterprise
Enterprise High Availability (HA) systems should never reset their system configuration to defaults.
Contact TrueNAS Enterprise Support if a system configuration reset is required.
TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Save the current system configuration with the Download File option before resetting the configuration to default settings!
If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.
The Reset to Defaults option resets the system configuration to factory settings.
After the configuration resets, the system restarts, and users must set a new login password.
Remote Backups of the Config File
TrueCommand provides an easy solution for users who want to schedule an automatic remote backup of the system configuration file:
Cron jobs allow users to configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Cron Jobs widget on the System > Advanced Settings screen displays No Cron Jobs configured until you add a cron job, and then it displays information on cron job(s) configured on the system.
Click Add to open the Add Cron Job configuration screen and create a new cron job. If you want to modify an existing cron job, click anywhere on the item to open the Edit Cron Jobs configuration screen populated with the settings for that cron job.
The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Enter a description for the cron job.
Next, enter the full path to the command or script to run in Command. For example, for a command string to create a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt.
Select a user account to run the command from the Run As User dropdown list. The user must have permissions allowing them to run the command or script.
Select a schedule preset or choose Custom to open the advanced scheduler.
An in-progress cron task postpones any later scheduled instances of the task until the one already running completes.
Cron Job Schedule Format
Cron job schedules use six asterisks that represent minutes, hours, days of the month, days of the week, and months in that order.
For example, a schedule of 1 1 1 * sat,sun would run at 01:01 AM, on day 1 of the month, and only on Saturday and Sunday.
Separate multiple values for a segment with commas, not spaces.
If you want to hide standard output (stdout) from the command, select Hide Standard Output. If left cleared, TrueNAS emails any standard output to the user account cron that ran the command.
To hide error output (stderr) from the command, select Hide Standard Error. If left cleared, TrueNAS emails any error output to the user account cron that ran the command.
Select Enabled to enable this cron job. Leave this checkbox cleared to disable the cron job without deleting it.
Click Save.
The TrueNAS UI has several fields that allow users to write custom scripts. When a user writes a password into a custom script, the password is provided in cleartext form within system debug files, creating a serious security concern.
We do not recommend using custom scripting on TrueNAS, as it is a highly advanced feature for expert storage administrators and can lead to security breaches.
Managing the Console Setup Menu
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Console widget on the System > Advanced Settings screen displays current console settings for TrueNAS.
Click Configure to open the Console configuration screen. The Console configuration settings determine how the Console setup menu displays, the serial port it uses and the speed of the port, and the banner users see when it is accessed.
To display the console without being prompted to enter a password, select Show Text Console without Password Prompt. Leave it clear to add a login prompt to the system before showing the console menu.
Select Enable Serial Console to enable the serial console but do not select this if the serial port is disabled.
Enter the serial console port address in Serial Port and set the speed (in bits per second) from the Serial Speed dropdown list. Options are 9600, 19200, 38400, 57600 or 115200.
Finally, enter the message you want to display when a user logs in with SSH in MOTD Banner.
Click Save
Managing System Logging
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
By default, TrueNAS writes system logs to the system boot device.
The Syslog widget on the System > Advanced Settings screen allows users determine how and when the system sends log messages to a connected syslog server or server array of two servers.
Each syslog server can have its own host, transport, and TLS certificate settings.
The Syslog widget displays the existing system logging settings.
Before configuring your syslog server to use TLS as the Syslog Transport method, first add a certificate(s) to the TrueNAS system.
Go to Credentials > Certificates and use the Certificates widget to verify you have the required certificates, and if not present, to import them.
Click Configure to open the Syslog configuration screen.
The Syslog configuration screen settings specify the logging level the system uses to record system events, the syslog server DNS host name or IP, the transport protocol it uses, and if using TLS, the certificate for that server, and finally if it uses the system dataset to store the logs.
Select Use FQDN for Logging to include the fully-qualified domain name (FQDN) in logs to precisely identify systems with similar host names.
Select the minimum log priority level to send to the remote syslog server (or array) from the Syslog Level dropdown list.
The system only sends logs at or above this level.
Enter the remote syslog server DNS host name or IP address in the Syslog server Host field.
To use non-standard port numbers like mysyslogserver:1928, add a colon and the port number to the host name.
Log entries are written to local logs and sent to the remote syslog server.
Select the transport protocol for the remote system log server connection in Transport.
Selecting Transport Layer Security (TLS) shows the Syslog TLS Certificate field.
Select the certificate from the TLS Certificate dropdown list.
To add a second syslog server, click Add Syslog Server again and repeat the steps above.
Select Include Audit Logs to enable audit logging.
Click Save.
Configuring SED Settings
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later).
SED configuration options are not visible in the TrueNAS Community Edition.
Community users wishing to implement SEDs can continue to do so using the command line sedutil-cli utility.
Note: Additional changes to SED management options in the TrueNAS UI ahead of the 25.04.0 release version, with documentation updates to follow.
Configuring Global SED Settings
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive widget.
Select the user to unlock SEDs from the ATA Security User dropdown list.
Options are USER or MASTER.
Enter the global SED password in SED Password and in Confirm SED Password.
Click Save.
Remember SED passwords!
If you lose the SED password, you cannot unlock SEDs or access their data.
After configuring or modifying SED passwords, always record and store them in a secure location!
Configuring Individual SED Passwords
To configure individual, per-disk SED passwords, go to Storage and click Disks in the top right of the screen to open the Disks screen.
Click the row or expand_more for a confirmed SED to expand the row.
Click Edit to open the Edit Disk screen.
Enter and confirm the password in the SED Password fields to assign an individual SED password.
If both an individual and global SED password are present, the individual SED password overrides the global password for the disk it is configured on.
Repeat this process for each SED and any SEDs added to the system in the future.
The Init/Shutdown Scripts widget on the System > Advanced Settings screen allows you to add scripts to run before or after initialization (start-up), or at shutdown. For example, creating a script to backup your system or run a systemd command before exiting and shutting down the system.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, and then the widget lists the scripts configured on the system.
Note that the table(s) below can be reorganized by clicking on the column titles. This allows you to toggle the information in each toggle between a descending and ascending order.
Enter a description and then select Command or Script from the Type dropdown list. Selecting Script displays additional options.
Enter the command string in Command, or if using a script, enter or use the browse to the path in Script. The script must have the execute bit set. By default scripts run using dash(1), but you can run a script under a different interpreter by including a shebang line (for example, #!/bin/bash) as the first line of the script.
Select the option from the When dropdown list for the time this command or script runs.
Enter the number of seconds after the script runs that the command should stop in Timeout.
Select Enable to enable the script. Leave clear to disable but not delete the script.
Click Save.
Script Execution
Scripts run at different points in the system lifecycle based on the option you select in the When dropdown:
Pre Init: Select to run a script early in the boot process, after filesystems and networking are available.
Post Init: Select to run a script later in the boot process, just before TrueNAS services start.
Shutdown: Select to run a script during system shutdown, after services begin stopping.
Scripts in the same category (for example, multiple Post Init scripts) run sequentially in the order in which the user added them.
Use the Timeout setting to limit how long each script runs. A script that hangs or takes too long delays the next script in that category.
Shutdown scripts run while the system powers down, so not all services or resources remain available.
Editing an Init/Shutdown Script
Click a script listed on the Init/Shutdown Scripts widget to open the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
You can change from a command to a script, and modify the script or command as needed.
To disable but not delete the command or script, clear the Enabled checkbox.
Click Save.
Isolating GPU for VMs
Systems with more than one graphics processing unit (GPU) installed can isolate additional GPU device(s) from the host operating system (OS) and allocate them for use by a virtual machine (VM).
Isolated GPU devices are unavailable to the OS and for allocation to applications.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
To isolate a GPU, you must have at least two in your system; one available to the host system for system functions and the other available to isolate for use by a VM.
One isolated GPU device can be used by a single VM.
Isolated GPU cannot be allocated to applications.
To allocate an isolated GPU device, select it while creating or editing VM configuration.
When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM and becomes unavailable for any other allocations.
Click Configure on the Isolated GPU Device(s) widget to open the Isolate GPU PCI Ids screen, where you can select a GPU device to isolate.
Reboot the system after adding or removing a GPU from isolation to ensure the device isolation status is fully updated.
Managing Global 2FA (Two-Factor Authentication)
Global Two-factor authentication (2FA) is great for increasing security.
TrueNAS offers global 2FA to ensure that entities cannot use a compromised administrator or root password to access the administrator interface.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
To use 2FA, you need a mobile device (or desktop application) with the correct time and date, and a TOTP-compatible authenticator app installed.
TrueNAS uses the TOTP (Time-based One-Time Password) standard (RFC 6238), which is compatible with most authenticator apps. Popular options include:
Microsoft Authenticator (iOS, Android)
Google Authenticator (iOS, Android)
Authy (iOS, Android, desktop)
Bitwarden (cross-platform, open source)
1Password (cross-platform)
Choose an authenticator app based on your platform and preferences. All TOTP-compatible apps work with TrueNAS.
Two-factor authentication is time-based and requires a correct system time setting.
We strongly recommend ensuring Network Time Protocol (NTP) is functional before enabling two-factor authentication!
What is 2FA and why should I enable it?
2FA adds an extra layer of security to your system to prevent someone from logging in, even if they have your password.
2FA requires you to verify your identity using a randomized six-digit code that regenerates every 30 seconds (unless modified) to use when you log in.
Benefits of 2FA
Unauthorized users cannot log in since they do not have the randomized six-digit code.
Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.
Internet access on the TrueNAS system is not required to use 2FA.
Drawbacks of 2FA
2FA requires an app to generate the 2FA code.
If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled).
You can bypass or unlock 2FA using the CLI.
Enabling Global 2FA
Set up a second 2FA device as a backup before proceeding.
Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.
Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure.
If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.
The Window setting extends the validity of authentication codes to include previously generated codes. This can be helpful in high-latency situations where there can be delays between code generation and entry. The default setting works for most environments - only adjust this if users experience authentication issues due to network delays.
After enabling Global 2FA, the system prompts users to set up their individual 2FA configuration:
Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until Global 2FA is enabled.
When Global 2FA is enabled, user accounts without 2FA settings configured are prompted with the Two-Factor Authentication screen on their next login to set up 2FA authentication for that account.
See Setting Up Individual 2FA for detailed instructions on configuring 2FA for individual user accounts.
Disabling Global 2FA
Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Config. Clear the Enable Two-Factor Authentication Globally checkbox and click Save.
Reactivating Global 2FA
If you want to enable 2FA again, go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save.
To change the system-generated Secret, click on the Settings icon on the top toolbar and select Two-Factor Authentication.
Click Renew 2FA Secret.
Setting Up Individual 2FA
When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. Users can also set up 2FA at any time by accessing Settings > Two-Factor Authentication from the top toolbar.
Set up a second 2FA device as a backup before proceeding.
Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.
To set up individual 2FA:
Click the Settings icon on the top toolbar, then select Two-Factor Authentication to open the User Two-Factor Authentication Actions screen.
Click Configure 2FA Secret to open the Set Up Two-Factor Authentication screen and view the QR code. The Set Up Two-Factor Authentication screen also has the unique key with a copy to clipboard button so you can configure 2FA using a non-camera method if necessary.
You can configure two-factor authentication and get the QR code for an authenticator app for the logged-in user at any time, but you must configure global two-factor authentication to enable it.
Set Interval to 30 seconds to match the default setting used by most authenticator apps. Using a non-standard interval can cause authentication codes to fail during login.
Scan the QR code using your authenticator app or manually enter the unique key.
To generate a new QR code click Renew 2FA Secret.
When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. However, individual setup is optional and can be skipped. See Setting Up Individual 2FA for the full setup process.
To skip the setup:
When the Two-Factor Authentication setup screen appears, click Skip Setup.
Confirm the decision in the dialog that appears.
While 2FA significantly enhances security and is strongly recommended, skipping the initial setup does not prevent access to the system. Users can configure 2FA later by accessing Settings > Two-Factor Authentication from the top toolbar.
The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.
Removing Individual 2FA Configuration
Users can remove their personal 2FA configuration without disabling global 2FA:
Click the Settings icon on the top toolbar and select Two-Factor Authentication.
Click Unset 2FA Secret.
Confirm the removal when prompted.
Removing 2FA configuration reduces account security. Only remove 2FA if you plan to reconfigure it with a different authenticator device, or if you no longer have access to your current authenticator.
After removing your 2FA configuration:
If Global 2FA is still enabled, you are prompted to set up 2FA again on your next login
You can skip this prompt if needed using the Skip Setup button
2FA configurations for other users remain unaffected
Administrator Clearing User 2FA
Administrators can clear 2FA for any user without needing to log in as that user. This is useful when:
A user has lost access to their authenticator device
A user is locked out due to 2FA issues
Troubleshooting login problems for users
To clear 2FA for another user:
Go to Credentials > Users
Select the user whose 2FA needs to be cleared
Click Clear Two-Factor Authentication on the Access widget
Confirm the action in the dialog
After clearing, the user can log in without 2FA. If Global 2FA is still enabled, they are prompted to reconfigure 2FA on their next login.
TOTP codes regenerate every 30 seconds (by default). If a code expires while you are entering it, wait for your authenticator app to display a new code and retry.
Logging In Using SSH
Confirm that you set Enable Two-Factor Auth for SSH in System > Advanced > Global Two Factor Authentication.
Go to Credentials > Users and edit the desired user account. Set SSH password login enabled, then click Save.
Go to System Settings > Services and click the SSHStart Service button to start the service. Wait for the service status to show that it is running.
Open your authenticator app on your mobile device or desktop.
Open a terminal (such as Windows Shell) and SSH into the system using either the host name or IP address, the administrator account user name and password, and the 2FA code.
Developer Mode (Unsupported)
Developer mode is for developers only.
Users that enable this functionality will not receive support on any issues submitted to iXsystems.
Only enable when you are comfortable with debugging and resolving all issues encountered on the system.
Never enable it on a system that has production storage and workloads.
TrueNAS is an Open Source Storage appliance, not a standard Linux operating system (OS) that allows customization of the OS environment.
By default, the root/boot filesystem and tools such as apt are disabled to prevent accidental misconfiguration that renders the system inoperable or puts stored data at risk.
However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.
Do not make system changes using the TrueNAS UI web shell.
Using package management tools in the web shell can result in middleware changes that render the system inaccessible.
Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.
To enable developer mode, log into the system as the root account and access the Linux shell.
Run the install-dev-tools command.
Running install-dev-tools removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS.
These changes do not persist across updates and install-dev-tools must be re-run after every system update.
Troubleshooting
install-dev-tools is a developer-focused option that might not work in scenarios beyond those intended by TrueNAS developers, such as modified installations or deployments that use non-default settings.
Users with NVIDIA GPU drivers installed cannot enable developer mode while the NVIDIA kernel module is mounted.
Running install-dev-tools in this state results in the following error:
/usr is currently provided by a readonly systemd system extension.
This may occur if nvidia module support is enabled. System extensions
must be disabled prior to disabling rootfs protection.
This happens because the NVIDIA drivers are overlaid onto /usr via systemd-sysext, making it read-only by design.
To resolve the issue, unmerge systemd-sysext, run install-dev-tools, then merge system extensions again.
Boot Pool Management
The Boot Environment screen has options that monitor and manage the ZFS boot pool and devices that store the TrueNAS operating system.
Changing the Scrub Interval
The Stats/Settings option shows current system statistics. It also allows you to change the scrub interval or how often the system runs a data integrity check on the operating system device.
Go to the System > Boot Environment screen and click Stats/Settings.
The Stats/Settings window shows statistics for the operating system device: Boot Pool Condition as Online or Offline, Size in GiB, the consumed space in Used, and Last Scrub Run with the date and time of the most recent scrub task.
By default, the operating system device is scrubbed every seven days.
To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.
Boot Pool Device Management
From the Boot Environment screen, click Boot Pool Status to open the Boot Pool Status screen.
This screen shows the boot-pool. Expand it to show the devices allocated to that pool.
Read, write, or checksum errors show for the pool.
TrueNAS supports a ZFS feature known as boot environments.
These are snapshot clones of the TrueNAS boot-pool install location that TrueNAS boots into.
Only one boot environment is used for booting at a time.
A boot environment allows restarting the system to a specific point in time and greatly simplifies recovering from system misconfigurations or other potential system failures.
With multiple boot environments, updating the operating system becomes a low-risk operation.
For example, the TrueNAS update process automatically creates a snapshot of the current boot environment and adds it to the boot menu before applying the update.
If anything goes wrong during the update, the system administrator can activate the snapshot of the pre-update environment and restart TrueNAS to restore system functionality.
Boot environments do not preserve or restore the state of any attached storage pools or apps, only the system boot-pool.
Storage backups must be handled through the ZFS snapshot feature or other backup options.
TrueNAS applications also use separate upgrade and container image management methods to provide app update and rollback features.
To view the list of boot environments on the system, go to System > Boot.
Each boot environment entry contains this information:
Name: the name of the boot entry as it appears in the boot menu.
Active: indicates which entry boots by default if a boot environment is not active.
Date Created: indicates the boot environment creation date and time.
Space: shows boot environment size.
Keep: indicates whether or not TrueNAS deletes this boot environment when a system update does not have enough space to proceed.
Use the icons row to take different actions for a boot environment.
Following Best Practices
Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but not all state changes made in an environment appear in another.
Changes made in a new boot environment do not subsequently appear in older environments of earlier releases. Similarly, changes made while booted into a previous environment do not automatically appear in the upgraded boot environment.
The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information.
We recommend only reverting to an earlier boot environment when a pool upgrade in the new version introduces a problem, or to recover from a broken configuration if the system console or IPMI is unavailable.
Activating a Boot Environment
The option to activate a boot environment only displays for boot entries not set to Active
Activating an environment means the system boots into the point of time saved in that environment the next time it is started.
Click the Activate (Activate) icon for an inactive boot environment to open the Activate dialog.
The System Boot screen status changes to Reboot and the current Active entry changes from Now/Reboot to Now, indicating that it is the current boot environment but it is not used on the next system restart (boot operation).
Activating and booting into an older environment restores only that environment state. Any changes made there do not carry forward into newer environments.
Rolling Back a Boot Environment
When the system is joined to Active Directory and you roll back to (activate) an earlier boot environment, or in the case where you migrated from a FreeBSD-based version to a current Debian-Linux version of TrueNAS and then need to revert back to FreeBSD-based, this can result in desynchronization of the system account password in AD between the different environments.
The directory service-stored secret moves forward with upgrades, while the rolled-back boot environment retains the old one.
If desynchronization occurs, you might see a Kerberos credentials not valid error message.
To avoid possible issues, leave AD, then rollback or revert to the earlier version, and then rejoin AD.
To recover from the error, leave and then rejoin Active Directory.
To roll back to a previous Debian-Linux based boot environment, click the Activate icon for the environment you want to roll back to, then restart the system.
See Migrating CORE to SCALE for information on rolling back or reverting to FreeBSD-based releases.
Cloning a Boot Environment
Cloning copies the selected boot environment into a new inactive boot environment that preserves the boot-pool state at the clone-creation time.
Click the Clone (Clone) icon to open the Clone Boot Environment window.
Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
The Source field displays the boot environment you are cloning. If the displayed name is incorrect, close the window and select the correct boot environment to clone.
Click Save.
Deleting a Boot Environment
Deleting a boot environment removes it from the ** Boot Environment** screen and the boot menu.
Click on the Delete (Delete) icon for a boot environment to open the Delete dialog.
Select Confirm and then click Delete.
You cannot delete the default or any active entries.
Because you cannot delete an activated boot entry, this option does not show for activated boot environments.
To delete the active boot environment, first, activate another entry and then delete the environment you want to remove.
Keeping a Boot Environment
By default, TrueNAS prunes boot environments when the boot pool runs out of remaining storage space.
Keep toggles with the Unkeep option, and they determine whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.
Click the Keep (Keep) icon for a boot environment to open the Keep dialog.
Select Confirm and then click Keep Flag.
This makes the boot environment subject to automatic deletion if the TrueNAS updater needs space for an update.
Recovering a Boot Pool
When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and restore your system configuration. This process involves a complete system rebuild while preserving your data pools and configuration settings.
Recovery Steps
Replace the failed boot drive - Install a new drive to serve as the boot device.
Perform a clean TrueNAS installation - Follow the standard installation procedure to install TrueNAS on the new boot drive.
Upload your configuration file - Use your previously saved configuration backup to restore system settings:
Go to System > General > Manage Configuration
Click Upload Config and select your configuration backup file
Follow the prompts to restore your settings
Import existing data pools - Your data pools should be automatically detected and imported after the configuration restore. If not:
Go to Storage > Import Pool
Select your existing pools and import them
Important Considerations
By default, TrueNAS creates a new boot environment when you update or reinstall the system, but if you revert to an earlier environment and make changes, those changes do not carry into the newer environment. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists.
Keep external backups - Always maintain current configuration backups stored outside the TrueNAS system
Regular backup schedule - Export configuration files regularly, especially after making system changes
Data pools preserved - This process only affects the boot pool - your data pools and their contents remain intact
Boot environments lost - All boot environments are lost and must be recreated after recovery
After Recovery
After completing the recovery:
Verify all pools are imported and healthy
Check that sharing services are working correctly
Recreate any custom boot environments as needed
Update your configuration backup to reflect the new system state
Services
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
System > Services displays each system component that runs continuously in the background. These typically control data-sharing or other external access to the system. Individual services have configuration screens, activation buttons, and you can set them to run automatically.
Documented services related to data sharing or automated tasks are in their respective Shares and Tasks articles.
Contents
FTP: Provides instructions on configuring the FTP service including storage, user, and access permissions.
NFS: Provides information on configuring NFS service in TrueNAS.
SMB: Provides instructions on configuring the SMB service in TrueNAS.
SNMP: Provides information on configuring SNMP service in TrueNAS.
SSH: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.
UPS: Provides information on configuring UPS service in TrueNAS.
FTP
The File Transfer Protocol (FTP) is a simple option for data transfers.
SSH provides secure transfer methods for critical objects like configuration files, while TFTP provides simple file transfer methods for non-critical files.
Options for configuring FTP, SSH, and TFTP are in System > Services.
Click the edit to configure the related service.
Configuring FTP Service
FTP requires a new dataset and a local user account.
Go to Storage to add a new dataset to use as storage for files.
Next, add a new user. Go to Credentials > Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory.
Add ftp to the Auxiliary Groups field.
You can do this for every user or create a global account for FTP (for example, OurOrgFTPaccnt).
You cannot create multiple accounts utilizing the same dataset as your home directory.
By default, only members of the ftp group can authenticate via FTP.
Add your newly created user to the ftp group, or change this behavior in the FTP service configuration:
Enable Allow Local User Login to allow any local user to authenticate
Enable Allow Anonymous Login to allow anonymous connections without authentication
Dataset permissions are configured separately and control what files authenticated users can access.
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields.
Select Apply User and Apply Group.
Select the Read, Write, and Execute for User, Group, and Other you want to apply.
Click Save.
Configuring Service Settings
To configure FTP, go to System > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
To confine FTP sessions to the home directory of a local user, select chroot.
Authentication Options:
By default, only ftp group members can authenticate (no additional configuration needed)
Enable Allow Local User Login to allow any local user to authenticate without ftp group membership
Enable Allow Anonymous Login to allow anonymous connections without authentication
Do not allow anonymous access unless it is necessary.
Enable TLS when possible (especially when exposing FTP to a WAN).
TLS creates FTPS for better security.
Click Save, then start the FTP service.
Connecting with FTP
Use a browser or FTP client to connect to the TrueNAS FTP share.
The images below show FileZilla, a free option.
The user name and password are those of the local user account on the TrueNAS system.
The default directory is the same as the user home directory.
After connecting, you can create directories and upload or download files.
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
Go to System > Services screen, locate NFS, and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
We recommend using the default NFS settings unless you require specific settings.
Select the IP address from the Bind IP Addresses dropdown list to use a specific static IP address, or leave this field blank for NFS to listen to all available addresses.
By default, TrueNAS dynamically calculates the number of threads the kernel NFS server uses.
To manually enter an optimal number of threads the kernel NFS server uses, clear Calculate number of threads dynamically and enter the number of threads you want in the Specify number of threads manually field.
If using NFSv4, select NFSv4 from Enabled Protocols. NFSv3 ownership model for NFSv4 clears, allowing you to enable or leave it clear.
Selecting NFSv3 ownership model for NFSv4 deactivates the Manage Group Server-side option.
To force NFS shares to fail if the Kerberos ticket is unavailable, select Require Kerberos for NFSv4.
Next, enter a port to bind to in the field that applies:
Enter a port to bind mountd(8) in mountd(8) bind port.
Enter a port to bind rpc.statd(8)in rpc.statd(8) bind port.
Enter a port to bind rpc.lockd(8) in rpc.lockd(8) bind port.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Only select Allow non-root mount if the NFS client requires it to allow serving non-root mount requests.
Select Manage Groups Server-side to allow the server to determine group IDs based on server-side lookups rather than relying solely on the information provided by the NFS client.
This can support more than 16 groups and provide more accurate group memberships.
It is equivalent to setting the --manage-gids flag for rpc.mountd.
This setting assumes group membership is configured correctly on the NFS server.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
Click Save.
Start the NFS service.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
Adding a Service Principal Name (SPN)
TrueNAS allows configuring a Service Principal Name (SPN) on the NFS service screen when TrueNAS is joined to Active Directory, AD is healthy in TrueNAS, and when NFSv4 is selected in Enabled Protocols and Require Kerberos for NFSv4 is enabled.
What is an SPN?
A Service Principal Name (SPN) is how Kerberos identifies a specific service instance on a specific host so a client can request a ticket for it.
Think of it as the address for the NFS service in Kerberos terms, which is specified as service-class/hostname[:port], for example, nfs/truenas-box.domain.com.
When a client wants to talk to that NFS server using Kerberos auth, it asks the AD domain controller (KDC) for a ticket for that exact SPN.
The KDC can only issue the ticket if the SPN is registered to a security principal in AD (usually a computer account or a dedicated service account).
Adding the SPN registers the nfs/truenas-box.domain.com in AD and stores the corresponding keytab entry locally so the NFS service can decrypt tickets presented for it.
Without this registration, clients requesting Kerberos-secured NFSv4 get an auth failure because the ticket request has nowhere to resolve to.
Registering the SPN entry creates the AD registration and the local keytab entry via nfs.add_principal, using AD admin credentials with rights to write SPNs.
After setting up the NFS service and saving changes, open the NFS service screen again to see Add SPN active at the bottom of the screen to the right of Save.
Click Add SPN to open the first of two dialogs. Select Yes on the first Enable Kerberos SPN Entry dialog to open the second dialog.
Enter the AD admin account name and password for that account, then click Submit.
Authentication is against the AD account and not the TrueNAS administrator account in the TrueNAS database.
AD owns the SPN, not TrueNAS.
SMB
The Services > SMB screen displays after going to the Shares screen, finding the Windows (SMB) Shares section, and clicking more_vert + Config Service.
Alternatively, you can go to System > Services and click the edit edit icon for the SMB service.
Configuring SMB Service
The SMB Services screen displays setting options to configure TrueNAS SMB settings to fit your use case.
In most cases, you can set the required fields and accept the rest of the setting defaults. If you have specific needs for your use case, click Advanced Options to display more settings.
Enter the name of the TrueNAS host system if not the default displayed in NetBIOS Name. This name is limited to 15 characters and cannot be the Workgroup name.
Enter any alias name or names that do not exceed 15 characters in the NetBIOS Alias field. Separate each alias name with a space between them.
Enter a name that matches the Windows workgroup name in Workgroup. TrueNAS detects and sets the correct workgroup when Active Directory is configured and the field is left unset.
NetBIOS names (workgroup, domain, and computer names) are limited to 15 characters and cannot contain the following characters: \ / : * ? " < > |
Microsoft and RFC 852 define reserved words that should not be used as NetBIOS names. TrueNAS 25.04 and later enforce these restrictions through validation.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
If you encounter validation errors when joining Active Directory or configuring SMB services, verify that your NetBIOS Name, Workgroup, and Domain Name comply with these requirements.
If using SMB1 clients, select Enable SMB1 support to allow legacy SMB1 clients to connect to the server. Note: SMB1 is deprecated. We advise upgrading clients to operating system versions that support modern SMB protocols.
If you plan to use the insecure and vulnerable NTLMv1 encryption, select NTLMv1 Auth to allow smbd attempts to authenticate users.
This setting enables backward compatibility with older versions of Windows, but we do not recommend it. Do not use on untrusted networks.
Enter any notes about the service configuration in Description.
TrueNAS and Samba default behavior for SMB transport encryption allows SMB clients to negotiate different encryption levels for shares.
This default setting enables negotiating encryption but does not turn on data encryption globally per share.
SMB1 and SMB2 provide different settings to change the level of global or per-share SMB encryption applied to connections.
See Samba Server SMB Encrypt(s) for more information.
You can change the SMB service to apply different SMB transport encryption levels to suit your use case.
Go to the SMB service, found on the System > Services screen, and click Edit for the SMB service to open the SMB Service screen, then click on Advanced Settings.
Click in the Transport Encryption Behavior field to select the option and behavior you want applied:
Default - follow upstream/TrueNAS default
Negotiate - only encrypt transport if explicitly requested by the SMB client
Desired - encrypt transport if supported by client during session negotiation
Required - always encrypt transport (rejecting access if client does not support encryption - incompatible with SMB1 server enable_smb1)
Select the Default option to use the TrueNAS current behavior.
If set to default, there is no technical limitation preventing an SMB client from negotiating an encrypted session if required.
If you are concerned about having Windows SMB clients always using signing in your environment, make a GPO change on the client side to always sign SMB2+ traffic.
This defaults to the Windows settings digitally sign communications (always) and to off.
To monitor SMB service event logs, such as when a client attempts to authenticate to the share, use the TrueNAS auditing screen.
Go to System > Audit to review event logs, including SMB connect, disconnect, create, read or write events, and others.
Enter SMB in the search bar to view only SMB service logs or use the advanced search to further limit results.
Configuring SMB Share Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Use Watch List or Ignore List to limit auditing to specific groups and reduce audit volume.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
SNMP
SNMP (Simple Network Management Protocol) monitors network-attached devices for conditions that warrant administrative attention.
TrueNAS uses Net-SNMP to provide SNMP.
To configure SNMP, go to System > Services page, find SNMP, and click the edit.
To download an MIB from your TrueNAS system, you can enable SSH and use a file transfer command like scp.
When using SSH, make sure to validate the user logging in has SSH login permissions enabled and the SSH service is active and using a known port (22 is default).
Management Information Base (MIB) files are located in /usr/local/share/snmp/mibs/.
Example (replace mytruenas.example.com with your system IP address or hostname):
It is possible for SNMP v3 service settings to not fully migrate from FreeBSD-based releases to a Debian-Linux version, and then not carry over after upgrading from release 25.10.4 to later releases.
To resolve this, go to System > Services in the Debian-Linux TrueNAS UI:
Stop the SNMP service.
Edit the SNMP service by re-entering the SNMP v3 service values you recorded when Preparing to Migrate, and then click Save.
Toggle the SNMP service Start Automatically to on.
Allowing external connections to TrueNAS is a security vulnerability!
Do not enable SSH unless you require external connections.
See Security Recommendations for more security considerations when using SSH.
Configuring SSH Service
To configure SSH go to System > Services, find SSH, and click edit to open the basic settings General Options configuration screen.
Use the Password Login Groups and Allow Password Authentication settings to allow specific TrueNAS account groups the ability to use password authentication for SSH logins.
Click Save. Select Start Automatically and enable the SSH service.
Configuring Advanced SSH Settings
If your configuration requires more advanced settings, click Advanced Settings.
The basic options continue to display above the Advanced Settings screen.
Configure the options as needed to match your network environment.
Select specific network interfaces from Bind Interfaces for SSH to listen on, or deselect all options to have SSH listen on all interfaces (default).
Select Compress Connections to reduce latency over slow networks.
Configure SFTP logging by selecting the appropriate SFTP Log Level and SFTP Log Facility.
Select additional cipher options in Weak Ciphers if needed.
None allows unencrypted SSH connections while AES128-CBC allows the 128-bit Advanced Encryption Standard cipher.
These ciphers are security vulnerabilities and should only be used in secure network environments.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Add sshd_config options not covered by other settings in Auxiliary Parameters.
Enter one option per line.
Parameters are case-sensitive.
SSH auxiliary parameters are unsupported.
Certain configurations can prevent the SSH service from starting.
Remember to enable the SSH service in System > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account.
See Adding SSH Credentials for more information.
Using SSH File Transfer Protocol (SFTP)
SFTP (SSH File Transfer Protocol) is available by enabling SSH remote access to the TrueNAS system.
SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.
Go to System > Services, find the SSH entry, and click the edit to open the Services > SSH basic settings configuration screen.
Go to Credentials > Users. Click anywhere on the row of the user you want to access SSH to expand the user entry, then click Edit to open the Edit User configuration screen. Make sure that SSH password login enabled is selected. See Managing Users for more information.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
SSH with root is a security vulnerability. It allows users to fully control the NAS remotely with a terminal instead of providing SFTP transfer access.
Choose a non-root administrative user to allow SSH access.
Review the remaining options and configure them according to your environment or security needs.
Remember to enable the SSH service in System > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
TrueNAS shows an error if users activate Global 2FA (Two-Factor Authentication) and attempt to enable password-based SSH authentication without a 2FA token. See Managing Global 2FA for more information.
Using SFTP Connections
Open an FTP client (like FileZilla) or command line.
This article shows using FileZilla as an example.
Using FileZilla, enter SFTP://{TrueNAS IP} {username} {password} {port 22}. Where {TrueNAS IP} is the IP address for your TrueNAS system, {username} is the administrator login user name, and {password} is the administrator password, and {port 22} to connect.
SFTP does not offer chroot locking.
While chroot is not 100% secure, lacking chroot lets users move up to the root directory and view internal system information.
If this level of access is a concern, FTP with TLS might be the more secure choice.
UPS
An Uninterruptible Power Supply (UPS) is a power backup system that ensures continuous electricity during outages, preventing downtime and damage.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support.
For supported device and driver information, see their hardware compatibility list.
Further device-specific compatibility information is available from the NUT Devices Dumps Library.
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
Some UPS models are unresponsive with the default polling frequency (default is two seconds).
TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10.How do I find a device name?
For USB devices, the easiest way to determine the correct device name is to enable and view console messages in the TrueNAS UI.
Go to System > General Settings, find the GUI widget, and click Settings.
Select Show Console Messages under Other Options.
Click Save.
Plug in the USB device and look for a /dev/ugen or /dev/uhid device name in the console messages.
Can I attach Multiple Computers to One UPS?
A UPS with adequate capacity can power multiple computers.
One computer connects to the UPS data port with a serial or USB cable.
This primary system makes UPS status available on the network for other computers.
The UPS powers the secondary computers, and they receive UPS status data from the primary system.
See the NUT User Manual and NUT User Manual Pages.
Using Shell
The TrueNAS Shell is convenient for running command line tools, configuring different system settings, or finding log files and debug information.
Warning! The supported mechanisms for making configuration changes are the TrueNAS WebUI and API exclusively.
All other are not supported and result in undefined behavior that can result in system failure!
The Font Sizeremove and add buttons adjust the displayed text size in the Shell.
The shell window stores the command history for the current session.
Leaving the Shell screen clears the command history.
Navigating In Shell
This section provides keyboard navigation shortcuts you can use in Shell.
Action
Keyboard/Command
Description
Scroll up
Up arrow expand_less
Scroll up through previous commands.
Scroll down
Down arrow expand_more
Scroll down through following commands.
Top of screen
Home
Moves the cursor to the top of the screen when viewing entries and results.
Bottom of screen
End
Moves the cursor to the bottom of the screen command when viewing entries and results.
Delete
Delete
Deletes highlighted text.
Auto-fill text
Tab
Type a few letters and press Tab to complete a command name or filename in the current directory.
right-click
Right-clicking in the terminal window opens the browser default right click menu, which allows you to use native copy and paste functions.
Exit to root prompt
exit
Entering exit leaves the session.
Copy text
Ctrl+Insert
Enter Ctrl+Insert to copy highlighted text in Shell.
Paste text
Shift+Insert
Enter Shift+Insert to paste copied text in Shell.
Kill running process
Ctrl+c
Enter Ctrl+c to kill a process running in Shell. For example, the ping command.
Changing the Default Shell
zsh is the default shell, but you can change this by going to Credentials > Users.
Select the admin or other user to expand it.
Click Edit to open the Edit User screen.
Scroll down to Shell and select a different option from the dropdown list.
Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh.
Click Save.
Admin users can set the Shell to default to the TrueNAS Console by selecting TrueNAS Console in Shell on the Edit User screen.
Clicking other TrueNAS UI menu options closes the shell session and stops commands running in the Shell screen.
Tmux allows you to detach sessions in Shell and then reattach them later.
Commands continue to run in a detached session.
Using Audit Logs
TrueNAS auditing and logs provide a trail of all actions performed by a session, user, or service (SMB, middleware).
The audit function backends are the syslog and Samba debug libraries.
Syslog sends audit messages via an explicit syslog call with configurable priority (WARNING is the default) and facility (for example, USER).
The default is syslog-sent audit messages.
Debug sends audit messages from the Samba debug library. Messages have a configurable severity (WARNING, NOTICE, or INFO).
The System > Audit screen lists all session or user events, facilitating comprehensive monitoring.
Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).
Audit logs retain at least one week of data. Logs are downloadable.
Auditing event types are:
Session and user
Sudo and root user commands (includes STIG-compliant shell commands)
SMB protocol and share
iSCSI protocol and share
FTP service
STIG-compliant security objects
HA shutdown and restart reason
Enterprise and Enterprise HA systems have security object (FIPS and STIG) event logging.
HA primary and standby controller event logs are downloadable from either the primary or the standby controller.
Session and User Auditing Events
Session and user auditing events include authentication, method call, and sudo accept/reject events.
Authentication Events
Audit messages are generated every time a client logs into the TrueNAS UI or an SSH session or makes changes to user credentials.
TrueNAS terminates inactive sessions when it reaches the specified timeout limit. If a user initiates a new session within five minutes of the last session, TrueNAS logs the user as associated with the previous session. If the log-in occurs outside the five minutes, TrueNAS initiates a new websocket session.
Method Call Events
Audit messages are generated every time a currently logged-in user creates a new user account or changes user credentials.Sudo Accept or Reject Events
Generated every time a user logs into a shell session and uses sudo to perform a command as root, or is denied sudo permission.
The event data for a sudo event includes the command.
SMB Auditing Events
SMB events are omitted by default from the System > Audit screen.
To view these audit results, go to System > Services and click receipt_longAudit Logs for the SMB service or use the Service dropdown on the main Audit screen to select SMB.
SMB audit logs include all SMB protocol events, but do not include changes to SMB configuration, such as creating an SMB share or querying and modifying SMB ACLs.
See the middleware service log to review those events.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List configuration.
Watch and ignore lists control subsequent SMB operations (connect, create, write, read, etc.) but do not filter authentication events.
This ensures a complete audit trail of all authentication attempts for security and compliance purposes.
Connect Events
Generated every time an SMB client performs an SMB tree connection (TCON) to a given share.
Each session can have zero or more TCONs.Disconnect Events
Generated every time an SMB client performs an SMB tree disconnect to a given share.Create Events
Generated every time an SMB client performs an SMB create operation on a given tree connection (TCON).
Does not log internally-initiated create operations.
Each SMB tree connection can have multiple open files.Read or Write Events
Generated as an SMB client reads from or writes to a file.
TrueNAS waits at least 60 seconds after a read or write event before generating another one for the same file type, so constant reads or writes to a file produce one event per type per minute.
File-based counters are printed within close messages, and connection-based counters are included in disconnect messages.Read or Write Offload Events
Generated as an SMB client performs offloads of reads from or writes to a file.
TrueNAS waits at least 60 seconds after an offload read or write event before generating another one for the same file type, so constant offload reads or writes to a file produce one event per type per minute.
File-based counters are printed within close messages, and connection-based counters are included in disconnect messages.Open or Close Events
Generated every time an SMB client opens or closes a file.
When a file is opened or closed, a summary of file system operations performed on the type is included in the audit message.Rename Events
Generated when a client attempts to rename a file.Set_Attr Events
Generated when a client attempts to set basic file attributes (for example, DOS mode or file timestamps).
The key attr_type indicates the precise type of attributes changed in the event this message records.Set_Quota Events
Generated when a client attempts to set basic file attributes (for example, DOS mode or file timestamps).
The key attr_type indicates the precise type of attributes changed in the event this message records.Unlink Events
Generated when a client attempts to delete a file or directory from a share.Set_ACL Events
Generated when a client attempts to set an NFSv4 ACL on a file system or to grant a user (OWNER) read and write permissions to the file system.
Audit Message Records
Audit records contain information that establishes:
Type of event
When the event occurred (timestamp)
Where the event occurred (source and destination addresses)
Source of the event (user or process)
Outcome of the event (success or failure)
Identity of any individual or file names associated with the event
Each audit message is a single JSON file containing mandatory fields.
It can also include additional optional records.
Message size is limited to not exceeding 1024 bytes for maximum portability with different syslog implementations.
Use the Export button on an audit screen to download audit logs in CSV, JSON, or YAML format. CSV format is readable in spreadsheet programs.
Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file.
The JSON object for an audit message contains the version information, the service that might be the name of the SMB share, a session ID, and the tree connection (tcon_id).
Message Fields
Each audit message JSON object includes:
Field
Description
aid
GUID uniquely identifying the audit event.
vers
JSON object containing version information of the audit event. Audit version identifiers represent the major and minor versions of the internal TrueNAS audit message. Major versions are not made outside a major TrueNAS release. Minor version changes indicate non-breaking changes to the format, such as adding a new optional field. Major version changes that can be renaming or removing an existing mandatory field.
time
UTC timestamp indicating when the event occurs.
addr
IPv4 or IPv6 address for the client generating the audit message.
user
Username of the user or client generating the audit message. If no username, it can be the user ID prefixed with UID.
svc
Unique human-readable service identifier (all uppercase alpha characters) for the TrueNAS service generating the audit message (always SMB).
event
Human-readable name for the event type for the audit message. Name is in all uppercase alpha characters that can include the underscore (_) or dot (.) special characters. See Audit Event Types above for more information.
svc_data
A JSON object containing tree connection (TCON) specific data. This is standardized for all events.
event_data
A JSON object containing event-specific data. This varies based on the event type.
sess
GUID unique identifier for the session.
success
Shows true if the operation succeeds or false if it fails.
Accessing Auditing Screens
Users have access to audit information from three locations in the TrueNAS UI:
Credentials > Users details screen through the Audit Logs option
* On the Users screen, click Audit Logs on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user. For more details, see Audit Screen.
Shares > Window (SMB) Shares details screen through the share edit Audit Logging option
* On the Sharing screen, click the editEdit icon on the desired SMB share row where Enable, watch and ignore settings are available. For details, see Configuring SMB Auditing.
System > Services > SMB to view SMB audit logs
* On the Services screen, click the receipt_longAudit Logs icon on the SMB row. This opens the main Audit log page with the Search field filter configured to show only SMB events. For details, see Audit Screen.
System > Audit option on the main navigation panel
* The default Audit log screen is unfiltered and displays all system events such as authentication and SMB events.
Use the Service dropdown at the top of the screen to filter audit entries by service type (SMB, Middleware, etc.).
The audit screen includes basic and advanced search options.
Click Switch to Basic to change to the basic search function or click Switch to Advanced to show the advanced search operators.
You can enter any filters in the basic Search field to show events matching the entry.
To enter advanced search parameters, use the format displayed in the field, for example, Event = “CLOSE” to show close events. Use the Service dropdown to filter by service type (SMB, Middleware, etc.) before or after applying advanced search filters.
Event types are listed in Auditing Event Types.
Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering.
Parentheses define query priority.
Clicking the advanced Search field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.
For example, to search for connect or close events from the user smbuser, select SMB from the Service dropdown and enter Event in ("Connect", "Close") AND User = "smbuser" in the advanced search field. To exclude authentication events, enter Event != "Authentication".
The advanced search automatically checks syntax and shows done when the syntax is valid and warning for invalid syntax.
Click on a row to show details of that event in the Metadata and Event Data widgets.
Export provides a dropdown to export event log data in CSV, JSON, or YAML format. CSV files can be opened in spreadsheet programs (i.e., MS Excel, Google Sheets, etc.). JSON and YAML formats are useful for importing into data management applications or automation tools.
The assignment (Copy to Clipboard) icon shows two options, Copy Text and Copy Json.
Copy Text copies the event to a text file.
Copy Json copies the event to a JSON object.
Configuring SMB Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Use Watch List or Ignore List to limit auditing to specific groups and reduce audit volume.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Configuring Audit Storage and Retention Policies
To configure Audit storage and retention settings, click Audit Settings on the Audit screen or go to System > Advanced Settings, then click Configure on the Audit widget.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
For example, to change the percent usage warning threshold for the storage allocated to the Audit database:
Navigate to System > Advanced screen.
Select the Configure button on the Audit widget.
In the Audit configuration popup, change the value in the Quota Fill Warning field to the desired percentage.
Select the Save button to effect the change.
UI Reference Guide
Welcome to the TrueNAS UI Reference Guide!
This document shows and describes each screen and configurable option contained within the TrueNAS web interface.
The document is arranged in a parallel manner to the TrueNAS web interface, beginning with the top panel and then descending through each option displayed in the web interface left side menu.
To display this document in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
TrueNAS UI Reference Guide Sections
⎙ Download or Print: View the TrueNAS UI Reference Guide as a single page for download or print.
Top Toolbar: All the icons and options contained in the TrueNAS top toolbar.
Settings Options: Describes the top-level Settings options in TrueNAS.
Jobs Screens: Describes the TrueNAS jobs manager and how to use it to view failed jobs and logs.
Dashboard: Explains the main dashboard information cards and provides basic information on synchronizing the system and TrueNAS server times, and on customizing the Dashboard display.
Storage: Provides information on the Storage Dashboard widgets and options for pools, devices, and disks listed on this screen.
Disks: Describes UI screens and dialogs related to disk operations.
Pool Creation Wizard: Descriptions for settings and functions found in the Pool Creation Wizard.
VDEVs: Provides information on settings and functions found on the VDEVs screens and widget.
Datasets: Provides information on the Datasets screens and settings.
Zvols: Provides information on the settings and functions found on the Zvol screens and widgets.
Capacity Settings: Provides information on the quota settings and functions found on the Capacity Settings screen.
Snapshots: Provides information on the settings and functions found on the Snapshots screen.
User and Group Quotas : Provides information on the settings and functions found on the User and Group Quota screens.
Encryption Settings: Provides information on the settings and functions found on the TrueNAS storage encryption screens.
Permissions: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.
Shares: Describes the various storage sharing screens in TrueNAS.
SMB Shares Screens: Provides information on SMB share screens and settings.
NFS Shares Screens: Provides information on NFS Shares screens and settings.
Backup Credentials: Information on backup credential screens and settings to integrate TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about the Certificates screen and widgets.
KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS Enterprise.
Containers: Provides information on the Containers screens and settings to add containers or virtual machines (VMs) to your TrueNAS system.
Virtual Machines: Provides information on the screens and settings to add virtual machines (VMs) and devices to your TrueNAS SCALE system.
Apps: Articles describing the TrueNAS Apps screens and fields.
Custom App Screens: Provides information on the Install Custom App screen and configuration settings.
Reporting: Provides information on TrueNAS reporting graph screens and settings.
System Settings: Articles describing the various screens and fields contained within the TrueNAS System Settings section.
Update Screens: Provides information on functions and fields on the TrueNAS Update screens.
General Settings Screen: Provides information on the General Settings screen, widgets, and configuration settings for getting support, changing console or the GUI, localization and keyboard setups, and system email.
Advanced Settings Screen: Provides information on the System Settings > Advanced screen, widgets, and configuration screen settings.
Boot: Provides reference descriptions of the boot environment screens and settings.
Services: Information on the Services screen and individual service articles in the Services area.
Shell Screen: Provides information on the TrueNAS Shell screen, buttons, and slider.
Alert Settings Screen: Provides information on Alert Settings service screen settings.
Audit Screen: Provides information on the TrueNAS Audit screens and settings.
Top Toolbar
The top toolbar buttons allows for quick software feedback, displays the status of TrueCommand and directory services configured on your system, active alerts, and shows other system management options.
Opens the TrueNAS Connect dialog that shows the current status of the service and allows you to connect to and open the login screen for TrueNAS Connect.
Update Status
Shows the system update progress and which user account started the update. Only appears in the top bar when a TrueNAS system update starts.
info
Directory Services status
Displays a dialog with the status of Active Directory and LDAP directory servers configured on the system.
assignment
Running Jobs
Displays the Running Jobs dialog. Click the History button to display the Tasks screen with a list of All, Active or Failed tasks or processes.
notifications
Alerts
Displays a list of system alerts and a dropdown list with the alert options Alert Settings and Email.
account_circle
Settings
Displays a dropdown list of setting options Change Password, Two-Factor Authentication (when enabled), My API Keys, Guide, and Log Out.
power_settings_new
Power options
Displays the power related options Restart or Shut Down.
Search UI
The Search UI global search bar allows users to search for screens and elements within the TrueNAS UI or to redirect search terms to the TrueNAS Documentation Hub.
Using Global Search
Searching UI Fields
Click the Search UI bar or type Ctrl + / to select the UI global search.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
Send Feedback
TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.
To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window.
Alternatively, go to System > General Settings and click File Ticket on the Support widget.
Rating a UI Screen
Click Rate this page to send feedback on a UI page.
You can include a screenshot of the current page and/or upload additional images with your comments.
You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.
Click Report a bug to create an engineering ticket when a TrueNAS screen or feature is not working as intended.
This submits the ticket directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click Report a bug to see the fields to create an engineering ticket for system errors, bugs, or unexpected behavior.
For example, report a bug where a middleware error and traceback occurred while saving a configuration change.
Enter a descriptive summary in the Subject.
For example, if a configuration change does not update after clicking Save and you get an error message or traceback after attempting the change, enter XYZ setting fails to save with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
I clicked the edit XYZ settings option, modified the XYZ setting, and clicked Save. The operation failed and showed the following traceback message: [include the traceback text]. My system is running TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to speed up the issue resolution.
Select Attach debug.
To attach a screenshot of the current page, select Take screenshot of the current page.
Or, before using this form, take screenshots of the screen, traceback or other error message, copy a log into a text file, or create any other file to attach.
Open this form and attach those files by selecting Attach additional images and clicking Choose File to open a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
TrueNAS displays a message telling users to check their email for verification instructions.
Status of TrueNAS Connect
TrueNAS provides quick access to TrueNAS Connect from the top toolbar in your TrueNAS system.
The Status of TrueNAS Connect icon opens the TrueNAS Connect dialog.
Before you sign up for TrueNAS Connect, the dialog shows it is waiting to connect.
After connecting to TrueNAS Connect and registering the system, the Status of TrueNAS Connect icon shows an active status indicator.
The TrueNAS Connect dialog shows the status of the active connection.
Click Open TrueNAS Connect to open the TrueNAS Connect management interface.
Click cloud_offDisable Service to disconnect the system from TrueNAS Connect.
Click on either service to go to its configuration screen.
Jobs
The Running Jobsassignment icon button opens the Running Jobs window showing a minimized view of all running, waiting, and failed jobs/processes.
Hover the mouse over an error job to view a pop-up window with the error message for that failed job.
Click the minus (-) at the top right corner of any dialog or pop-up window to minimize a job/process.
Click on a running job to open a dialog for that job.
A running job shows a progress bar and a stop_circle button to the right of the job. Click on this to show the Abort dialog.
Click Abort to stop the job and abort the process.
Beginning in 25.04, the Abort option is only available for select jobs. Jobs that are unable to be aborted are listed without the stop_circle button as an option.
Click on Go to Jobs to open the Jobs screen with tabs to screens listing all successful, active, or failed and aborted jobs.
Click on the All, Active, or Failed button at the top of the screen to show the log of jobs that fit that classification.
Click View next to a task to see the log information and error message for that task.
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Settings
The account_circleSettings button displays a menu of general system settings options.
The options are Change Password, Two-Factor Authentication (when enabled), MY API Keys, Guide and Log Out.
The dialpadChange Password button displays a dialog where you can change the login password for the currently logged-in administrator password.
The Two-Factor Authentication button displays only when global 2FA is configured and opens the Two-Factor Authentication Screen.
The laptopMy API Keys button displays the API Keys screen that lists current API keys and where you can add or manage API keys that identify outside resources and applications without a principal.
The library_booksGuide button opens the TrueNAS Documentation Hub website in a new browser tab.
The exit_to_appLog Out button logs the current user out of the TrueNAS UI.
Power
The Powerpower_settings_new button provides two options that let the user restart or shut down their TrueNAS system.
Jobs Screens: Describes the TrueNAS jobs manager and how to use it to view failed jobs and logs.
Alerts
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Contents
Alert Settings Screens: The Alert Settings screen allows users to set the warning levels and frequency of alerts.
Email Screens: Provides information on the email configuration screens for SMTP and GMail OAuth.
Alert Settings Screens
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies.
To access this screen, click the notifications icon, then click the settings icon and select Alert Settings on the dropdown list.
Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
Add/Edit Alert Service Screen
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default.
To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the more_vert icon for the service, and then click Edit to display the Edit Alert Service screen.
Name and Type Settings
Setting
Description
Name
Enter a name for the new alert service.
Enabled
Clear the checkmark to disable this service without deleting it.
Type
Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS.
Level
Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. TrueNAS sends alert notifications for all warnings matching and above the selected level. For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Alert Service Types
AWS SNS
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
Authentication Settings
Setting
Description
API Key
Enter the API key. Find the API key by signing into the OpsGenie web interface and going to Integrations/Configured Integrations. Click the desired integration, Settings, and read the API Key field.
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
Authentication Settings
Setting
Description
Hostname
Enter the hostname or IP address of the system to receive SNMP trap notifications.
Port
Enter the UDP port number on the system receiving SNMP trap notifications. The default is 162.
SNMPv3 Security Model
Select to enable the SNMPv3 security model.
SNMP Community
Enter the network community string. The community string acts like a user ID or password. A user with the correct community string can access network information. The default is public. For more information, see What is an SNMP Community String?.
Telegram
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Enter a list of chat IDs separated by a space ( ), comma (,), or semicolon (;). To find your chat ID, send a message to the bot, group, or channel and visit https://core.telegram.org/bots/api#getting-updates.
VictorOPS
Click here for more information
Select VictorOps from the Type dropdown list to display VictorOps authentication settings.
Use the Category dropdown list to display alert settings for each category.
Applications
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Click here for more information
You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.
Certificates
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Click here for more information
You can customize alert settings for when a certificate expires, a certificate parsing fails, a certificate revokes, and the web UI HTTPS certificate setup fails.
Directory Service
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
Click here for more information
You can customize alert settings for when the Active Directory bind is unhealthy, Active Directory domain validation fails, the domain is offline, and the LDAP bind bind is unhealthy.
High Availability Settings
TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only displays on the list of alerts for dual-controller High-Availability systems with an Enterprise license applied.
Click here for more information
You can customize alert settings for when an automatic sync to peer fails, disks are missing on the active and/or standby controller, the system fails to check failover status with the other controller, syncing operations fail such as encryption keys to peer and KMIP keys to peer, the failover interface is not found, and when a failover action fails.
Hardware
Hardware alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.
Click here for more information
You can customize alert settings for when disk temperature is too hot, disk(s) format with the data integrity feature, a selftest fails, erase cycle count is high, IPMI has system events, the IPMI system event log space is low, JBOF removal requires reboot, spare block reserve is low, and uncorrected errors are detected.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Key Management Interoperability Protocol (KMIP)
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Click here for more information
You can customize alert settings for when the system fails to communicate, sync the SED global password, and sync keys with the KMIP server.
Network
Network alert settings apply to network interfaces configured on your TrueNAS.
Click here for more information
You can customize alert settings for when ports are not active on the LAGG interface and when the LAGG interface has no active ports.
Reporting
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Click here for more information
You can customize alert settings for when netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.
Sharing
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Click here for more information
You can customize alert settings for when a deprecated service is running, IP addresses bound to an iSCSI portal are not found, NFS services cannot bind to specific IP addresses using 0.0.0.0, and the system cannot resolve NFS share references hosts.
You can also customize alerts for when NTLMv1 attempts authentication in the last 24 hours, SMB1 connections to TrueNAS server are performed in the last 24 hours, and a share is unavailable because it uses a locked dataset.
Storage
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
Click here for more information
You can customize alert settings for when a dataset exceeds standard and critical quotas, a pool has new available feature flags, pool space usage exceeds 70, 80, or 90 percent, and pool status is not healthy.
You can change alert settings for when a pool consumes USB disks, a scrub pauses, and too many snapshots exist.
System
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.
Click here for more information
You can customize alert settings for when the admin user is overridden, the boot pool is unhealthy, the system dataset has core files, a device slows down pool I/O, NTP health checks fail, and TrueCommand API keys are disabled or need confirmation.
You can also change alert settings for when SSH logins fail, the system is not ready for Kdump, the web UI cannot bind to a configured address, TrueCommand fails health checks, the system restarts off schedule, and update are available, failed, or not applied.
Tasks
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
Click here for more information
You can customize alert settings for when cloud sync tasks, VMWare snapshot creation, login, and deletion, replication, rsync tasks, scrubs, and snapshot tasks fail in general or due to locked datasets.
You can also change alert settings for when replication, rsync tasks, and scrubs succeed.
UPS
UPS alert settings apply to a UPS connected to your TrueNAS.
Click here for more information
You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.
Alert Warning Levels
Use the Set Warning Level dropdown list to customize alert importance.
Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
TrueNAS sends alert notifications for all warnings matching and above the selected level
For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Level
Icon
Alert Notification?
INFO
No
NOTICE
Yes
WARNING
Yes
ERROR
Yes
CRITICAL
Yes
ALERT
Yes
EMERGENCY
Yes
Alert Frequency
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
Email Screens
The top toolbar Alertsnotifications icon button and settings icon display the Alerts dropdown list with two options: Alert Settings and Email.
Select Email to go to the General settings screen and find the Email widget.
Email Widget
The Email widget on the General Settings screen displays information about current system mail settings.
Settings opens the Email Options screen that allows users to configure the system email send method.
Email Options Screen
SMTP
Gmail OAuth
Outlook OAuth
Settings Options
The account_circleSettings icon button displays a menu of general system settings options.
The options are Change Password, Preferences, My API Keys, Guide and About.
Change Password
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
My API Keys
Click on laptopMy API Keys to display the User API Keys screen where you can add or manage API keys on your system.
Click API Docs on the User API Keys screen to view API documentation.
Guide
Click on library_booksGuide to display the TrueNAS Documentation Hub in a new tab.
About
Click on About to display the information window links to the TrueNAS Documentation Hub, TrueNAS Community Forums, FreeNAS Open Source Storage Appliance GitHub repository, and iXsystems home page.
Contents
User API Keys Screen: Describes how the User API Keys screen in TrueNAS and access API Documentation
laptopMy API Keys on the top right toolbar account_circle user settings dropdown menu to opens the User API Keys screen.
This screen displays a list of API keys added to your system and allows you to add, search, edit, or delete keys.
API Docs opens the API Documentation.
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.
edit edit for any API key on the list opens the Edit API Key window to modify that key.
API Docs opens the TrueNAS API documentation that is built into the system.
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 midclt and 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.
Two-Factor Authentication Screen
Two-factor authentication is time-based and requires a correct system time setting.
The Two-Factor Authentication screen, accessed from the Settings menu on the top toolbar, allows managing user-level two-factor authentication (2FA) credentials. This option only appears in the Settings menu when an administrator has enabled Global 2FA.
Removing your 2FA configuration reduces account security. If global 2FA is enabled, you are prompted to set up 2FA again on your next login, though you can skip this prompt if needed.
Jobs Screens
The Jobs screens, accessed from the Running Jobs window after clicking Go to Jobs, shows all jobs executed on the system.
There are three tab views, All, Active and Failed. All displays by default.
Use the arrow display options to change the number of jobs per screen. Options are the default 10, 50 or 100.
Click View to display the argument passed for the selected job.
Use the north arrow beside the State or ID header to change the display order, or the south arrow to return to the top down display order.
Failed Jobs Screen
The Failed screen lists failed jobs.
Click View to show the job log. The system error for this failed job displays at the bottom of the log file.
Dashboard
The Dashboard is the first screen you see after logging into the web interface after installing TrueNAS.
It displays a set of default cards with system, help, storage, and network information, but you can customize the display to suit your needs and preferences.
Dashboard on the left side navigation panel returns to the main dashboard from any other screen in the UI.
The Configure button at the top right of the Dashboard changes the screen to configuration mode and allows you to turn card displays on or off.
Dashboard Cards
The Dashboard cards show information about the TrueNAS system basic settings, CPU and memory usage, network traffic and link status, storage, and backup tasks.
Dashboard cards are customizable. Options include changing card layouts and the location on the screen and adding custom or application cards.
Pool and network interface cards vary based on system storage and network configurations.
Click on the Reports icon to display the data report screen that corresponds to the card category.
For example, clicking the assessment icon on the CPU card opens the Reporting > CPU screen.
System Information Card
The System Information card shows general information about the TrueNAS system.
The Updates Available button opens the System > Update screen.
Shows as Generic for customer-provided server and hardware and displays the TrueNAS logo to the left of the System Information fields. The TrueNAS model number for the iXsystems-provided server and hardware and a picture of the server shows in the area to the left of the fields.
Version
Shows the currently installed software release of TrueNAS. Use the clipboard assignment icon to display the full name of the release installed and to copy the version to the clipboard.
Hostname
Shows the host name for the TrueNAS system. Configure the host name on the Network > Global Configuration screen.
Uptime
Shows the number of consecutive days, hours, and minutes of system runtime since the last restart.
Updates Available Check for Updates
Opens the System Update screen, or go to System > Update on the left-side main menu panel to open the System Update screen. Updates Available shows when systems updates are available for the current system release train.
HA System Information Cards
TrueNAS Enterprise
The two HA Active and Standby controller System Information cards show only for systems licensed for HA.
Each HA active or standby System Information card shows the same information found on the non-HA System Information card but also shows the system serial number, system license number, and type.
The standby controller card shows the Initiate Failover button.
The active controller card shows the Check for Updates button.
The CPU cards show the CPU model, dynamic gauges, and graphs of CPU usage and recent usage, and CPU usage and temperature per system core. All values are updated in real time.
The card shows gauges and graphs showing CPU statistics:
CPU Model card shows the CPU model.
CPU Usage gauge shows the average percent of usage for the CPU cores.
CPU Recent Usage gauge that shows recent CPU usage updated in realtime, and includes the CPU model number, number of cores, and physical cores.
CPU Usage per Core bar graph that shows CPU usage per core.
CPU Temperature per Core bar graph that shows CPU Usage in blue and Temperature in orange.
CPU Recent Temperature gauge that shows recent CPU temperatures updated in real time.
CPU Overview card shows the CPU model, number of cores, number of threads, highest usage percentage, hottest measured temperature, CPU average usage gauge, and bar graph of CPU usage per core.
CPU Temp card shows the current temperature of the system CPU.
Memory Card
The Memory card shows current system memory consumption information.
The card includes a gauge showing GiB Free in blue, ZFS Cache in fuchsia pink, and Services in orange.
You can configure the memory card as one large (100%) or one long (50%) plus two quarter-size (25%) card layouts.
Network and Interface Cards
The Network card shows two cards, one with a dynamic bar graph showing the time of recorded traffic and the incoming (blue) and outgoing (orange) traffic in kbs, and the status of the configured primary system interface(s), link status, network I/O traffic, and media type and subtype if known, and the other shows the primary interface IP address.
For systems with multiple interfaces, switch the card to the Interface card and set each to the interfaces on your system.
An Interface card shows traffic, link status, interface media type and subtype, and any VLANS and the IP Address and port number.
Storage and Pool Cards
The Storage card shows the primary (root) pool status, path, and number of VDEVs configured in that pool.
It also shows the percentage of used and free space and any caches.
It reports the number of disks with errors, the total number of disks in the pool, and if a spare exists.
The Storage card includes the Create Pool card that when clicked, opens the Pool Creation Wizard screen.
You can configure individual pool cards that show the same information as the root pool in the Storage card.
The Backup Task card shows links to quickly set up an automated data backup schedule if a backup task does not exist.
Click open_in_new to open the Data Protection screen with all options for checking or backing up stored data.
The card shows the number of tasks for each type of backup, the direction of data (sent or received), the number of times tasks failed and succeeded, and weekly success counters.
Help Card
The TrueNAS Help card shows links to various TrueNAS websites.
TrueNAS app logo shows if the app does not have a logo image.
App name and version.
App state, such as Running, Deploying, Stopping, Stopped, or Crashed.
App is Up to date or has an Update available.
CPU usage as a percentage and memory usage.
Network I/O incoming and outgoing traffic rates with a graph of the 1-minute average.
Block I/O disk read and write totals with a graph of the 1-minute average.
The header of each app card includes icon buttons that control the app.
Hover over a button to show its tooltip.
Button
Description
Web UI
Opens the main web portal for the app in a new browser tab. The tooltip shows the name of the portal. The card uses the portal with Web UI in its name as the main portal. If the app has no portal with that name, the card uses the first portal listed for the app. If the app does not have a web portal, this button does not show. TrueNAS replaces an address of 0.0.0.0 in the portal URL with the host name or IP address you use to access the TrueNAS web interface.
Other Portals
Opens a list of the other portals for the app. Selecting a portal name opens that portal in a new browser tab. Shows only for apps with more than one web portal.
Restart App
Restarts the app and shows the Restarting App progress dialog. The button is not available while the app state is Deploying.
Check App Details
Opens the Installed apps screen with the details for the app.
Dashboard in Configuration Mode
In configuration mode, dashboard cards are enclosed in dotted-line boxes to show the area for each card.
Add opens a blank Card Editor screen.
Save saves all changes made to the dashboard.
Cancel closes configuration mode without saving any changes. Changes made and saved on the Card Editor screen are discarded if you click Cancel.
Save saves any changes and exits configuration mode.
Cancel exits configuration mode without saving changes.
Pressing Esc (escape) also exits configuration mode and discards any changes made to card configurations or placements.
Card Layouts and Controls
Each card area uses one of five layouts. A layout holds one to four cards of different sizes and configurations.
Layout options show on the Card Editor screen.
Each card shows three function icons:
Drag handle that allows you to grab and move the card to a new location on the screen.
Dragging a card to a new location shifts the other cards one position to the left or right depending on where the dragged card is placed.
Edit opens the Card Editor populated with the settings for the existing card.
Delete removes the card from the Dashboard.
Pressing Tab allows selecting the next button or function icon on the screen and across all cards.
Card Editor
Access to the Card Editor screen is available when the Dashboard screen is in configuration mode.
The edit icon for any card opens the Card Editor populated with the current settings for that card.
Add opens the Card Editor with no settings.
Select an individual card in a layout with multiple cards to change the category and type and customize the display of the card.
The editor shows a preview of the layout and a settings section for the selected card, such as Card 1 Settings.
Sets the layout of the cards in the group. Clicking on a layout image add one to four cards in the group. Not all card categories support all layouts.
Card Category
Sets the information category to the dropdown list option selected. Each option shows the number of card types it includes, for example, Apps (5 cards):
Empty - Default selection for a new card. Use to fill a grouping of multiple cards where only two are defined and the others are not.
Apps - Use to set up a card that shows the status and resource usage of an installed app.
Storage - Use to set up a storage or single pool card.
Network - Use to set up a network card.
Help - Use to include the card with links to TrueNAS resources.
Memory - Use to set up a memory-usage card.
Backup Tasks - Use to set up a card showing either configured data protection tasks or links to locations to configure tasks.
CPU - Use to set up a CPU usage card.
System Information - Use to add one of four system information card types.
Custom - Use to set up a text-only card with whatever text-based information you want to include on the Dashboard.
The Card Type field shows after selecting the category.
Card Type
Sets the type of information shown in the selected card. Options change based on the selected Card Category. See Card Type Options by Category for information on the options by the category and type selected.
Card Type Options by Category
Card Type Options for Network
There are three types available when Card Category is set to Network.
Selecting Interface, IPv4 Address or IPv6 Address as the type adds the Interfaces field to the screen.
Interface shows the interface ID, link state, I/O traffic, Media type and subtype, and IP address assigned to the interface, and the dynamic bar graph for the I/O traffic.
Can use a full or half-size card.
IPv4 Address and IPv6 Address can use a full, half, or quarter-size card. Shows the IP address for the selected interface.
Select the interface to show in the card from the Interface dropdown field.
Card Type Options for Storage
There are six card types available when Card Category is set to Storage.
Selecting any of these types adds the Pool field to the screen. Select the pool to show in the card from the dropdown list.
Card Type
Size
Storage
Full
Pool
Full
Pool Usage
Full, half, or quarter
Pool Status
Quarter
Disks w/ZFS Errors
Quarter
Last Scan Errors
Quarter
Card Type Options for Help
Only Help is the available card type when Card Category is set to Help.
The Help card can use a full, half, or quarter-size card, but using the half or quarter size adds scrollbars to the card to provide access to the full content in this card category.
For best viewing and access to the content, we recommend using the full size for the Help card.
Card Type Options for Memory
Only Memory is the available card type when Card Category is set to Memory.
The Memory card can use a full, half, or quarter-size card, and can be included in a layout with other card categories and types.
Card Type Options for Backup Tasks
Only Backup Tasks is the available card type when Card Category is set to Backup Tasks.
The Backup Task card can only use a full-size card.
Card Type Options for CPU
Only CPU Model, CPU Overview, and CPU Temp are available as card types when Card Category is set to CPU and a full layout is selected.
CPU Recent Temperature, CPU Recent Usage, CPU Usage Per Core, CPU Temperature Per Core, and CPU Usage become available as a Card Type when full, half, or quarter-sized layouts are selected.
Card Type Options for System Information
The System Information card has six Card Type options, Hostname-Active, OS Version, Serial-Active, and System Image, System Information-Active, and System Uptime.
HA systems, with two controllers and an HA license, show the Hostname-Standby, Serial-Standby, and System Information-Standby card types.
TrueNAS Enterprise
The dashboard in larger systems with hundreds of drives have a slower response when populating the screen cards in normal and configuration mode.
Be patient and wait until your system is fully online before attempting to customize dashboard cards.
HA-licensed system dashboards show the active and standby controller cards in a full-size card.
The System Information card displays the following Card Type options: Hostname - Active, Hostname - Passive, OS Version, Serial - Active, Serial - Passive, System Image, System Information - Active, System Information - Standby, and System Uptime.
OS Version, System Uptime, or System Image can use a full, half, or quarter-size card.
These can be included in a layout with other card categories and types to create a mixed information card.
Card Type Options for Apps
There are five card types available when Card Category is set to Apps.
Selecting any of these types adds the required Application field to the screen. Select the installed app to show in the card from the dropdown list.
Shows the app logo, name, version, state, update status, CPU usage, memory usage, network I/O, and block I/O.
Application Information
Half
Shows the app logo, name, version, state, and update status.
Application Network
Half
Shows the app logo and network I/O traffic.
Application CPU Usage
Quarter
Shows the CPU usage of the app as a percentage.
Application Memory
Quarter
Shows the memory usage of the app.
Every app card type includes the control buttons described in the App Cards section.
If you uninstall (delete) the app shown in an app card, the dashboard does not remove the card.
Edit the card to select a different app, or delete the card.
Card Type Options for Custom
The Custom card has only the Arbitrary Text as the card type but also shows the Card Title, Card Text, and Card Subtext fields.
Enter text that does not exceed the maximum character count for the Custom card, which is 200 upper and lower case alpha-numeric or special characters.
Spaces between characters count as characters.
Storage
The Storage Dashboard screen allows users to configure and manage storage resources such as pools (VDEVs) and disks.
The dashboard widgets organize functions related to storage resources.
No Pools Screen
The No Pools screen displays before you add the first pool.
Select a pool from the Pool dropdown list.
These are ZFS storage pools previously created and stored on disks connected to the TrueNAS system.
TrueNAS detects these as present on the system but not yet connected in TrueNAS.
Import starts connecting to the pool and bringing it into TrueNAS.
Export/Disconnect opens the Export/disconnect pool: poolname window where users can export, disconnect, or delete a pool.
The Export/disconnect pool window includes a warning stating that data becomes unavailable after export and that selecting Destroy Data on this pool destroys data on the pool disks.
Exporting/disconnecting can be a destructive process!
Back up all data before performing this operation. You might not be able to recover data lost through this operation.
This window displays the share type (i.e., SMB share, etc.) affected by the export/disconnect operation if a share uses the pool.
Disks in an exported pool become available to use in a new pool but remain marked as used by an exported pool.
If you select a disk used by an exported pool for use in a new pool, the system displays a warning message about the disk.
Setting
Description
Destroy data on this pool?
Select to erase all data on the pool. A field displays where you enter the pool name to confirm the operation before the Export/Disconnect button activates.
Delete configuration of shares that use this pool
Enabled by default to remove the share connection to this pool. Exporting or disconnecting the pool deletes the configuration of shares using this pool. You must reconfigure the shares affected by this operation.
Confirm Export/Disconnect
(Required) Select to confirm the operation and accept the warnings displayed. Activates the Export/Disconnect button.
Export/Disconnect executes the process and begins the pool export or disconnect.
A status window shows progress. When complete, a final dialog states that the export/disconnect completed successfully.
Expand Pool
Select Expand Pool to increase the pool size to match all available disk space.
Users with pools using virtual disks use this option to resize these virtual disks apart from TrueNAS.
After adding a pool, the screen displays storage and pool widgets.
The set of four pool widgets and the Export/Disconnect and Expand buttons show for each pool created on the system.
Each set of pool widgets provides access to screens for disks, datasets, VDEVs, snapshots, quotas, and pool ZFS functions for the pool.
For example, Manage Devices on the Topology widget opens the Devices screen with the VDEVs configured for only that pool.
Unassigned Disks Widget
The Unassigned Disks widget at the top of the Storage Dashboard shows when disks are available to add to a new or existing pool.
If the system has disks available and that are associated with exported pools, the Disks with Exported pools shows instead.
The number of available disks shows, and the Add to Pool button.
The pool with the system dataset, and the state of the pool, shows in the dialog.
Add to Pool opens a window with two options:
New Pool
Existing Pool
Existing Pool shows the Existing Pool dropdown list of pools on the system.
Add Disks opens the Pool Creation Wizard when New Pool is selected. It opens the Add VDEVs to Pool wizard when Existing Pool is selected.
The Storage link in the breadcrumb at the top of the screen returns you to the Storage Dashboard to cancel out of adding to a new or existing pool.
If you attempt to use a disk assigned in an exported pool, a warning message prompts you to select a different disk.
To see information on each disk on the system, click View Disks on the Disk health widget
Add to Pool on the Unassigned Disks widget opens the Add to Pool window.
It displays the number of unassigned disks and provides the option to assign these disks to a new or existing pool.
Add Disks opens the Pool Manager screen if the existing pool was created with the Pool Manager, otherwise it opens the Pool Creation Wizard.
If you select New Pool, Add Disks opens the Pool Creation Wizard screen.
VDEVs Widget
The VDEVs widget shows information on the VDEVs configured on the system and the status of the pool.
The widget lists each VDEV type (data, metadata, log, cache, spare, and dedup) associated with the pool.
A Data VDEV includes the data type (stripe, mirror, RAID, or mixed configuration), the number of disks (wide), and the storage capacity of that VDEV.
View VDEVs opens the VDEVs screen where you can add or manage existing VDEVs.
Status Indicators
Each pool widget includes a color-coded icon just to the right of the header, near the VDEV lists to indicate the state of the pool VDEV, or near disks in the VDEV. Possible states are:
Green circle with checkmark for a Healthy
Orange circle with an exclamation mark for No Redundancy or Pool is Unhealthy
Red circle with an x for Pool is not Healthy
This same information displays on the main Dashboard on the Storage widget and a pool widget.
Usage Widget
The Usage widget shows information on the pool space datasets consumed and the status of pool usage.
The widget includes a color-coded donut chart that illustrates the percentage of space the pool uses.
Blue indicates space usage in the 0-80% range, and red indicates anything above 80%.
A warning message displays below the donut graph when usage exceeds 80%.
Usable Capacity details pool space statistics by Used and Available.
View Disk Reports opens the pool usage reports for the selected pool.
Large (>1 petabyte) systems could report storage numbers inaccurately.
Storage configurations with more than 9,007,199,254,740,992 bytes round to the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Scrub Now opens the Scrub Pool dialog. Start Scrub in the Scrub Pool dialog runs a check on the data integrity of the pool.
Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
Configure opens the Configure Scheduled Scrub screen.
Prune and Set Quota only show if the pool has a dedup VDEV and it contains duplicated files in the pool.
Configure Scheduled Scrub Screen
The Configure Scheduled Scrub screen sets a schedule for TrueNAS to run a scrub operation.
A scrub is a data integrity check of your pool.
Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
By default, TrueNAS automatically checks every pool to verify it is on a recurring scrub schedule.
If TrueNAS detects problems during the scrub, it corrects them automatically or generates an alert.
Enabled shows the schedule information on the Storage Health dashboard as the value for Scheduled Scrub.
When disabled, Scheduled Scrub changes to Not Set and shows the Schedule link. Schedule opens the Configure Scheduled Scrub screen.
Schedule shows a dropdown list of schedule options:
Hourly, which runs the scrub at the start of each hour.
Daily, which runs a scrub at 00:00 on the 24-hour clock.
This is the time period where system processes and demands are likely at the lowest point, and where it reduces the drain on system resources.
Weekly, which runs the scrub on Sundays at 00:00 for the same reason as with the Daily option.
Monthly, which runs on the first day of the month at 00:00.
Custom, which runs at 12.00 AM, only on Sunday.
** Create, which opens the custom schedule window where you can select the frequency (how often it runs), time (in hours and minutes), start or finish times, and set a time zone.
Threshold Days sets the days before a completed scrub is allowed to run again.
This controls the task schedule.
For example, scheduling a scrub to run daily and setting threshold days to 7 means the scrub attempts to run daily.
When the scrub is successful, it continues to check daily but does not run again until seven days have elapsed.
Using a multiple of seven ensures the scrub always occurs on the same weekday.
Save sets the schedule and adds the time and frequency to the Storage Health widget.
Starting in TrueNAS 25.10, resilver priority settings are now located in System Settings > Advanced Settings on the Storage widget.
Auto TRIM Dialog
The Edit Auto TRIM option on the ZFS Health widget opens a dialog to set Auto TRIM.
When enabled, Auto TRIM allows TrueNAS to periodically review data blocks and identify which empty blocks of obsolete blocks it can delete.
Leave unselected to incorporate day block overwrites when a device write is started (default).
Select Confirm to activate Save.
For more details about TRIM in ZFS, see the autotrim property description in zpool.8.
Prune Deduplication Table Dialog
The Prune Deduplication Table dialog shows pruning measurement options the system should use when pruning the deduplication table (DDT).
Options are Percentage and Age.
Percentage shows a slider to set the size (maximum amount of storage) percentage threshold the DDT is filled before it reaches the maximum size.
When reached, the system prunes the table.
The Deduplication Quota for poolname shows the Quota dropdown list with three options for setting the maximum size limit the deduplication table can reach.
Auto is the default option, which allows the system to set the quota and the size of a dedicated dedup VDEV.
This property works for both legacy and fast dedup tables.
View Disk Reports opens the Reporting > Disk screen for the disks in the selected pool.
Upgrade Dialog
The Storage Dashboard shows the Upgrade button for existing pools after an upgrade to a new TrueNAS release that includes new OpenZFS feature flags.
Newly created pools are always up-to-date with the OpenZFS feature flags in the installed TrueNAS release.
Storage pool upgrades are typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Consider these factors before upgrading a storage pool to the latest OpenZFS feature flags.
Upgrading can affect data.
Before performing any operation that affects data on a storage disk, always back up data first and verify the backup integrity.
New OpenZFS feature flags are permanently applied to the upgraded pool.
An upgraded pool cannot be reverted or downgraded to an earlier OpenZFS version.
A storage pool with the latest feature flags cannot import into another operating system that does not support those feature flags.
Upgrading a ZFS pool is optional.
Do not upgrade the pool when reverting to an earlier TrueNAS version or repurposing the disks in another operating system that supports ZFS is a requirement.
The upgrade only takes a few seconds and is non-disruptive. However, it is best to upgrade when the pool is not in heavy use.
The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
It is not necessary to stop any sharing services to upgrade the pool.
Section Contents
Disks: Describes UI screens and dialogs related to disk operations.
Pool Creation Wizard: Descriptions for settings and functions found in the Pool Creation Wizard.
VDEVs: Provides information on settings and functions found on the VDEVs screens and widget.
Disks
The Disks screen lists the physical drives (disks) installed in the system.
The list includes the names, serial numbers, sizes, and pools for each system disk.
Use the Columns dropdown list to select options to customize disk the information displayed.
Options are Select All, Name, Serial (the disk serial number), Disk Size, Pool (where the disk is in use), Disk Type, Description, Model, Transfer Mode, Rotation Rate (RPM), HDD Standby, Adv. Power Management, and Reset to Defaults.
Each option displays the information you enter in the Edit Disk screen or when you install the disk.
Select the checkbox to the left of a disk to display the Batch Operations options.
The checkbox at the top of the table selects all disks in the system. Select again to clear the checkboxes.
Storage in the breadcrumb at the top of the screen returns to the Storage Dashboard.
Disks Screen - Expanded Disk
Click anywhere on a disk row to expand it and show the traits specific to that disk and available options.
The expanded view of a disk includes details for the disk, options to edit disk properties, and, in some instances, the ability to wipe the disk.
The Bulk Edits Disks screen allows you to change disk settings for multiple disks simultaneously.
The screen lists the device names for each selected disk in the Disks to be edited section.
Select the minutes of inactivity before the drive enters standby mode from the dropdown list. Options are Always On or 5, 10, 20, 30, 60, 120, 240, 300, and 330. For more information, read this forum post describing identifying spun-down drives. Temperature monitoring is disabled for the standby disk.
Advanced Power Management
Select the power management profile from the dropdown list. Options are Disabled, Level 1 - Minimum power usage with Standby (spindown), Level 64 - Intermediate power usage with Standby, Level 127 - Maximum power usage with Standby, Level 128 - Minimum power usage without Standby (no spindown), Level 192 - Intermediate power usage without Standby, and Level 254 - Maximum performance, maximum power usage.
Wipe Disk Dialogs
The option to wipe a disk only displays when a disk is not assigned to a pool and is not in use.
Wipe opens three dialogs, one to select the method, a confirmation dialog, and a progress dialog that includes the option to abort the process.
The Wipe Disk diskname opens after clicking Wipe on the expanded view of a disk on the Disks screen.
Method provides options for how you want the system to wipe the disk.
Options are Quick, Full with zeros, or Full with random data.
See Wiping Disks for more information.
Abort stops the disk wipe process. At the end of the disk wipe process, a success dialog displays.
Close closes the dialog and returns you to the Disks screen.
Edit Disk Screen
The Edit Disk screen allows users to configure and manage general disk, power management, temperature alert, and SED settings for system disks not assigned to a pool.
Click Edit Disk on the Devices screen to open the the Edit Disk screen.
General Settings
Setting
Description
Name
Displays the current name of the disk. To change, enter a Linux disk device name.
Serial
Displays the serial number for the selected disk. To change, enter the disk serial number.
Description
Enter notes about this disk.
Power Management Settings
Setting
Description
HDD Standby
Select a value from the dropdown list of options or leave it set to the default Always On. This specifies the minutes of inactivity before the drive enters standby mode. For information on identifying spun-down drives, see this forum post. Temperature monitoring is disabled for standby disks.
Advanced Power Management (APM)
Sets the APM level that controls power management behavior when drives are idle, not maximum performance capabilities. When drives are actively accessed, they operate at full performance regardless of the APM setting. Lower-numbered levels prioritize power savings during idle periods, while higher levels prioritize quick response times. Power management profile options:
Disabled (the default setting)
Level 1 - Minimum power usage with Standby (spindown)
Level 64 - Intermediate power usage with Standby
Level 127 - Maximum power usage with Standby <liLevel 128 - Minimum power usage without Standby (no spindown) <liLevel 192 - Intermediate power usage without Standby <liLevel 254 - Maximum performance, maximum power usage
Pool Creation Wizard
The Pool Creation Wizard configuration screens include a configuration preview and an inventory list of disks available on the system.
Create Pool at the top right of the Storage Dashboard screen opens the Pool Creation Wizard.
Configuration Preview lists pool and VDEV settings that dynamically update as you configure settings in the wizard.
Inventory displays the number of available disks by size on the system, and this list dynamically updates as disks move to VDEVs added in the wizard.
Pool Creation Wizard
The Pool Creation Wizard for most systems has seven configuration screens, numbered in sequence, to create a pool with VDEVs.
TrueNAS Enterprise
Larger iXsystems-provided servers for Enterprise users equipped with expansion shelves include the additional Enclosure Options screen.
Each wizard VDEV configuration screen includes the Automated Disk Selection and Advanced Options areas.
Click Manual Disk Selection to open the Manual Selection screen.
Back and Next move to the previous or next wizard screen.
Reset Step clears the VDEV settings for the VDEV type selected. For example, Data VDEV configuration.
Save And Go To Review saves the current selections and goes directly to the Review wizard screen.
General Info
The General Info area includes two default settings, Name and Encryption.
Name is a required field.
A pool name can have up to 50 characters and must follow ZFS naming conventions.
Use lower-case alpha characters to avoid potential problems with sharing protocols.
Names can include numbers and special characters such as underscore (_), hyphen (-), colon (:), or a period (.).
Do not begin a pool name with a special character.
Encryption applies key-type encryption to the pool.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Enables ZFS encryption for the pool and all datasets (or zvols) within the pool created using the TrueNAS UI.
See Storage Encryption for more information on using TrueNAS storage encryption.
An encryption warning dialog opens with a Confirm option.
Confirm enables the I Understand button. I Understand continues with adding the pool with encryption applied.
Keep the encryption key file in a safe location where you perform regular backups.
Losing the encryption key file results in lost data you cannot recover.
If system disks contain data exported from pools, a warning displays with a checkbox for the pool name.
Allow non-unique serialed disks has two options, Allow and Don’t Allow.
Allow permits using disks with non-unique serial numbers, such as those that can occur on virtual disks.
The Data wizard screen shows the disks as available.
Don’t Allow does not permit using disks with non-unique serial numbers.
TrueNAS Enterprise
Enclosure Options
The Enclosure Options wizard screen shows if the Enterprise system has one or more expansion shelves.
The three radio button options apply a dispersal strategy that sets pool storage configuration topology. A dispersal strategy determines how the system adds disks by size and type to the pool VDEVs created when using the Automated Disk Selection option. Enclosures in the options below refer to the disk enclosures in the expansion shelves and system chassis.
No Enclosure Dispersal Strategy does not apply a dispersal strategy and does not show additional options.
Disks added to the pool VDEVs are assigned in sequence based on disk availability but are not balanced across all enclosures.
Maximum Dispersal Strategy applies a maximum dispersal strategy, which balances disk selection across all enclosures and available disks.
Does not show additional options. Disks added to the pool VDEVs are spread across all available enclosure disks.
Limit Pool To A Single Enclosure applies a minimum dispersal strategy.
Shows the Enclosure dropdown with a list of available expansion shelf options.
Disks added to the pool VDEVs are spread across the enclosure disks that align with the selection in Enclosure.
The Data wizard screen shows options to automatically or manually add disks to a data VDEV.
A pool must have a data VDEV before you can add other types of VDEVs to the pool.
The Layout dropdown list shows the Stripe, Mirror, RAIDZ1, RAIDZ2, RAIDZ3, dRAID1, dRAID2, and dRAID3 VDEV types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Log (Optional)
The Log wizard screen settings configure a log VDEV. ZFS log devices can improve the speeds of synchronous writes.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Spare (Optional)
The Spare wizard screen settings configure a hot spare for a drive in a data VDEV.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Cache (Optional)
The Cache wizard screen settings configure a ZFS L2ARC read-cache VDEV.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Metadata (Optional)
The Metadata wizard screen settings configure a special allocation class VDEV. Metadata VDEVS are used to speed up metadata and small block I/O. Use when creating a fusion pool.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Dedup (Optional)
The Dedup wizard screen settings configure a deduplication VDEV. A Dedup VDEV stores de-duplication tables.
Size dedup VDEVs as x GiB for each x TiB of general storage.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Manual Selection Screen
The Manual Selection screen shows settings to add a Data VDEV Layout and the individual disks available to add to the new VDEV.
You can filter disks by type or size.
Add places a VDEV area to populate with individual disks.
The screen shows disk icons for available disks.
The system dropdown list also shows a list of available system disks.
Use the disk filters separately or together to find disks of the same type and size.
Drag disks to the VDEV to add them.
Save Selection creates the VDEV and closes the window.
Inspect VDEVs opens the Inspect VDEVs screen that shows the VDEVs with assigned disks added to the pool.
Start Over clears the current pool configuration so you can start over.
Create Pool completes the configuration process and adds the pool.
VDEVs
The VDEVs screen lists VDEVS and disks configured for the selected pool.
Go to Storage and click on View VDEVs on the VDEVs widget to view the VDEVs screen.
Click anywhere on the VDEV to see the drives in it and the ZFS Info widget for that VDEV.
Add VDEV opens the Add a VDEVs to Pool screen with the Pool Creation Wizard for the selected pool.
For example, find the VDEVS widget for a pool and click View VDEVs.
This opens the Pool Creation Wizard with tank prepopulated but not editable.
ZFS Info Widget
The ZFS Info widget for the VDEV shows a count of read, write, and checksum errors for that VDEV. It can show the Remove or Offline buttons, and the Extend and Remove options.
Extend opens the Extend VDEV dialog where you select a disk from the New Disk dropdown to add a new disk to the VDEV.
Remove opens the Remove device dialog where you confirm you want to remove the selected VDEV.
To remove a drive from the VDEV, select the drive, then select Detach on the ZFS Info widget to remove the drive from the VDEV (pool).
DiskWidgets
Each disk in a VDEV has two widgets that show information for that disk: ZFS Info and Disk Info.
After selecting a disk, the widgets show on the right side of the screen in the Details for diskname area of the screen.
The ZFS Info widget for each device (disk drive) in the VDEV shows the name of the VDEV (Parent), the read, write, and checksum errors for that drive, and the Detach and Offline options.
Offline opens a confirmation dialog and takes the selected drive to an offline state before taking a disk offline to replace it.
Toggles to Online so you can bring a replacement disk online.
After taking a drive offline, you can remove or replace the physical drive.
The Disk Info widget shows the disk size, transfer mode, the serial and model numbers for the drive, type of drive, HDD standby setting, and a description associated with the selected drive.
Member Disk lists selectable disks to add a new disk to the pool.
The system prevents losing existing data by stopping an add operation for the new disk if it is already in use or has partitions present.
Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
Preserve disk description maintains any descriptions associated with the original disk. Selected by default. Disable it before changing the replacement disk descriptors attached to the original disk.
Replace Disk adds the new disk to the pool.
Datasets
The Datasets screen and widgets show information about datasets and zvols, provide access to data management functions, indicate the dataset roles, list the services using the dataset, show encryption status, and list permissions for datasets.
The screen focuses on managing data storage, including user and group quotas, snapshots, and other data protection measures.
Datasets Screen
The Datasets screen shows No Datasets and a Create Pool button until you add a pool and the first root dataset.
After creating a dataset, the screen shows the dataset tree table on the left and the Details for datasetnamedataset widgets on the right.
The tree table with multiple datasets lists parent and child datasets (or zvols) on the system. Icons representing the storage type or a service, such as SMB share or the system dataset, show at the right of a row.
Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round to the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Begin typing the name of a dataset in the Search field to filter datasets to a short list of those matching what is typed.
Dataset Tree Table
The datasets tree table shows an expandable hierarchical structure, starting with the root dataset, then each non-parent or parent and child datasets, with the child datasets nested under each parent dataset.
The top row of the tree table is selected by default when you go to the Datasets screen. The widgets on the right show information for the selected dataset.
Click on any parent dataset to expand the tree table to show nested child datasets.
The table of datasets shows used and available storage space for each dataset, encryption status (locked, unlocked, or unencrypted), and dataset usage, such as the services using it (e.g., the system dataset, a share, virtual machine, or application).
Datasets and zvols have different icons.
The icon represents zvols.
The icon represents a dataset.
Tree Table Encryption Icons
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
Tree Table Usage Icons
The dataset tree table shows icons representing the service type. Hover over the icons to view the description or icon label.
Usage in the dataset tree corresponds to the Usage widget.
A dataset with an active task includes an activity spinner when that task is in progress.
Usage
Icon
Description
System dataset
Indicates the parent (root) dataset designated as the system dataset. To change the system dataset, go to System > Advanced Settings and edit the System Dataset Pool on the Storage widget.
Share
Indicates the dataset is used by a share or that child datasets of the parent are used by a share.
SMB share
Indicates the dataset is used by an SMB share.
VM
Indicates the dataset is used by a virtual machine (VM).
Apps
Indicates this dataset is used by an application and stores configuration and container-related data.
Dataset Details Widgets
Each dataset has a set of information cards (widgets) in the Details for datasetname area of the screen.
These widgets and information is grouped by functional areas.
The widgets for a root or parent dataset differ from a child dataset, or a dataset used by another service or with encryption.
Sync - Shows the type of dataset.
For example, STANDARD for non-root datasets or ROOT DATASET for the first pool or root dataset, which is usually the system dataset.
Compression - Shows the compression algorithm applied to the dataset. See Data Compression Algorithms for more information.
Enable Atime - Shows if this is on or off. See Advanced Options for more information.
ZFS Deduplication - Shows if ZFS deduplication is on or off. See Advanced Options for more information.
Case Sensitivity - Shows if case sensitivity is on or off. See Advanced Options for more information.
Path - Shows the mount path to the dataset.
A root dataset path shows the pool name alone. If there are multiple pools on the system, the first pool created is the system dataset.
The root dataset for a pool is the top-level container in your pool, sharing the same name as the pool itself.
When managing your TrueNAS system, it is generally best practice to create dedicated datasets under the root dataset for different types of data, rather than storing data directly in the root dataset itself.
Edit opens the Edit Dataset screen for the selected dataset.
Delete shows on the Details widget for non-root datasets.
Use the Disconnect/Export option on the Storage Dashboard screen to deleate a root dataset.
Delete opens a Delete dataset window with information about other options or services using the dataset, for example, a parent to other datasets, the services child datasets of a parent dataset uses, shares like SMB and/or NFS, or a multiprotocol share, and the path to the datasets the shares use.
Promote shows on the Details widget for a dataset created by cloning a snapshot on the dataset tree table.
It promotes the cloned child dataset and allows users to delete the parent volume that created the clone.
Otherwise, you cannot delete a clone while the original volume still exists.
See zfs-promote.8.
Delete Window
The Delete window shows information about the dataset, including the path, services that depend on the dataset, and shares using the dataset and the path to the dataset.
If a service does not use a dataset, the Delete window does not show a service.
The window includes a field where you enter the path to the dataset.
Confirm activate the Delete Dataset button.
Delete Dataset deletes the dataset and all data it contains.
Space Management Widget
The Space Management widget shows the total space allocation (data written, children of the dataset, available space).
The widget shows if an encrypted dataset is unlocked. After locking the dataset, this widget disappears until you unlock the dataset.
The donut graph on the widget provides at-a-glance information and numeric values for the space allocated and used in the selected dataset.
This includes data written and space allocated to child datasets of this dataset. It shows the available space in the dataset.
Manage User Quota opens the User Quotas screen.
Manage Group Quotas opens the Group Quotas screen.
Edit opens the Capacity Settings screen where you can set quotas for the dataset.
Data Protection Widget
The Data Protection widget shows snapshot and backup task information for the dataset.
View Snapshot Tasks opens the Data Protection screen where you can add or manage scheduled periodic snapshot tasks.
No Backup Tasks shows when no data protection backup tasks are created.
Go to Backups opens the Data Protection screen, where you can manage scheduled replication, rsync, and other data protection tasks.
Permissions Widget
The Permissions widget shows the type of ACL permissions applied to the dataset.
ACL types can be NFSv4 or Unix Permissions (POSIX), and each lists access control user or group entries, and the owner and group for the dataset.
The widget shows the owner and type of access control list (ACL) and ACL Entries (ACEs) for the dataset in the lower portion of the widget.
Owner shows both the onwer user and group on one line, formatted as owner:group. For example, Owner: root:root.
The permission screen and widget options vary based on the ACL type.
Root datasets have POSIX permissions, and the entries are not editable.
NFSv4 ACL type (the default ACL type) shows the user and group entries on the Permissions widget as buttons that show selectable options to change selectable Permissions Advanced and Flags Advanced options for that entry on the Permissions widget.
The Usage widget shows the dataset role or services that use it (i.e., a share, application, virtual machine, or the system dataset).
It shows an icon for and information about the service using the dataset. A corresponding icon shows on the row for the dataset in the dataset tree table.
The Manage Advanced Settings shows for the system dataset, and opens the Advanced Settings screen.
If the dataset is associated with a share, a Manage SMB Share link shows. where SMB is the share type and opens the corresponding share screen.
It shows Not Shared if the dataset is configured with a share preset like SMB but does not have a share created.
The Usage widget shows two links: Create SMB Share that opens the Add SMB screen and Create NFS Share that opens the Add NFS screen.
Shows the name of the SMB and NFS share using the dataset. Each link opens the Sharing SMB or Sharing NFS screens. Click on the share to edit it.
Encryption Widget
The Encryption widget only shows for encrypted datasets.
Options shown in the widget vary based on the type of dataset (root, non-root parent, or child dataset), and whether the dataset is a encrypted parent or an encrypted child dataset that inherits settings from the parent.
It includes the current state of the dataset encryption, the encryption root, and the type.
The Encryption widget shows Lock when the dataset is unlocked or Unlock when the dataset is locked.
These are not available on the widget for the root dataset. The dataset table also shows Locked or Unlocked by Parent.
The Encryption widget shows Export Key when the encryption type is set to key.
Export Key downloads the system-generated encryption key to a JSON file. You can find this in your Windows Downloads folder.
Edit opens the Edit Encryption Options for datasetname window. A root dataset does not include the Edit button.
We do not recommend encrypting the root or system dataset!
For more details on encryption windows and functions, see Encryption Settings.
Add and Edit Dataset Screens
The Add Dataset and Edit Dataset screens allow admin users with full control access to create and manage datasets.
Both screens include the same Advanced Options settings but you cannot change the dataset name, Dataset Preset selection, or the Case Sensitivity settings on the Advanced Options screen after clicking Save on the Add Dataset screen.
Edit on the Dataset Details widget opens the Edit Dataset screen.
Edit on the Encryption widget opens an encryption edit window. The Encryption widget only shows if a dataset is encrypted.
Edit on the Permissions widget opens the Edit ACL screen to edit dataset NFSv4 permissions.
POSIX ACLs open the Unix Permissions Editor screen.
Add Dataset and Edit Dataset screens include the Basic Options and Advanced Options.
TheBasic Options and Advanced Options screens shows the Name and Options section.
A read-only field populated with the full dataset path, from the pool root dataset down to the dataset. Adds the name of the dataset after it is entered in Name. For example, tank/shares/smbshare1. The dataset name and parent path name are combined and limited to a 200-character maximum length. The maximum nested directory level names in a path are limited to 50. You cannot create a dataset at the 51st level in the directory hierarchy after you account for the nested levels in the parent path.
Name
Text entry field that accepts manual or copy/paste entry of a unique identifier for the dataset. Names can consist of upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters. Names cannot have trailing spaces after the dataset name. The dataset name and parent path name are combined and limited to a 200 character maximum length. The maximum nested directory level names in a path are limited to 50. You cannot create a dataset at the 51st level in the directory hierarchy after you account for the nested levels in the parent path. You cannot change the dataset name after clicking Save. The Name field on the Edit Dataset screen shows the path but is not editable.
Dataset Preset
Presets configure dataset settings and permissions based on the type of data sharing the dataset uses, for example, SMB/NFS shares, apps, or generic storage. The options optimize the dataset for a sharing protocol or app, and set the ACL type (NFSv4 or POSIX) best suited to the dataset purpose. Options are:
Generic - Use for general storage datasets that are not associated with SMB, NFS, or multi-protocol shares, or apps. Created with a POSIX ACL.
SMB - Optimizes the dataset for SMB shares. Preselects the Create SMB Share option and populates the SMB Name field with the value entered in Name. Created with an NFSv4 ACL.
Apps - Optimize for use by any application. Created with an NFSv4 ACL. If planning to deploy container applications, the system automatically creates the ix-apps dataset for Docker storage for application data. For data storage for individual apps, create separate datasets.
Multiprotocol - Optimized for multi-protocol or mixed-mode NFS and SMB sharing protocols, or to create only an NFS share. Allows clients to use either protocol to access the same data. The Create NFS Share and Create SMB Share options are pre-selected, and the SMB Name field populates with the value entered in Name. See Multiprotcol Shares for more information. Created with an NFSv4 ACL.
This setting cannot be edited after saving the dataset.
Advanced Options
The Add Dataset and Edit Dataset screens show the Advanced Options button.
Advanced Options show:
Setting a quota defines the maximum allowed space for the dataset or the dataset and its child datasets.
You can reserve a defined amount of pool space to prevent automatically-generated data like system logs from consuming all available dataset space.
You can configure quotas for only the new dataset or include all child datasets in the quota.
Quota management settings on the Advanced Options screen set quotas for the selected dataset, and can set the quota for the child datasets of the selected dataset.
The Edit button on the dataset Space Management widget opens the Capacity Setting
Options for user or group levels can be accessed from the Storage Dashboard screen.
The quota management settings options:
This Dataset - Sets quotas for only the selected dataset.
This Dataset and Child Datasets - Sets quotas for the child datasets of the selected dataset.
These settings also display on the Capacity Settings screen that sets quotas at the pool level.
Quota for this dataset Quota for this dataset and all children
Enter a value to define the maximum allowed space for the dataset. 0 disables quotas.
Quota warning alert at, %
Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Quota critical alert at, %
Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Reserved space for this dataset Reserved space for this dataset and all children
Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.
Encryption Options Section
Encryption settings apply key or passphrase type encryption to the selected dataset, and encrypt any child datasets of an encrypted parent.
Encryption settings show on in the Advanced Options screen for the Add Dataset screen, but not on the Edit Dataset screen.
Edit on the Encryption widget opens the Edit Encryption Options for datasetName window, showing the current encryption settings for the selected dataset and allowing you to change the encryption type settings.
Inherit (Non-Encrypted) shows when you create an unencrypted dataset.
Inherit (Encryption) shows when you create an encrypted dataset. All child datasets created under an encrypted dataset are encrypted.
The Encryption option (pre-selected), when selected, shows the key type encryption settings by default.
Passphrase in Encryption Type to show other settings.
Selected by default. When selected, it inherits the encryption setting of the parent dataset (encrypted/non-encrypted). Clearing the checkmark shows the Encryption option.
Encryption
When selected, shows other encryption settings. The default encryption type is key. Clearing the Encryption checkmark hides the encryption settings.
Setting
Description
Encryption Type
Shows two encryption type options:
Key - Shows key-based encryption settings. Shows a system-generated key field, an option to use a manual entry key, and key-based encryption algorithms.
Passphrase - Shows text fields for manual or copy/paste entry of a passphrase, and passphrase authentication algorithms.
Generate key
Shows when Encryption Type is set to Key. Selected by default and sets TrueNAS to generate a random encryption key for securing the dataset. Clearing the checkbox shows the Key field that accepts manual or copy/paste entry of an encryption key. Warning! The encryption key is the only means to decrypt the information stored in a key-encrypted dataset. Store encryption keys in a secure location! Creating a new key file invalidates a previously downloaded key file (for this dataset). Delete any previous key file backups and back up the new key file.
Key
Text entry field that accepts manual or copy/paste entry of an encryption key string to secure the dataset.
Algorithm
Shows a dropdown list of mathematical instruction algorithms that determine how plaintext converts into ciphertext for key and passphrase encryption types. See Advanced Encryption Standard (AES) for more details on each option.
Passphrase Confirm Passphrase
Text entry fields that accept manual or copy/paste entry of an alphanumeric string or phrase to secure the dataset.
pbkdf2iters
Sets the number of password-based key deviation function 2 (PBKDF2) iterations used for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Other Options Section
The Other Options section tunes the dataset for specific data-sharing protocols, sets compression level, sync type options, ACL type and mode, and other settings.
Text entry field for optional text to describe or define the dataset usage or any other information to associate with the dataset.
Sync
Sets the sync type to the option selected on the dropdown list. Options are:
Standard - Uses the sync settings requested by the client software.
Always - Waits for data writes to complete.
Disabled - Never waits for writes to complete.
Compression level
Applies the compression algorithm to the option selected on the dropdown list. Options encode information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance against the amount of space saved. Options include:
LZ4 - Generally recommended as it maximizes performance and dynamically identifies the best files to compress.
ZSTD - Uses the Zstandard compression algorithm. Has several options for balancing speed and compression.
Gzip - Has options that range from 1 for least compression with best performance or 9 for maximum compression with greatest performance impact.
ZLE - Has a fast algorithm that only eliminates runs of zeroes.
LZJB - A legacy algorithm that is not recommended for use.
Enable Atime
Sets the access time for files to the selected option on the dropdown list. Access time can result in significant performance gains. Inherit uses the access time setting of the parent or the root dataset. On updates the access time for files when they are read. Off disables creating log traffic when reading files to maximize performance.
ZFS Deduplication
Sets the option to transparently reuse a single copy of duplicated data to save space to the option selected on the dropdown list. Options:
Inherit - Uses the parent or root dataset settings.
On - Uses deduplication.
Off - Does not use deduplication.
Verify - Use to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical.
Deduplication can improve storage capacity but is RAM-intensive. Compressing data is recommended before using deduplication. Deduplicating data is a one-way process. You cannot undo deduplicated data!
Case Sensitivity
Sets case sensitivity to the option selected on the dropdown list. Options are:
Sensitive - Assumes file names are case sensitive.
Insensitive - Assumes file names are not case sensitive.
You cannot change case sensitivity after saving the dataset. Note: The Mixed option no longer exists.
Checksum
Sets the checksum to the option selected on the dropdown list. Options:
Inherit - Uses the parent setting.
On - Uses the checksum without specifying the variant.
FLETCHER2 (deprecated) or FLETCHER4 - Uses a position-dependent checksum that uses two checksums to determine single-bit errors in messages transmitted over network channels or ZFS streams.
SHA256 (default for deduped datasets) or SHA512 - Uses a sequence of numbers and letters to check the copy of a downloaded update file is identical to the original.
SKEIN - Not supported for a file system on boot pools.
EDNOR - Not supported for file systems on boot pools, and Edon-R requires verification when used with dedup, so it automatically uses verify.
Sets the option that allows or prevents dataset modification to the option selected on the dropdown list. On prevents modifying the dataset. Off allows users to access the dataset to modify its contents.
Exec
Sets the option for executing processes from within the dataset to the option selected on the dropdown list. On allows executing processes from within this dataset. Off prevents executing processes from within the dataset. We recommend setting it to On.
Snapshot directory
Sets the option that controls visibility of the .zfs directory on the dataset from the option selected in the dropdown list. Select Visible, Invisible, or Disabled.
Snapdev
Sets the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible to the options selected on the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Copies
Sets the number of ZFS user data duplicates stored on this dataset to the option selected on the dropdown list. Select between 1, 2, or 3 redundant data copies. This can improve data protection and retention, but is not a substitute for storage pools with disk redundancy.
Record Size
Sets the logical block size in the dataset to the option selected on the dropdown list. Matching the fixed size of data, as in a database, can result in better performance.
ACL Type
Sets the access control list type to the option selected on the dropdown list. Options:
Inherit - Preserves ACL type from the parent dataset.
Off - Uses neither NFSv4 nor POSIX protocols.
NFSv4 - Cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with TrueNAS, FreeBSD, or other non-Linux ZFS implementations.
POSIX - Use when a data backup target does not support native NFSv4 ACLs. Since the Linux platform has used POSIX for a long time, many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSv4 ACLs.
All datasets within an SMB share path must have identical ACL types. For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer. This advanced setting changes ACL type and mode settings configured by the Dataset Preset option. Do not make changes here if you do not understand ACLs.
ACL Mode
Determines how chmod behaves when adjusting file ACLs to the option selected on the dropdown list. See the zfs(8)aclmode property for more information. Options:
Passthrough - Only updates ACL entries related to the file or directory mode.
Restricted - Does not allow chmod to make changes to files or directories with a non-trivial ACL. An ACL is trivial if it can be fully expressed as a file mode without losing access rules. Set ACL Mode to restricted to optimize a dataset for SMB sharing, but it can also require further optimizations. For example, configuring an rsync task with this dataset could require adding --no-perms in the task Auxiliary Parameters field.
Metadata (Special) Small Block Size
Sets a threshold block size for small file blocks you include in the special allocation class (fusion pools) to the entered value. Blocks smaller than or equal to this value are assigned to the special allocation class, while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. The default size 0 means no small file blocks are allocated in the special class. Before setting this property, you must add a metadata special class VDEV to the pool.
Data Compression Algorithms
The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Contents
Zvols: Provides information on the settings and functions found on the Zvol screens and widgets.
Capacity Settings: Provides information on the quota settings and functions found on the Capacity Settings screen.
Snapshots: Provides information on the settings and functions found on the Snapshots screen.
User and Group Quotas : Provides information on the settings and functions found on the User and Group Quota screens.
Encryption Settings: Provides information on the settings and functions found on the TrueNAS storage encryption screens.
Permissions: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.
Zvols
The zvol screens and widgets, accessed from the Datasets screen, allow you to add or edit a zvol and manage the volume storage.
Zvols are listed on the Datasets screen tree table.
The dataset tree table shows storage space used and available for that zvol (or dataset), encryption status (locked, unlocked, or unencrypted), and how that zvol or dataset is used (i.e., the system dataset, a share, virtual machine, or application).
Add Zvol shows on the Datasets screen when a dataset is selected, but does not show when a zvol is selected.
Zvol Widgets
Each zvol has a set of Details for zvolname information cards (widgets) that provide information grouped by functional areas.
Zvol widgets are:
The Encryption widget only shows if the zvol is encrypted.
Zvol Details Widget
The Zvol Details widget lists information on sync type, compression level, and ZFS deduplication settings. The Path shows the full path from a root (pool) dataset to the zvol location.
The Delete Zvol dialog shows information about other options or services that use the zvol. It also shows the services that child datasets use.
This includes information about snapshots, shares, or, if used, other services such as Kubernetes or VMs that use the dataset.
Parent and child datasets include the Delete button.
The window includes a blank field where you type the path for the zvol.
Confirm activates the Delete Zvol button.
Zvol Space Management Widget
The Zvol Space Management widget shows the space allocation (reserved, used, available) for the zvol. When an encrypted zvol is locked, you must unlock it to see this widget.
The donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected zvol.
This includes data written and space allocated to child datasets of this dataset.
The Encryption widget only shows when a zvol is configured with encryption.
It shows the current state of the encryption, the encryption root, the type, and the algorithm used.
The Encryption widget shows the Lock or Unlock options if it uses passphrase encryption.
The Export Key option shows if the zvol uses key encryption.
For more details on encryption windows and functions, see Encryption Settings.
Data Protection Widget
The Data Protection widget displays for all datasets or zvols.
It shows information for the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system.
It provides access to the tasks found on the Data Protection screen through links.
View Snapshots opens the Snapshots screen list view where you can manage snapshots.
View Snapshot Tasks opens the Data Protection > Periodic Snapshot Tasks screen list view where you can manage scheduled periodic snapshot tasks.
Go To Backups opens the Data Protection screen, where you can create a data protection task like Rsync, Replication, or Cloud Sync Backup.
Add and Edit Zvol Screens
The Add Zvol and Edit Zvol screens allow admin users with the right permission level to create and modify zvols.
Both screens include the same settings, but you cannot change the zvol name, Block Size, or select the Sparse option after you click Save on the Add Zvol screen.
After adding a zvol, click Edit on the Zvol Details widget to open the Edit Zvol screen.
When the zvol is encrypted, Edit on the Encryption widget opens a configuration screen where you can change the passphrase for a zvol encrypted with the passphrase type, but you cannot change to a key encryption type. If the zvol is not encrypted, you do not see encryption options on the Edit Zvol screen.
(Required setting) Enter a short name for the zvol longer than 63 characters to prevent potential problems accessing zvols as devices. For example, you cannot use a zvol with a 70-character file name or path as an iSCSI extent.
Comments
Enter any notes about the zvol. Descriptions show on the iSCSI screens when the zvol is used in a block share.
Size for this zvol
Specify numeric size and value. You can include units like t as in TiB, and G. You can increase the size of the zvol later, but you cannot reduce the size. If the size is greater than 80% of the available capacity, the creation fails with an out-of-space error unless you select Force size.
Force size
Enables the system to create a zvol where the size is over 80% capacity. By default, the system does not create a zvol of this size. While not recommended, enabling this option forces the creation of the zvol.
Sparse
Enables using thin provisioning where disk space for this volume is allocated on-demand as new writes are received. Use caution when enabling, as writes can fail when the pool is low on space.
Sync
Select a data write synchronization option from the dropdown list. Options:
Inherit gets the sync settings from the parent dataset.
Standard uses the sync settings requested by the client software.
Always waits for data writes to complete.
Disabled never waits for writes to complete.
Compression level
Select the option from the dropdown list for the type of data compression to use for encoding information in less space than the original data occupies. Select the algorithm that balances disk performance with the amount of space saved. See below for the options.
ZFS Deduplication
Do not change this setting unless instructed to by your TrueNAS support engineer. Transparently reuses a single copy of duplicated data to save space. Deduplication can improve storage capacity, but it is RAM-intensive. Compressing data is generally recommended before using deduplication. Deduplicating data is a one-way process. Deduplicated data cannot be undeduplicated!.
Read-only
Select the option to prevent modifying the zvol. Options are Inherit (off), On or Off.
Block size
Select the size option from the dropdown list. The default is 16KiBt, other options are 4KiB, 8KiB, 16KiB, 32KiB, 64KiB, 128KiB. The zvol default block size is automatically chosen based on the number of disks in the pool for a general use case.
Snapdev
Select the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible from the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Inherit (non-encrypted/encrypted)
Encryption settings are inherited from the parent dataset. When the parent is encrypted, this option defaults to Inherit (encrypted); otherwise, it shows (non-encrypted). Clearing the checkmark shows the Encryption options. If the parent is encrypted with the passphrase type, the zvol can only use passphrase encryption. When the parent is encrypted with a key, the zvol can use either key or passphrase encryption. Refer to the Encryption Settings article for more details.
Block Size Table
TrueNAS recommends a space-efficient block size for new zvols.
This table shows the minimum recommended volume block size values by configuration (mirror or RAIDz type).
Use this table to change the Block size value.
Configuration
Number of Drives
Optimal Block Size
Mirror
N/A
16k
Raidz-1
3
16k
Raidz-1
4/5
32k
Raidz-1
6/7/8/9
64k
Raidz-1
10+
128k
Raidz-2
4
16k
Raidz-2
5/6
32k
Raidz-2
7/8/9/10
64k
Raidz-2
11+
128k
Raidz-3
5
16k
Raidz-3
6/7
32k
Raidz-3
8/9/10/11
64k
Raidz-3
12+
128k
Depending on their workload, zvols can require additional tuning for optimal performance.
See the OpenZFS handbook workload tuning chapter for more information.
Data Compression Algorithms
The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Capacity Settings
The Capacity Settings screen allows users to set quotas for the selected dataset and for the selected dataset and any of the child datasets for the selected dataset apart from the dataset creation process.
The settings on the Capacity Settings screen are the same as those in the quota management section on the Add Dataset > Advanced Options screen.
Setting
Description
Quota for this dataset Quota for this dataset and all children
Enter a value to define the maximum allowed space for the dataset. 0 disables quotas.
Quota warning alert at, %
Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Quota critical alert at, %
Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Reserved space for this dataset Reserved space for this dataset and all children
Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.
Snapshots
The Snapshots screen lists dataset snapshots on the system.
It allows you to add new or manage existing snapshots.
Access to the Snapshots screen is available using the Manage Snapshots link on the Data Protection widget on the Datasets screen and by clicking Snapshots on the Periodic Snapshot Tasks widget on the Data Protection screen.
If the selected dataset does not have snapshots, the screen displays No Snapshots are Available.
My Snapshot screen is blank
If the Snapshots screen does not display a list of snapshots and you know you added snapshots, clear the dataset path in the search field to show all dataset and zvol snapshots on the system.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Show Extra Snapshot List Columns
Click the Show Extra Columns toggle to add extra information columns to the list of snapshots to open the Show Extra Columns dialog.
Show adds the extra columns to the list of snapshots. These columns add the space used (Used), the snapshot creation date, and the amount of data the dataset can access (Referenced).
Click the toggle again to open the Hide Extra Columns dialog. Hide to return to the default view with only the Dataset and Snapshot columns.
Snapshot Details Screen
Click anywhere on a snapshot to expand it and view more information about the snapshot and the options for that snapshot.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Option
Description
Delete
Opens a Delete confirmation dialog for the selected snapshot(s). Select Confirm to activate the Delete button.
Clone to New Dataset
Opens the Clone to New Dataset) window where you enter a new name or clone with the default value in the Dataset Name field.
Select to prevent the snapshot from being deleted. If selected and you batch-operation delete datasets, this opens an error display with the name of the dataset and prevents the delete operation from continuing.
Rollback from Snapshot Window
The snapshot Rollback option replaces the data in the selected dataset with the information saved in the snapshot.
WARNING: Rolling the dataset back destroys data on the dataset and can destroy additional snapshots that are related to the dataset.
This can result in permanent data loss!
Do not roll back until all desired data and snapshots are backed up.
There are three Stop Rollback if Snapshot Exists radio button options that impose safety levels on the rollback operation.
When the safety check finds additional snapshots directly related to the dataset you are rolling back it cancels the rollback.
Select to stop rollback when the safety check finds any related intermediate, child dataset, or clone snapshots that are newer than the rollback snapshots.
Newer Clone
Select to stop rollback when the safety check finds any related clone snapshots newer than the rollback snapshot.
No Safety Check (CAUTION)
Select to stop rollback if snapshot exists. The rollback destroys any related intermediate, child dataset, and cloned snapshots newer than the rollback snapshot.
Confirm
Select to confirm the selection and activate the Rollback button.
Use the Clone to New Dataset button to create a clone of the snapshot.
The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen.
Click Clone to New Dataset to open a clone confirmation dialog.
To delete more than one snapshot in one operation, select the checkbox beside the datasets you want to delete to display the Batch Operations Delete option.
Confirm activates the Delete button. If a snapshot has the Hold option selected, an error displays to prevent you from deleting that snapshot.
Add Snapshot Screen
The Add Snapshots screen allows you to create a snapshot while on the Snapshots screen.
It also opens when you click Create Snapshot on the Dataset Protection widget on the Datasets screen.
Save retains the settings and returns to the Snapshots screen.
Add Snapshot Settings
Setting
Description
Dataset
Select the dataset or zvol from the dropdown list. The snapshot created is from this dataset or zvol.
Name
TrueNAS populates this with a name but you can override the name with any string of your choice. You cannot use Name and Naming Schema for the same snapshot.
Naming Schema
Select an option from the dropdown list or leave this blank to use the system-populated name in the Name field. This generates a name for the snapshot using the naming schema from a previously-entered periodic snapshot. This allows replication of the snapshot. You cannot use Naming Schema with Name. Selecting a schema option overwrites the value in Name.
Recursive
Select to include child datasets or zvols in the snapshot.
User and Group Quotas
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
User Quotas Screen
Select Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.
The User Quotas screen displays names and quota data of user accounts cached on or connected to the system.
If no users exist, the screen displays No User Quotas in the center of the screen.
Click Save to save changes or click the “X” to close the window without saving.
Settings
Description
User
Displays the name of the selected user.
User Data Quota (Examples: 500KiB, 500M, 2 TB)
Enter the amount of disk space the selected user can use. Entering 0 allows the user to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
User Object Quota
Enter the number of objects the selected user can own. Entering 0 allows unlimited objects.
Set User Quotas Screen
To display the Set User Quotas screen click the Add button.
Enter the amount of disk space the selected user can use. Entering 0 allows the user to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
User Object Quota
Enter the number of objects the selected user can own. Entering 0 allows unlimited objects.
Apply Quotas to Selected Users Settings
Settings
Description
Apply To Users
Select the users from the dropdown list of options.
Click Save to set the quotas or click the “X” to exit without saving.
Group Quotas Screens
Click Manage Group Quotas on the Dataset Space Management widget to open the Group Quotas screen.
The Group Quotas screen displays the names and quota data of any groups cached on or connected to the system.
If no groups exist, the screen displays No Group Quotas in the center of the screen.
Click Save to set the quotas or click the “X” to exit without saving.
Edit Group Configuration Settings
Settings
Description
Group
Displays the name of the selected group(s).
Group Data Quota (Examples: 500KiB, 500M, 2 TB)
Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota
Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.
Set Group Quotas Screen
To display the Set Group Quotas screen, click the Add button.
Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota
Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.
Apply Quotas to Selected Groups Settings
Settings
Description
Apply To Groups
Select groups from the dropdown list of options.
Encryption Settings
Datasets, root, non-root parent, and child, or zvols with encryption include the Encryption widget in the set of dataset widgets shown on the Datasets screen.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
Dataset Encryption
The Encryption option on the Pool Manager screen sets encryption for the entire pool.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
The Download Encryption Key warning window opens when you create the pool.
It downloads a JSON file to the downloads folder on your system.
The Encryption widget for root datasets with encryption includes the Export All Keys and Export Key options. It does not include the Lock option.
If a dataset is encrypted using a key, the Encryption widget for that dataset includes the Export Key option.
Export All Keys Dialog
Export All Keys opens a confirmation dialog with the Download Keys option that exports a JSON file of all encryption keys to the system download folder.
Export Key opens a dialog showing the key for the selected dataset, and the Download Key button.
Download Key exports the key to a JSON file and saves it in your system download folder.
Encryption type and options are set for a dataset when it is first created or are inherited from the root dataset.
The Edit Encryption Options for datasetname displays the current encryption option settings for the selected encrypted dataset.
Use to change the encryption type from or to key or passphrase, and the related settings.
The Edit Encryption Options for datasetname window opens with the current dataset encryption settings displayed.
The encryption settings options are the same as those on Add Dataset > Encryption Options.
Key - Shows key-based encryption settings. Shows a system-generated key field, an option to use a manual entry key, and key-based encryption algorithms.
Passphrase - Shows text fields for manual or copy/paste entry of a passphrase, and passphrase authentication algorithms.
Generate key
Shows when Encryption Type is set to Key. Selected by default and sets TrueNAS to generate a random encryption key for securing the dataset. Clearing the checkbox shows the Key field that accepts manual or copy/paste entry of an encryption key. Warning! The encryption key is the only means to decrypt the information stored in a key-encrypted dataset. Store encryption keys in a secure location! Creating a new key file invalidates a previously downloaded key file (for this dataset). Delete any previous key file backups and back up the new key file.
Key
Text entry field that accepts manual or copy/paste entry of an encryption key string to secure the dataset.
Algorithm
Shows a dropdown list of mathematical instruction algorithms that determine how plaintext converts into ciphertext for key and passphrase encryption types. See Advanced Encryption Standard (AES) for more details on each option.
Passphrase Confirm Passphrase
Text entry fields that accept manual or copy/paste entry of an alphanumeric string or phrase to secure the dataset.
pbkdf2iters
Sets the number of password-based key deviation function 2 (PBKDF2) iterations used for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Lock Dataset Dialog
Lock shows on the Encryption widgets when you encrypt a dataset (or zvol) with a passphrase.
An encrypted child that inherits encryption from an encrypted parent does not see the Lock option on its Encryption widget when the lock state is controlled by the parent dataset for that child dataset.
The locked icon for child datasets that inherit encryption is the locked by ancestor icon.
Lock opens the Lock Dataset confirmation dialog with the option to Force unmount and Lock the dataset.
Force unmount disconnects any client system accessing the dataset via the sharing protocol. Do not select this option unless you are certain the dataset is not used or accessed by a share, application, or other system services.
After locking a dataset, the Encryption screen displays Locked as the Current State and adds the Unlock option.
Unlock Datasets Screen
Unlock on the Encryption widget shows for locked datasets that are not child datasets that inherit encryption from the parent dataset.
Unlock opens the Unlock Datasets screen, which is used when you unlock the selected dataset and child datasets simultaneously.
If you select a child dataset of a root (pool-level) dataset or a non-root parent, the screen includes only the one Dataset Passphrase field, and the option to Unlock Child Encrypted Roots is pre-selected.
Unlocks any encrypted dataset stored within this dataset.
Dataset Passphrase Dataset Key
Text entry field that accepts manual or copy/paste entry of the user-defined string (passphrase) or system-generated or user-created alphanumeric key entered when you created the dataset.
Force
Adds a force flag to the operation. In some cases, the provided key/passphrase might be valid, but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, the unlock operation fails. Adding the force flag can override this, and when selected, the system renames the existing dataset mount directory/file path and unlocks the dataset.
Save
Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Continue unlocks the dataset.
Save
Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Continue unlocks the dataset.
Permissions
TrueNAS offers two Access Control List (ACL) types: POSIX (the TrueNAS default) and NFSv4.
For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer.
The Dataset Preset option on the Add Dataset screen sets the ACL type applied for SMB shares, apps, multi-protocol shares, and general-use datasets.
The ACL Type setting in the Advanced Options on both the Add Dataset and Edit Dataset screens, determines the ACL presets available on the ACL Select a preset ACL window.
It also determines which permissions editor screens you see after you click the edit edit icon on the Dataset Permissions widget.
Set ACL Type to NSFv4 to activate and select which ACL Mode the dataset uses.
While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.
Unix Permissions Editor Screen
If you set Dataset Preset to Generic, or selected POSIX or Inherit as the ACL Type settings on the Add Dataset > Advanced Options screen, the first screen you see after clicking Edit on the Permissions widget is the Dataset > Edit Permissions screen Unix Permissions Editor.
Use the settings on this screen to configure basic ACL permissions.
POSIX ACL Owner Settings
The Owner section controls which TrueNAS user and group has full control of this dataset.
Setting
Description
User
Enter or select a user to control the dataset. Users created manually or imported from a directory service appear in the menu.
Apply User
Select to confirm user changes. To prevent errors, TrueNAS only submits changes after you select this option.
Group
Enter or select the group to control the dataset. Groups created manually or imported from a directory service appear in the menu.
Apply Group
Select to confirm group changes. To prevent errors, TrueNAS only submits changes after you select this option.
POSIX ACL Access Settings
The Access section lets users define the basic Read, Write, and Execute permissions for the User, Group, and Other accounts that might access this dataset.
A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets.
Removing this permission results in lost access to the path.
POSIX ACL Advanced Settings
The Advanced section lets users Apply Permissions Recursively to all directories, files, and child datasets within the current dataset.
To access advanced POSIX ACL settings, click Add ACL on the Unix Permissions Editor. The Select a preset ACL window displays with two radio buttons.
Select an ACL Preset
There are two different Select a preset ACL windows, one for the POSIX ACL and the other for the NFSv4 ACL.
Selecting a preset replaces the ACL currently displayed on the Edit ACL screen and deletes any unsaved changes.
For a POSIX ACL, a window with three setting options displays before you see the Edit ACL screen.
These setting options allow you to select and use a pre-configured set of permissions that match general permissions situations or to create a custom set of permissions.
You can add to a pre-configured ACL preset on the Edit ACL screen.
The ACL Type setting determines the pre-configured options presented on the Default ACL Options dropdown list on each of these windows.
For POSIX, the options are POSIX_OPEN, POSIX_RESTRICTED, or POSIX_HOME. For NFSv4, the options are NFS4_OPEN, NFS4_RESTRICTED, NFS4_HOME, and NFS4_DOMAIN_HOME.
Setting
Description
Select a preset ACL
Click to populate the Default ACL Options dropdown list with pre-configured POSIX permissions.
Create a custom ACL
Click to open the Edit ACL screen with no default permissions, users, or groups or to configure your own set of permissions. Click Continue to display the Edit ACL screen.
The Edit ACL screen options are based on ACL type (POSIX or NFSv4).
The Dataset Preset and ACL Type settings determine the ACL type. They are under Advanced Options in the Add Dataset and Edit Dataset screens
The section below describes the differences between screens for each ACL type.
ACL Editor Settings - POSIX and NFSv4
Select any user account or group manually entered or imported from a directory service in the Owner or Owner Group.
The value entered or selected in each field displays in the Access Control List below these fields.
Dataset displays the dataset path (name) you selected to edit.
The Access Control List section displays the items and a permissions summary for the owner@, group@, and everyone@ for both POSIX and NSFv4 ACL types. The list of items changes based on a selected pre-configured set of permissions.
To add a new item to the ACL, click Add Item, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.
Edit ACL Functions - POSIX and NFS4
These functions display on the Edit ACL screen for both POSIX and NSFv4 ACL types except for Strip ACL, which only displays for NSFv4 types.
Select to apply all settings or changes on the Edit ACL screen to all child datasets in the path in Dataset.
Save Access Control List
Saves settings or changes made on the Edit ACL screen.
Strip ACL
(NSFv4 only) Remove all ACLs from the current dataset and any directories or files contained within this dataset. Stripping the ACL resets dataset permissions and can make data inaccessible until you create new permissions.
Permissions Editor
(POSIX only) Displays the Unix Permissions Editor screen for POSIX ACL types.
Use Preset
Displays the Select a preset ACL window. If the ACL Type setting, found in the Advanced Options of both the Add Dataset and Edit Dataset screens, is POSIX or Inherit, the Default ACL Options dropdown displays POSIX pre-configured options. If set to NFSv4, the preset options displayed are pre-configured NSFv4 options.
Save As Preset
Saves the current access control list as a custom preset and adds it to the Access Control List.
POSIX Access Control Entry Settings
The POSIX Access Control Entry settings include Who, Permissions, and Flags options.
Select the user or group from the dropdown list the permissions apply to.
User denotes access rights for users identified by the entry qualifier. Group denotes access rights for the filegroup. Other denotes access rights for processes that do not match any other entry in the ACL. Group Obj denotes access rights for the filegroup. User Obj denotes access rights for the file owner. Mask denotes the maximum access rights User, Group Obj, or Group type entries can grant.
Permissions
Select the checkbox for each permission type (Read, Write and Execute) to apply to the user or group in Who.
Flags
Select the Default option to include a flag setting for the user or group in Who.
NFS4 Access Control Entry Settings
There are two Access Control Entry settings, Who and ACL Type.
The NFSv4 ACL Type radio buttons change the Permissions and Flags setting options. Select Allow to grant the specified permissions or Deny to restrict the permissions for the user or group in Who.
User denotes access rights for users identified by the qualifier. Group denotes access rights for groups identified by the qualifier. owner@ applies this entry to the user that owns the dataset. group@ applies this entry to the group that owns the dataset. everyone@ applies this entry to all users and groups.
ACL Type
Determines how the Permissions apply to the chosen Who. Choose Allow to grant the specified permissions and Deny to restrict the specified permissions.
NFS4 Permissions and Flags
TrueNAS divides permissions and inheritance flags into basic and advanced options. The basic permissions options are commonly-used groups of advanced options.
Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.
Basic Permissions Settings
Click the Basic radio button to display the Permissions dropdown list of options that applies to the user or group in Who.
Click the Advanced radio button to display the flag settings that enable or disable ACE inheritance and offer finer control for applying an ACE to new files or directories.
The ACE is inherited with subdirectories and files. It applies to new files.
Directory Inherit
d
New subdirectories inherit the full ACE.
No Propagate Inherit
n
The ACE can only be inherited once.
Inherit Only
i
Remove the ACE from permission checks but allow new files or subdirectories to inherit it. Inherit Only is removed from these new objects.
Inherited
I
Set when this dataset inherits the ACE from another dataset.
Shares
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares. TrueNAS allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
Click Shares on the main navigation panel to open the Sharing screen, which displays options to access SMB, NFS, iSCSI, and NVMe-oF shares.
If you have not added SMB shares to the system, the SMB widget shows text stating general information about the Windows (SMB) Shares until a share is added.
The Windows (SMB) Shares launch header shows the status of the SMB service as either STOPPED (red) or RUNNING (green). Before adding the first share, the STOPPED status displays in the default color.
The header is a link that opens the Sharing > SMB screen.
The more_vert dropdown list shows four options available to SMB shares and the SMB service in general:
Turn Off/ON Service toggles to Turn Off Service when the SMB service is enabled, and to Turn On Service when the SMB service is disabled.
Config Service opens the SMB configuration screen.
SMB Sessions opens the SMB Status screen with showing Sessions.
Audit Logs opens the Audit screen with a predefined filter applied to show the SMB logs.
The widget shows a table listing SMB shares created in TrueNAS.
Each SMB share row on the Windows (SMB) Shares widget shows the path to the shared dataset, a description if one is entered when the share is added, an Enabled toggle that allows you to enable or disable the share, and indicates if audit logging is turned on/off.
The more_vert dropdown list for each share shows four options:
The SMB table lists all SMB shares added to the system.
The table header shows the status of the SMB service as stopped or running.
The table columns show the share name, the path to the dataset for the share, and a description, if added during share creation.
The Enabled toggle allows you to enable/disable the share. When enabled, the share path is available when the SMB service is active.
If disabled, the share is disabled but not deleted from the system.
Audit Logging indicates whether auditing for the share is enabled or disabled.
The more_vert dropdown list at the right of each table row shows four options for a share:
The two SMB share configuration screens, Add SMB and Edit SMB, have the same SMB share setting options.
The Create Dataset option becomes active after selecting a parent dataset in the Path file browse field.
It opens the Create Dataset dialog.
Save creates the share (or saves an existing one) and adds it to the Windows (SMB) Shares widget and the SMB table on the SMB screen.
Enable Now appears on both the Add SMB and Edit SMB screens after selecting the Time Machine Share option in Purpose if the Enable SMB2/3 Protocol option is not already enabled in the Advanced Options section of the SMB service screen.
Enable Now also appears on both the Add SMB and Edit SMB screens after selecting the Final Cut Pro Storage Share option in Purpose if the Enable Apple SMB2/3 Protocol Extensions option is not already enabled in the Advanced Options section of the SMB service screen. When this requirement is not met, an inline requirement error message appears below the Purpose field stating: This parameter requires Apple SMB2/3 protocol extension support to be enabled in SMB service. Click Enable Now to enable the required setting. The service updates automatically.
Basic Settings
The Basic Options settings show by default on the Add and Edit SMB screens. Basic settings show for all share options in the Purpose dropdown list; only the External Share option shows the Remote Path setting.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Specifies the mount path for the share. It includes a blank field and a file browser field directly below it. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser allows selecting the mount path to the share dataset on the local file system that TrueNAS exports over the SMB protocol. The arrow_right icon to the left of expands the dataset directory tree. Root datasets do not show and cannot be selected for shares unless the share existed prior to upgrading to 25.10 or later releases.
Create Dataset
Creates a dataset for a share while configuring the share. Inactive until the parent dataset is selected. It opens the Create Dataset dialog, where you enter a name for a new dataset. The dataset name becomes the SMB share name. Create adds the dataset and populates Name field on the Add SMB screen.
Name
Sets the name for the share. This text entry field accepts manual entry or copy/paste of a name for the share that does not exceed 80 characters. A name must not exceed 80 characters because of how the SMB protocol uses the name. A name cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. Name is automatically populated with the name of the dataset when you use Create Dataset. If not supplied, the share name becomes the last component of the path. This forms part of the full share path name when SMB clients perform and SMB tree connect. If changing the name, follow the naming conventions for files and directories or share names.
Purpose
Sets the share type to one selected on the dropdown list. Options are:
Default Share - The SMB share uses standard configuration with default settings suitable for general-purpose file sharing. This is the recommended option when you do not need specialized share functionality.
Time Machine Share - The SMB share is optimized for Apple Time Machine backups. This option configures the share to serve as a backup destination for macOS devices. It requires SMB2/3 protocol support enabled in the SMB service configuration.
Final Cut Pro Storage Share - Available in TrueNAS 25.10.1 and later. The SMB share is optimized for Final Cut Pro workflows. This option requires Apple SMB2/3 protocol extensions enabled in the SMB service configuration and forcibly enables Apple name mangling for proper media file handling. Warning: Name mangling can cause unexpected behavior for existing data written without this feature enabled. See Setting Up Final Cut Pro SMB Shares for details.
Multi-Protocol Share - The SMB share is configured for multi-protocol (SMB and NFS) access. Set this if the path is shared through NFS, FTP, or used by containers or apps. Note: This setting can reduce SMB share performance because it turns off some SMB features for safer interoperability with external processes.
Time Locked Share - The SMB share makes files read-only through the SMB protocol after the set grace period ends. WARNINGS: This setting does not work if the path is accessed locally or if another SMB share without the Time Locked Share purpose uses the same path. This setting might not meet regulatory requirements for write-once storage.
Private Datasets Share - The server creates a new ZFS dataset for each user when the client connects, using the specified dataset naming schema in options. The server uses this dataset as the share path during the SMB session. This provides isolated storage spaces for individual users.
External Share - The SMB share is a DFS proxy to a share hosted on an external SMB server. Use this option to redirect users to shares on other servers.
The selected option applies predetermined settings and changes the settings shown in Other Options when showing advanced options.
Remote Path
Sets the path to a remote server and share. Each server entry must include a full domain name or IP address and the share name. Separate the server and share name with the \ characters. Example: 192.168.0.200\SHARE. This text entry field accepts copy/paste of a path to the external server and share. Shows when Purpose is set to External Share.
Description
A text-entry field for a brief description or notes about how this share is used. The description entered shows in the Description column on the Windows (SMB) Shares widget on the Shares dashboard and the SMB table on the SMB screen.
Enabled
A toggle that shows the status of the share and allows enabling or disabling the share. This does not enable or disable the SMB service. Enabled is the default setting.
Advanced Options Settings
Advanced Options settings are grouped into three categories:
Access and Audit Logging settings show for all share options in the Purpose dropdown list.
The Other Options settings change based on the share option selected in the Purpose dropdown list.
Access Settings
Access settings customize access to the share and files, and specify allowed or denied access for host names or IP addresses.
All share options listed in the Purpose dropdown show these settings.
For datasets with NFSv4 ACL type, SMB clients automatically use access-based enumeration.
This means directory listings over SMB only include files and directories for which the client has read permissions.
This behavior is enabled by default and matches FreeBSD behavior.
Setting
Description
Export Read-Only
Prohibits writes to the share when enabled.
Browsable to Network Clients
Determines whether this share name is included when browsing shares. Enabled by default. Private dataset shares (the replacement for home shares) are only visible to the owner, regardless of this setting.
Access Based Share Enumeration
Restricts share visibility to users with read or write access to the share. This setting applies to datasets with a POSIX ACL type. For datasets with NFSv4 ACL type, access-based enumeration is automatically enabled and cannot be disabled. See the smb.conf manual page.
Hosts Allow
Specifies a list of allowed IP addresses or host names. When populated, restricts access to only the addresses entered. This can break UI access for all other IP or host name entries. Separate entries by pressing Enter. See smb.conf for detailed syntax. Not available for External Share preset.
Hosts Deny
Specifies a list of denied IP addresses or host names. Works in combination with Hosts Allow to control access. Separate entries by pressing Enter. See smb.conf for detailed syntax. Not available for External Share preset.
Hosts Allow and Hosts Deny interaction:
Both empty: Any host can access the share
Hosts Allow populated, Hosts Deny empty: Only hosts in Allow list can access
Hosts Allow empty, Hosts Deny populated: All hosts except those in Deny list can access
Both populated: Hosts in Allow list can access; hosts not in either list can access; hosts in Deny list cannot access
Legacy share additional access options:
Shares with Purpose set to Legacy Share display additional access controls not available in modern presets:
Enable ACL - Configure custom ACL entries
Allow Guest Access - Enable anonymous access without credentials
The Audit Logging settings enable the auditing function for the SMB share. Configure a watch list to audit specific groups, or an ignore list to audit all groups except those specified. At least one list (watch or ignore) must contain entries for auditing to function. All share options listed in the Purpose dropdown show these settings.
For detailed information about group validation and troubleshooting disabled shares, see Configuring SMB Auditing.
Enables audit logging for the SMB share and displays two additional options: Watch List and Ignore List. This controls whether audit messages are generated for the share after configuring at least one list. Note: Auditing is not available when SMB1 support is enabled for the server. Starting in TrueNAS 25.10.1, shares are automatically disabled in the running configuration if the watch or ignore lists contain invalid groups.
Watch List
Specifies groups to audit. Click the field to display the dropdown list of group options. Auditing applies only to user accounts that are members of groups in this list. If the same user belongs to groups in both the Watch List and Ignore List, the watch list takes precedence, and operations are audited.
Ignore List
Specifies groups to exclude from auditing. Click the field to display the dropdown list of group options. If the same user belongs to groups in both the Watch List and Ignore List, the watch list takes precedence and operations are audited.
Other Options Settings
The Other Options settings vary based on the option selected on the Purpose dropdown list.
When Purpose is set to Default Share, Multi-Purpose Share or External Share, the settings below show in Other Options.
Implements the default hashing algorithm for NTFS illegal characters that Samba uses. Enabling this option translates NTFS illegal characters to the Unicode private range. Shows for all share types except when Purpose is set to the Time Machine Share or External Share.
When Purpose is set to Time Machine Share, the following settings show in Other Options.
Sets the user session identifier to a valid universally unique identifier that conforms to the UUID version 4 format (UUID4). A UUID4 string is defined by RFC 4122. UUID4 strings are randomly generated 128-bit values, typically represented as a 36-character hexadecimal string in the format 8-4-4-4-12 (e.g., 123e4567-e89b-12d3-a456-426614174000). Samba uses the UUID to identify the share uniquely for Mac OS Time Machine backups, ensuring the share is recognized as a valid backup destination. You can generate a UUID4 string using a variety of commands or through websites like https://www.uuidgenerator.net/.
Auto Snapshot
When selected, enables automatic snapshot creation for Time Machine shares.
Auto Dataset Creation
When selected, TrueNAS creates a dataset automatically if one does not exist.
When Purpose is set to Time Locked Share, these settings show in Other Options.
Implements the default hashing algorithm for NTFS illegal characters that Samba uses. Enabling this option translates NTFS illegal characters to the Unicode private range.
Grace Period
Sets the delay before access times out or the share locks. Only shows when Purpose is set to the Time Locked Share option.
When Purpose is set to Private Dataset Share, the following settings show in Other Options.
Implements the default hashing algorithm for NTFS illegal characters that Samba uses. Enabling this option translates NTFS illegal characters to the Unicode private range. When Purpose is set to the Time Machine Share or External Share options, this setting does not show.
Dataset Naming Schema
Sets TrueNAS to require the naming schema used when Auto Dataset Creation is enabled. If a schema is not set, the server uses the username if it is not joined to Active Directory. If the server is joined to Active Directory, it uses the domain/username. Only shows when Purpose is set to the Private Dataset Share option.
Auto Quota
Sets the specified ZFS quota in gibibytes (GiB) on new datasets. If the value is zero, TrueNAS disables automatic quotas for the share. Only shows when Purpose is set to the Private Dataset Share option.
When Purpose is set to Final Cut Pro Storage Share, the following settings show in Other Options.
The Final Cut Pro Storage Share purpose enables Use Apple-style Character Encoding, which translates NTFS illegal characters to the Unicode private range. This ensures compatibility with Final Cut Pro.
Enabling this feature on shares with existing data might cause unexpected behavior for files that were written without Apple character encoding enabled. Test thoroughly before applying to production shares with existing content.
This share purpose requires Apple SMB2/3 Protocol Extensions to be enabled globally in the SMB service configuration.
Setting
Description
Use Apple-style Character Encoding
Automatically enabled and non-editable for Final Cut Pro Storage Share. This implements Apple-style character encoding for NTFS illegal characters, which is required for proper operation of Final Cut Pro. This setting cannot be changed for this share purpose because it is essential for Final Cut Pro compatibility.
Many online guides recommend manually configuring SMB VFS options for macOS compatibility:
vfs objects = catia fruit streams_xattr
TrueNAS does not support manual VFS module configuration. Manually setting VFS objects via auxiliary parameters or CLI overrides TrueNAS defaults and breaks Asynchronous I/O (AIO), Access Control Lists (ACLs), and Shadow Copies.
Why does TrueNAS handle VFS modules differently?
The TrueNAS SMB implementation integrates VFS modules with several advanced features. Manual VFS configuration breaks functionality including:
Asynchronous I/O (AIO): Overrides modules needed for SMB performance optimization, causing poor performance or stability issues.
Access Control Lists (ACLs): Bypasses or breaks ACL functionality, causing incorrect permission handling.
The Final Cut Pro Storage Share purpose preset automatically configures VFS modules to integrate properly with TrueNAS AIO, ACLs, and Shadow Copies. By using this preset instead of manual configuration, you get a share that works seamlessly with Final Cut Pro without risking system functionality.
Legacy Share Settings
The Edit SMB screen sets Purpose to Legacy Share after upgrading to 25.10 when shares created in a release before 25.10 have Purpose set to No Preset. The Advanced Options > Other Options settings selected in the existing share show the same options in the upgraded share.
The Add SMB screen does not include the Legacy Share option on the list of Purpose presets.
The For the best experience, we recommend choosing a modern SMB Share purpose instead of the legacy option. message shows on the Edit SMB screen to prompt users to update to an appropriate option on the dropdown list, and either accept or select the settings in the Advanced Options > Other Options listed in 25.10 or later. These are detailed in Other Options Settings above.
For example, a 25.04 SMB share with Purpose set to No Preset and Use as Home Share selected under Advanced Options > Other Options, shows the message mentioned above, sets Purpose to Legacy Share, and shows the Use as Home Share, Enable Shadow Copies, Use Apple-style Character Encoding, Enable Alternate Data Streams, and Enable SMB2/3 Durable Handles selected.
We recommend changing Purpose to Private Datasets Share. Refer to the instructions in the Setting Up SMB Private Dataset Shares tutorial for more information on setting up this replacement for Home Shares.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
VFS module configuration (catia, fruit, streams_xattr) cannot be set through auxiliary parameters. Use the appropriate share purpose preset (Final Cut Pro Storage Share, Time Machine, etc.) instead.
Legacy share unique options:
In addition to the options available in modern presets, legacy shares provide access to deprecated configuration options. These are organized into two categories:
Legacy Access Options (shown in Advanced Options > Access section) modify how clients can access the share and which hosts can connect.
Legacy Other Options (shown in Advanced Options > Other Options section) enable deprecated features for compatibility with pre-25.10 configurations.
Legacy Access Options
These settings only show on the Edit SMB screen for shares with Purpose set to Legacy Share.
Setting
Description
Enable ACL
Shows additional ACL configuration options for the share. When enabled, allows configuring custom ACL entries beyond standard share ACL settings. Only shows for Legacy Share preset.
Allow Guest Access
Allows anonymous access to the share without requiring user credentials. The privileges granted are the same as those for a guest account. Windows 10 version 1709 and Windows Server 2019 and later disable guest access by default and require additional client-side configuration. Not recommended due to security vulnerabilities. Only shows for Legacy Share preset.
Legacy Other Options
These settings only show on the Edit SMB screen after upgrading from an earlier release with an existing SMB share configured with them, unless indicated otherwise.
Do not confuse these settings with those listed in the Settings by Purpose tabbed area in the section above.
Setting
Description
Use as Home Share
Allows the share to host user home directories. Each user has a personal home directory that they use when connecting to the share that is not accessible by other users. Home Shares allow for personal, dynamic shares. You can only use one share as the home share. See Adding an SMB Home Share for more information.
Time Machine Quota
Visible when Time Machine is enabled. Sets a maximum limit on storage consumed by Time Machine backups. This applies to the entire share.
Legacy AFP Compatibility
Enables backend compatibility with metadata written by legacy netatalk implementations. This option configures Samba to properly read and present Apple Filing Protocol (AFP) metadata, such as resource forks to SMB clients. Only enable this option when migrating data that was previously shared via the AFP. Pure SMB shares and standard macOS SMB clients do not require this compatibility option. Shows only when a pre-25.10 share selected this option.
Enable Shadow Copies
Exports ZFS snapshots as Shadow Copies for Microsoft Volume Shadow Copy Service (VSS) clients.
Export Recycle Bin
Renames deleted files to a per-user subdirectory within the .recycle directory at either the root of the SMB share if the path is the same dataset as the SMB share (default is share and dataset have the same name), or at the root of the current dataset if datasets are nested. Nested datasets do not have automatic deletion based on file size. Do not rely on this function for backups or replacements of ZFS snapshots.
Use Apple-style Character Encoding
Samba uses a hashing algorithm for NTFS illegal characters by default. Enabling this option translates NTFS illegal characters to the Unicode private range. Select to convert NTFS illegal characters in the same manner as macOS SMB clients. By default, Samba uses a hashing algorithm for NTFS illegal characters. Apple extension options cannot be set if Purpose is set to the multi-protocol option.
Enable Alternate Data Streams
Allows multiple NTFS data streams. Disabling this option causes macOS to write streams to files on the file system.
Enable SMB2/3 Durable Handles
Allows using open file handles that can withstand short disconnections. Support for POSIX byte-range locks in Samba is also disabled. This option is not recommended when configuring multi-protocol or local access to files.
Enable FSRVP
Enables support for the File Server Remote VSS Protocol (FSVRP). This protocol allows remote procedure call (RPC) clients to manage snapshots for a specific SMB share. Requires setting the share path to a dataset mount point. Snapshots have the prefix fss- followed by a snapshot creation timestamp. A snapshot must have this prefix for an RPC user to delete it.
Path Suffix
Appends a suffix to the share connection path. Use to provide individualized shares on a per-user, per-computer, or per-IP address basis. Suffixes can contain a macro. See the smb.conf manual page for a list of supported macros. The connection path must be preset before a client connects.
VUID
Sets the user session identifier to a valid universally unique identifier (UUID4). Samba uses the UUID to uniquely identify the share for macOS Time Machine backups. A UUID4 string is 36-character hexadecimal in format 8-4-4-4-12 (for example, 123e4567-e89b-12d3-a456-426614174000). Generate using commands or online tools. Shows for Legacy Share with Time Machine functionality enabled.
Additional Parameters String
Shows a string of parameters associated with the share preset selected, or if no preset, enter additional smb4.conf parameters not covered by the TrueNAS API.
Create Dataset
The Create Dataset dialog adds a new dataset under the parent dataset selected in the file browser Path field on the Add SMB or Edit SMB share screens.
The Share ACL for sharename screen edits permissions at the share level for the selected share.
Settings configure new ACL entries for the selected SMB share and apply them at the entire SMB share level, but do not apply to the dataset.
It is separate from file system permissions.
To configure dataset permissions, use the Edit Filesystem ACL option.
The Share ACL for sharename screen opens after clicking on the shareEdit Share ACL icon on the Windows (SMB) Shares widget or the more_vert on the Sharing SMB details screen.
ACL Entries shows a block of settings that specify who and the permissions they are granted.
Add shows a block of these settings to enter who, the permissions level, and type.
Save stores the share ACL and immediately applies it to the share.
Setting
Description
SID
Shows the security identifier (SID) trustee value or to whom this ACL entry (ACE) applies. SID is a unique value of variable length that identifies the trustee. Shown as a Windows Security Identifier. Save and re-open Edit Share ACL to update.
Who
Sets permissions to apply to the ACL entry for the domain for the selected account (who). Options are:
User - Select to show the User field. Enter or select a user (who) from the dropdown list to apply the permissions for this ACL entry, which is shown as a username.
Group - Select to show the Group field. Enter or select a group (who) from the dropdown to apply the permissions for this ACL entry, which is shown as a group name.
everyone - Select to apply the ACL entry permissions to everyone.
Permission
Sets the level of access to a selected predefined permission combination from the dropdown list. Options are:
FULL - Grants read access, execute permission, write access, delete objects, change permissions, and take ownership (RXWDPO) permissions.
READ - Grants read access and execute permission on the object (RX). For more details, see smbacls(1).
Type
Sets how TrueNAS applies permissions to the share to the selected option on the dropdown list. Options are:
ALLOWED - Denies all permissions by default, except manually defined permissions.
DENIED - Allows all permissions by default, except manually defined permissions.
Edit Filesystem ACL Screen
The Edit Filesystem ACL option sets permissions at the dataset level. It opens the Edit ACL screen for the dataset the share uses.
See Edit ACL Screen for more information on the settings found on this screen.
Use the ACL editor screen to set file system permissions for the shared dataset.
See Permissions for more information on configuring permissions.
SMB Status Screens
The SMB Status screen shows a table of SMB session IDs from the audit logs for SMB share sessions.
It opens after clicking SMB on the list icon on the System > Services screen, or after clicking SMB Sessions on the more_vert dropdown list on the Windows (SMB) Shares widget.
The SMB Status screen shows information related to SMB sessions, for example:
Sessions ID - The current SMB sessions (default view).
Hostname - The host name associated with the session ID.
Remote machine - The remote machine information.
Username - The username associated with the session.
UID - The user ID associated with the session.
GID - The group ID for the user associated with the session.
Session Dialect - The version of the SMB protocol.
Encryption - The share encryption.
Signing - The security mechanism used, such as an authentication algorithm like AES-128-GCM, etc.
Refresh updates the information shown on the screen.
Column shows a dropdown list of options to customize the information included in the table on the screen.
Sharing or SBM on the top breadcrumb returns to the selected screen name.
NFS Shares Screens
Unix (NFS) Share Widget
If you have not added NFS shares to the system, the NFS widget shows text stating general information about the Unix (NFS) shares until a share is added.
The Unix (NFS) Share launch header shows the status of the NFS service as either STOPPED (red) or RUNNING (green).
Before adding the first share, the STOPPED status displays in the default color.
The header is a link that opens the NFS screen.
The more_vert dropdown list shows three options available to NFS shares and the NFS service in general:
Turn Off/ON Service toggles to Turn Off Service when the NFS service is enabled, and to Turn On Service when the NFS service is disabled.
Config Service opens the NFS configuration screen.
The widget shows a table listing nfs shares created in TrueNAS.
Each NFS share row on the Unix (NFS) Shares widget shows the path to the shared dataset, a description if one is entered when the share is added, an Enabled toggle that allows you to enable or disable the share.
The more_vert dropdown list for each share shows two options:
The NFS table lists all NFS shares added to the system.
The table header shows the status of the NFS service as stopped or running.
The table columns show the path to the dataset for the share, the share description if added during share creation, networks, and hosts.
The Enabled toggle allows you to enable/disable the share. When enabled, the share path is available when the NFS service is active.
If disabled, the share is disabled but not deleted from the system.
Columns shows a set of options to customize the list view.
Options include Unselect All, Path, Description, Enabled and Reset to Defaults.
The more_vert dropdown list at the right of each table row shows two options for a share:
The Add NFS and Edit NFS show the same Basic Options and Advanced Options settings.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
Basic Options
The Basic Options settings on the Add and Edit NFS screens show by default, and at the top of the screen when Advanced Options is selected.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Specifies the mount path for the share. It includes a blank field and a file browser field directly below it. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the share dataset on the local file system that TrueNAS exports over the NFS protocol. Use the arrow_right icon to the left of to expand the dataset directory tree.
Create Dataset
Creates a dataset for a share while configuring the share. Inactive until the parent dataset is selected. It opens the Create Dataset dialog, where you enter a name for a new dataset. The dataset name becomes the last part of the NFS share path. Create adds the dataset and populates Path field on the Add NFS screen.
Description
A text-entry field for a brief description or notes about how this share is used. The description entered shows in the Description column on the Unix (NFS) Shares widget on the Shares dashboard and the NFS table on the NFS screen.
Enabled
Select to enable this NFS share. Clear the checkbox to disable this NFS share without deleting the configuration.
Networks
Defines an authorized network, and any added, restricts access to all other networks. Leave empty to allow all networks. Add shows the Networks IP address and CIDR fields to enter an allowed network IP and select the mask CIDR notation. Click Add for each network address and CIDR you want to define as an authorized network.
Add hosts
Defines allowed clients (hosts) you want to allow to connect to the share. Defining authorized systems restricts access to all other systems. Leave the field empty to allow all systems access to the share. Add shows the Authorized Hosts and IP addresses field. Enter a host name or IP address to allow that system access to the NFS share. Click Add for each allowed system you want to define.
Advanced Options Settings
Advanced Options settings tune the share access permissions and define authorized networks. Advanced Options shows the Access settings listed below.
Selecting this to enable read-only prohibits writing to the share.
Maproot User
Text entry field that allows manual entry of a user name or selecting a user from the dropdown list. Typing in the field filters the dropdown list to match what is entered. Entering a user applies permissions for that user to the root user, and limits the root user to the permissions of that user.
Maproot Group
Text entry field that allows manual entry of a group name or selecting a group from the dropdown list. Typing in the field filters the dropdown list to match what is entered. Entering a group applies permissions for that group to the root user and the root user is limited to the permissions of that group.
Mapall User
Text entry field that allows manual entry of a user name or selecting a user from the dropdown list. Typing in the field filters the dropdown list to match what is entered. Entering a user applies permission for the chosen user to all clients, and the specified permissions of that user are used by all clients.
Mapall Group
Text entry field that allows manual entry of a group name or selecting a group from the dropdown list. Typing in the field filters the dropdown list to match what is entered. Entering a group applies permissions for the chosen group to all clients, and the specified permissions of that group are used by all clients.
Security
Sets the level of authentication and cryptographic protection to the option selected on the dropdown list. Options are SYS, KRB5, KRB5I, KRB5P. Selecting KRB5 allows you to use a Kerberos ticket. SYS or none should be used if no KDC is available. If a KDC is available, e.g., Active Directory, KRB5 is recommended. If desired KRB5I (integrity protection) and/or KRB5P (privacy protection) can be included with KRB5.
Security Types
Setting
Description
SYS
Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5
Uses Kerberos for authentication.
KRB5I
Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P
Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.
NFS Sessions Screen
The NFS Sessions screen shows a table of sessions with the IP address and Export status of each session listed.
You can access the NFS Sessions screen from the :
list icon on the NFS service row on the System > Services screen
more_vert on the Shares > Unix (NFS) Shares widget
This screen shows NFSv3 clients that have successfully completed an MNT request by reading the NFS rmtab file.
Clients with appropriate permissions are removed from the list on a successful UMNT request.
However, this list can become inaccurate due to the different ways that a client can disconnect from a share.
To help prevent stale entries from accumulating, the sessions list is cleared on each system boot.
Refresh updates the information displayed on the screen.
Column shows a dropdown list of options for the selected tab to customize the information included on the screen.
The breadcrumb links at the top of the screen return you to the screen you click.
Block (iSCSI) Share Target Screens
Block (iSCSI) Shares Targets Widget
If you have not added iSCSI shares to the system, the iSCSI widget shows text stating general information about the block (iSCSI) share targets until a share is added.
The Block (iSCSI) Shares Targets widget header shows the status of the iSCSI service as STOPPED (red) or RUNNING (green).
Before adding the first share, the STOPPED status displays in the default color.
The header includes the Wizard button and the more_vert dropdown list of iSCSI share and service options.
The header is a link that opens the iSCSI screen.
Wizard opens the Wizard iSCSI wizard on the Target screen. See Target Screens below.
The more_vert dropdown list shows two options available to iSCSI shares and the iSCSI service in general:
Turn Off/ON Service toggles to Turn Off Service when the iSCSI service is enabled, and to Turn On Service when the iSCSI service is disabled.
The Start iSCSI Service dialog shows after adding the first share.
It includes an Enable this service to start automatically toggle and two buttons: Start and No.
Start starts the service and changes the status on the iSCSI widget toolbar from STOPPED (in red) to RUNNING (in blue).
Cancel closes the dialog without deleting.
Delete deletes the target but does not delete the iSCSI volumes associated with the extents.
iSCSI Global Configuration Screen
The iSCSI Global Configuration screen opens when you click Edit on the iSCSI Service row of the System > Services screen, and after clicking the Global Target Configuration button at the top of all iSCSI share screens.
Enter a name using lowercase alphanumeric characters. Allowed special characters are dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section RFC3721 for more information.
ISNS Servers
Enter host names or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Press Enter to separate each entry.
Pool Available Space Threshold (%)
Generate an alert when the pool reaches this percentage of space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port
TCP port used to access the iSCSI target. The default is 3260.
iSCSI Wizard Screens
The Wizard button opens the iSCSI wizard on the Targets screen. The wizard has three screens:
The wizard steps you through creating an iSCSI target, adding the extent for the target, including setting up the storage (device or file) it uses, and setting up the portal and initiators for the target.
Alternatively, you can use the individual iSCSI screens, accessible by clicking on the iSCSI widget header, to manually configure targets, extents, portals, etc.
The Targets screen opens by default.
For more information on iSCSI screens and settings, see iSCSI Screens below.
Next advances to the next wizard screen. Back shows the previous wizard screen. Save creates the iSCSI share.
iSCSI Wizard Target Screen
The iSCSI Wizard opens and shows the Target screen.
The Target dropdown shows Create New and any other existing targets on the system.
Create New creates a target.
Selecting an existing target from the dropdown list allows you to edit it, but we recommend using the iSCSI Target screen to edit an existing target rather than using the wizard screens.
iSCSI Wizard Extent Screen
The iSCSI wizard Extent screen shows settings to name the target, set the type of extent storage (device or file), and the sharing platform for the device.
The name given to the iSCSI block target. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Extent Type
The storage device for the target. The dropdown list shows two options: Device and File. Selecting Device shows the Device dropdown list. File sows the Path to the Extent fields and the Filesize field.
Device
Shows if Extent Type is set to Device. Shows Create New or a list of iSCSI extents added to the system. Create New shows the Pool/Dataset fields and the Size field.
Pool/Dataset
Sets the mount path to the zvol for the extent. Shows two fields after selecting Create New in Device. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the extent parent dataset on the local file system that TrueNAS exports over the iSCSI protocol. Use the arrow_right icon to the left of to expand the dataset directory tree. Create Dataset activates after selecting the parent dataset.
Size
Sets the block size for the zvol. Shows after clicking Create New in Device and after adding the mount point to the zvol in Pool/Dataset. Enter a numerical value and a suffix to specify the block size for the zvol you are creating.
Path to the Extent
Sets the mount path to the file. Shows if Extent Type is set to File. Enter or browse to select the mount point for the directory and file for the extent to use. If a directory does not exist, after selecting the dataset where you want to add the directory, and then enter a / followed by the name to add the directory to the dataset or zvol.
Filesize
Sets the size of the file. Shows if the Extent Type is set to File. Enter the size for the directory. Leaving this set to 0 uses the actual file size and requires the file to exist. Otherwise, specify the file size for the new file.
Sharing Platform
Sets the platform type for the target extent connection. Shows for both Device and File options. Select the platform that matches your use case. Options are:
VMware: Extent block size 512b, TCP enabled, no Zen compat mode, SSD speed
Modern OS: Extent block size 4k, TCP enabled, no Xen compat mode, SSD speed
iSCSI Wizard Protocol Options Screen
The iSCSI wizard Protocol Options screen shows settings to add a portal and initiators.
Create New shows settings to add a new portal if one does not exist.
Sets the portal for the target and extent. Shows a dropdown list with the Create New option and lists existing portals on the system available for the target and extent. Selecting Create New shows the IP Address field and Add button. Add shows another IP Address field each time it is clicked to allow adding multiple portals.
IP Address
Sets the network address used for the portal. The dropdown list shows several options for setting up a portal:
0.0.0.0 - Listens on all IPv4 addresses.
:: - Listens on all IPv6 addresses.
TrueNAS server IP address - Uses the IP address assigned to the primary network interface for the TrueNAS server being configured.
Initiators
Initiators send commands over the TCP/IP network to the target and receive responses from the target. Leave blank to allow all (recommended) or enter a list of initiator host names (to limit access). Separate each host name by pressing Enter after entering each host name.
iSCSI Screens
The iSCSI screen provides access to manage targets, and the extents, initiators (clients), portals, and authorized access for the targets.
The iSCSI screen shows five tabs: Targets, Extents, Initiators, Portals, and Autorized Access.
The iSCSI screen opens with the Targets tab selected by default.
The Block (iSCSI) Shares Targets widget header opens the iSCSI screens.
Wizard opens the iSCSI wizard configuration screens.
iSCSI Target Screen
iSCSI targets are storage resources on an iSCSI server that are made available to iSCSI initiators (clients) over a TCP/IP network.
The target is a server-side storage object that encapuslates a block storage resource (e.g., a phyical disk, logical volume, or file) and makes it accessible to initiators via the iSCSI protocol.
A target is identified by a unique iSCSI qualified name (IQN), and is associated with portal groups for network access and initiator groups for access control.
The Target tab shows by default when opening the iSCSI screen. Use it to manage iSCSI targets.
The Targets table lists all targets added to the system. It shows the target name and alias if one is configured for it.
The first row of the table is selected by default.
Each target shows three Details for targetname widgets:
iSCSI Connections shows active connections between an authorized client and the target.
Connections show the IQN and IP address of the client connecting to the target.
iSCSI Authorized Networks - Shows a list of authorized networks configured when you create the target or using the Authorized Network settings on the Add or Edit iSCSI Target screens.
iSCSI Connections - Shows a list of the connections.
Remove Extent Association Dialog
The Remove Extent Associationlink_off icon opens the Remove extent association dialog that shows the LUN link association and two buttons: Cancel and Remove.
Removing the association activates the Associate button on the Extent widget.
The Associate button is inactive when the extent is associated with a LUN.
Clicking the button opens the Associate target dialog.
LUN ID accepts a LUN ID between 0 and 1023. TrueNaS requires at least one LUN 0.
Some initiators expect a value between 0 and 256. Leaving this field blank automatically assigns the next available ID.
Extent shows a dropdown list of targets to select and associate the extent with.
Add or Edit Target Screens
The Add Target and Edit Target screens show the same configuration settings.
The name of the target, consisting of a maximum of 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Target Alias
An alternative, optional user-friendly name for the target.
Authorized Networks
Networks authorized or allowed to communicate between initiators (client computers) and iSCSI targets (storage devices) over the IP network. Add shows the Network field.
Network
Network addresses for authorized networks. Shows after clicking Add to the right of Authorized Networks. Enter the IP address for the network and select the netmask (CIDR) from the dropdown list. Address must be a public address. Adds the network address to the iSCSI Authorized Network widget.
Target iSCSI Group Settings
Setting
Description
Add Groups
Adds a collection of network interfaces, IP addresses, and TCP ports, on a storage device that an iSCSI initiator can connect to. Groups are also known as target portal groups. Add shows a group configuration field each time it is clicked.
Portal Group ID
Select the ID from the dropdown list. Shows a group for each iSCSI share added to the system with a number assignment, for example, 1 (test2) for the test2 target/share. Portal groups are created on the Add Portal screen.
Initiator Group ID
Select the group ID from the dropdown list. Shows a group for each portal ID configured on the system, for example, *1 (ALL Initiators Allowed). Initiator groups have access to the target.
Authentication Method
Select the authentication method from the dropdown list of options. Options are:
None - Select to allow anonymous discovery. When set to None you can leave Discovery Authentication Group set to None or empty.
CHAP - Select to use the Challenge Handshake Authentication Protocol (CHAP) method. CHAP verifies the identity of an iSCSI initiator (device trying to access storage) by sending a challenge that only the authentic initiator can correctly respond to. This prevents unauthorized access to the storage target. Think of it like a password-based authentication system for iSCSI connections. When set to CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Mutual CHAP- Select to use CHAP where both the iSCSI initiator (client) and target server mutually authenticate each other using the CHAP method. Each side verifies the identity of the other before establishing a connection. This provides a higher level of security compared to one-way CHAP. When set to mutual CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Authentication Group Number
Select the group from the dropdown list. An authentication group is configured on the Add Authorized Access screen. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses.
Extents Screens
The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.
Text entry field that accepts manual or copy/paste entry of a name for the extent. An Extent where the size is not 0 cannot be an existing file within the pool or dataset.
Description
Text entry field that accepts manual or copy/paste entry of notes about this extent.
Enabled
Enables the iSCSI extent.
Extent Compatibility Settings
Setting
Description
Enable TPC
Allows an initiator to bypass normal access control and access any scannable target when selected. Third Party Copy (TPC) enables a disk target to process Extended Copy (XCOPY) operations that would otherwise be blocked, allowing data transfers to occur directly between storage devices without passing through the initiator.
Xen initiator compat mode
Select when using Xen as the iSCSI initiator.
LUN RPM
Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. Sets the RPM in iSCSI related to a LUN based upon the option selected on the dropdown list. Options are UNKNOWN, SSD, 5400, 7200, 10000 or 15000.
Read-only
Prevents the initiator from initializing this LUN when selected.
Extent Type Settings
Setting
Description
Extent Type
Provides virtual storage access to zvols or files. Select the extent (zvol) option from the dropdown list. Dropdown options:
Device - Select to specify a device (default option). Device provides virtual storage access to zvols and zvol snapshots. Shows the Device field.
File - Select to specify a path to a file. File provides virtual storage access to a single file. Shows the Path to the Extent and Filesize fields.
Device
Shows after specifying Device in Extent Type. Select the unused zvol or zvol snapshot from the dropdown list.
Path to the Extent
Consists of two fields: a blank field for the mount path to the device or file, and a file browser field directly below it that allows browsing to select the file or zvol. After selecting a parent dataset, the Create Dataset link activates. Enter a slash (/) followed by a file or zvol name to create a file in a dataset, and append the file name to the path (/filename.ext).
Filesize
Enter 0 to use the actual file size of an existing file, or specify the file size for the new file added in Path to the Extent.
Product ID
Product identification string for the extent. The default is iSCSI Disk when left empty.
Logical Block Size
Shows the default 512 size. If the initiator requires a different block size, enter the numerical value.
Disable Physical Block Size Reporting
Select if the initiator does not support physical block size values over 4K (MS SQL).
Initiators Groups Screen
The Initators Groups screen manages iSCSI initiator groups for targets.
Initiator groups are a logical grouping of iSCSI initiators (clients), identified by their iSCSI qualified name (IQN), that control access to iSCSI targets they are associated with, and define what operations clients can perform on storage for those targets.
The Initiators Groups screen shows after clicking the Initiator tab. The table lists initiator groups configured on the system.
Add opens the Add Initiator screen.
Edit opens a version of the Add Initiator screen with only two fields.
Delete opens a dialog to delete an initiator group.
Add Initiator Screen
Add opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.
Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description
Enter any notes about the initiators.
Connected Initiators
Shows the list of connected initiators on the system.
Allowed Initiators
Shows the list of allowed initiators on the system.
Refresh
Updates the screen.
Edit Initiator Screen
Edit opens the Add Initiator edit screen showing two options: Allow All Initiators and Description.
Save saves changes and closes the screen. Cancel closes the screen without saving changes.
The Portals screen manages iSCSI portal groups for the target.
A portal group is a set of network portals (IP addresses and port combinations) within an iSCSI node that collectively supports the coordination of an iSCSI session.
Each portal group is identified by a 16-bit numerical identifier (portal group tag) unique within the iSCSI node.
Portal groups allow an iSCSI initiator (client) to connect to a target through multiple network paths.
The Portals screen shows after clicking on the Portals tab on the iSCSI screen. A Portals table lists portal ID groups on the TrueNAS system.
Enter an optional description. Portals are automatically assigned a numeric group.
Add Listen
Click Add to show the IP Address field where you add the IP address and netmask (CIDR) for the portal.
IP Address
Shows several options for setting up a portal. Select from these options:
0.0.0.0 - Select to listen on all IPv4 addresses.
:: - Select to listen on all IPv6 addresses.
TrueNAS server IP address - Select to use the IPv4 address assigned to the primary network interface for the TrueNAS server being configured.
IPv6 address assigned to the system.
Authorized Access Screens
The Authorized Access screen shows a table listing groups allowed to access the target.
The Authorized Access table lists the group ID, user, and peer users. settings to create new authorized access networks or edit existing ones in the list.
The table shows No records have been added yet until you add access.
Delete opens the Delete dialog for the selected portal ID. Confirm enables the delete option.
Delete deletes authorized access for the selected user and closes the dialog.
Edit opens the Edit Authorized Access screen.
The Add and Edit screens display the same settings. Both screens have the same setting options.
Add or Edit Authorized Access Screens
The Add Target and Edit Target screens show the same configuration settings.
Enter a number. Allows configuring different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.
Discover Authentication
Select the discovery method for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets use to discover valid devices. Options are:
None - Select to allow anonymous discovery. When set to None, you can leave an iSCSI Group Authentication Method set to None or empty.
CHAP - Select to use CHAP as the authentication method. If set to CHAP enter or create a new group on the Add iSCSI Targetscreen.
Mutual Chap - Select to use the Mutual CHAP two-way authentication method. To show this option, configure the Peer User and the password.
User Settings
Setting
Description
User
User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret
Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a Password does not match error until you enter the same password in Secret (Confirm).
Secret (Confirm)
Enter the same password to confirm the user password.
Peer Settings
Setting
Description
Peer User
(Optional) Enter only when configuring mutual CHAP. Usually the same value as User. Configure the peer user name and password to see Mutual Chap in the Discover Authentication dropdown list.
Peer Secret
Enter the mutual secret password. Required if entering a Peer User. Peer user must use a different password than the password in Secret.
Peer Secret (Confirm)
Enter the same password to confirm the mutual secret password.
Fibre Channel Screens
TrueNAS Enterprise
Fibre Channel is a TrueNAS Enterprise feature. Only TrueNAS systems licensed for Fibre Channel show iSCSI Fibre Channel screens and settings found by going to Sharing > Block Shares (iSCSI).
Enterprise systems with fibre channel hardware can access fibre channel settings and screens through various iSCSI wizard and share screens.
iSCSI Wizard Screens - Fibre Channel.
The Block (iSCSI) Shares Targets widget shows iSCSI shares configured for fibre channels.
The Wizard button on the header opens the Wizard iSCSI wizard on the Target screen. See Target Screens - Fibre Channel below.
The more_vert icon button shows two options: a toggle for Turn On Service/Turn Off Service and Config Service.
Config Service opens the iSCSI Global Configuration screen.
iSCSI Target Wizard Screen - Fibre Channel
The Wizard button opens the iSCSI wizard on the Targets screen with the Fibre Channel option. The wizard has three screens:
Target
Extent
Protocol Options
To access the individual iSCSI screens click on the iSCSI widget header.
The Targets screen opens by default.
For more information on iSCSI screens and settings, see iSCSI Screens - Fibre Channel below.
Next advances to the next wizard screen. Back shows the previous wizard screen. Save creates the iSCSI share.
iSCSI Wizard Target Screen - Fibre Channel
The iSCSI Wizard opens showing the Target screen with the Fibre Channel option. Select to configure the target for fibre channel.
The Target dropdown shows the default Create New. Selecting Create New creates a share. Selecting an existing target from the dropdown list allows you to edit that target.
iSCSI Wizard Extent Screen - Fibre Channel
The iSCSI wizard Extent screen shows settings to name the target, set the type of extent storage (device or file), and the sharing platform for the device.
The name given to the iSCSI block target. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Extent Type
The storage device for the target. The dropdown list shows two options: Device and File. Selecting Device shows the Device dropdown list. File sows the Path to the Extent fields and the Filesize field.
Device
Shows if Extent Type is set to Device. Shows Create New or a list of iSCSI extents added to the system. Create New shows the Pool/Dataset fields and the Size field.
Pool/Dataset
Sets the mount path to the zvol for the extent. Shows two fields after selecting Create New in Device. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the extent parent dataset on the local file system that TrueNAS exports over the iSCSI protocol. Use the arrow_right icon to the left of to expand the dataset directory tree. Create Dataset activates after selecting the parent dataset.
Size
Sets the block size for the zvol. Shows after clicking Create New in Device and after adding the mount point to the zvol in Pool/Dataset. Enter a numerical value and a suffix to specify the block size for the zvol you are creating.
Path to the Extent
Sets the mount path to the file. Shows if Extent Type is set to File. Enter or browse to select the mount point for the directory and file for the extent to use. If a directory does not exist, after selecting the dataset where you want to add the directory, and then enter a / followed by the name to add the directory to the dataset or zvol.
Filesize
Sets the size of the file. Shows if the Extent Type is set to File. Enter the size for the directory. Leaving this set to 0 uses the actual file size and requires the file to exist. Otherwise, specify the file size for the new file.
Sharing Platform
Sets the platform type for the target extent connection. Shows for both Device and File options. Select the platform that matches your use case. Options are:
VMware: Extent block size 512b, TCP enabled, no Zen compat mode, SSD speed
Wizard Protocol Options for Fibre Channel Settings
Setting
Description
Do not connect to a fibre channel port
Select to configure the share to not connect to a fibre channel port.
Use an existing port
Select to connect the share to an existing fibre channel port.
Create a new virtual port
Select to create a new virtual port. Shows the Create a new virtual port field. Select from the options on the dropdown list.
iSCSI Share Screens - Fibre Channel
Clicking on the iSCSI widget header opens the iSCSI share screens.
Global Target Configuration opens the iSCSI service configuration screen.
Wizard opens the iSCSI wizard configuration screens.
The iSCSI shares screen opens showing Targets by default.
Six tabs show for each of the following screens: Targets, Extents, Initiators, Portals, Authorized Access, and Fibre Channel Ports.
Each shows what is configured on the system, and provides access to the add and edit configuration screens for each functional area.
iSCSI Global Configuration Screen
The iSCSI Global Configuration screen opens when you click Edit on the iSCSI Service row of the System > Services screen, and after clicking the Global Target Configuration button at the top of all iSCSI share screens.
Enter a name using lowercase alphanumeric characters. Allowed special characters are dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section RFC3721 for more information.
ISNS Servers
Enter host names or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Press Enter to separate each entry.
Pool Available Space Threshold (%)
Generate an alert when the pool reaches this percentage of space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port
TCP port used to access the iSCSI target. The default is 3260.
Targets Screens - Fibre Channel
The iSCSI Targets screen shows a list of targets configured in the system and provides access to the add and edit configuration screens. Select a target to see details about that item.
Add and Edit open the configuration screen for the selected target.
Delete opens a dialog with delete options.
Details for Target
The screen shows four widgets on the right side of the screen for the selected target: Fibre Channel Port, Fibre Channel Connections, Extents, and iSCSI Connections.
Fibre Channel Port shows the fibre channel port showing the two HA assignments configured on the system, one for the HA primary controller and the other for the standby controller. These are created when you add the targets for an HA system or migrate existing from an earlier TrueNAS (13.0 or 13.3) release to the latest release.
Fibre Channel Connections shows the schema name for the ports assigned to each controller in an HA system.
Cancel closes the dialog without deleting.
Delete deletes the target but does not delete the iSCSI volumes associated with the extents.
Remove Extent Association Dialog
The Remove Extent Associationlink_off icon opens the Remove extent association dialog that shows the LUN link association and two buttons: Cancel and Remove.
Removing the association activates the Associate button on the Extent widget.
The Associate button is inactive when the extent is associated with a LUN.
Clicking the button opens the Associate target dialog.
LUN ID accepts a LUN ID between 0 and 1023. TrueNaS requires at least one LUN 0.
Some initiators expect a value between 0 and 256. Leaving this field blank automatically assigns the next available ID.
Extent shows a dropdown list of targets to select and associate the extent with.
Add and Edit iSCSI Target Screens - Fibre Channel
The Add Target and Edit Target screens show the same configuration settings.
Enter the name for the target using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Target Alias
Enter an optional user-friendly name.
Mode
Mode shows three options for a target:
iSCSI - Select to create a standard iSCSI share target.
Fibre Channel - Select to configure an iSCSI target that includes fibre channel.
Both - Select to use both modes.
Authorized Networks
Authorized networks allow communication between initiators (client computers) and iSCSI targets (storage devices) over the IP network. Add shows the Network field.
Network
Shows after clicking Add to the right of Authorized Networks. Enter the IP address for the network and select the netmask (CIDR) from the dropdown list. Adds the network address to the authorized network list.
Do not connect to a fibre channel port
Select to create an iSCSI share and target withoug fibre channel.
Use an existing port
Select to use an existing iSCSI port(s) already configured on the system. Select when migrating an existing TrueNAS FreeBSD-based iSCSI fibre channel configuration to a later TruenNAS Debian Linux-based release. Shows a dropdown list with existing ports.
Create new virtual port
Select to create a new virtual iSCSI port for fibre channel configuration. Use when setting up a new iSCSI share target and fibre channel ports. Shows the Create a new virtual port field. Select from the options on the dropdown list.
Target iSCSI Group Settings
Setting
Description
Add Groups
Adds a collection of network interfaces, IP addresses, and TCP ports, on a storage device that an iSCSI initiator can connect to. Groups are also known as target portal groups. Add shows a group configuration field each time it is clicked.
Portal Group ID
Select the ID from the dropdown list. Shows a group for each iSCSI share added to the system with a number assignment, for example, 1 (test2) for the test2 target/share. Portal groups are created on the Add Portal screen.
Initiator Group ID
Select the group ID from the dropdown list. Shows a group for each portal ID configured on the system, for example, *1 (ALL Initiators Allowed). Initiator groups have access to the target.
Authentication Method
Select the authentication method from the dropdown list of options. Options are:
None - Select to allow anonymous discovery. When set to None you can leave Discovery Authentication Group set to None or empty.
CHAP - Select to use the Challenge Handshake Authentication Protocol (CHAP) method. CHAP verifies the identity of an iSCSI initiator (device trying to access storage) by sending a challenge that only the authentic initiator can correctly respond to. This prevents unauthorized access to the storage target. Think of it like a password-based authentication system for iSCSI connections. When set to CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Mutual CHAP- Select to use CHAP where both the iSCSI initiator (client) and target server mutually authenticate each other using the CHAP method. Each side verifies the identity of the other before establishing a connection. This provides a higher level of security compared to one-way CHAP. When set to mutual CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Authentication Group Number
Select the group from the dropdown list. An authentication group is configured on the Add Authorized Access screen. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses.
Extents Screens - Fibre Channel
The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.
Text entry field that accepts manual or copy/paste entry of a name for the extent. An Extent where the size is not 0 cannot be an existing file within the pool or dataset.
Description
Text entry field that accepts manual or copy/paste entry of notes about this extent.
Enabled
Enables the iSCSI extent.
Extent Compatibility Settings
Setting
Description
Enable TPC
Allows an initiator to bypass normal access control and access any scannable target when selected. Third Party Copy (TPC) enables a disk target to process Extended Copy (XCOPY) operations that would otherwise be blocked, allowing data transfers to occur directly between storage devices without passing through the initiator.
Xen initiator compat mode
Select when using Xen as the iSCSI initiator.
LUN RPM
Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. Sets the RPM in iSCSI related to a LUN based upon the option selected on the dropdown list. Options are UNKNOWN, SSD, 5400, 7200, 10000 or 15000.
Read-only
Prevents the initiator from initializing this LUN when selected.
Extent Type Settings
Setting
Description
Extent Type
Provides virtual storage access to zvols or files. Select the extent (zvol) option from the dropdown list. Dropdown options:
Device - Select to specify a device (default option). Device provides virtual storage access to zvols and zvol snapshots. Shows the Device field.
File - Select to specify a path to a file. File provides virtual storage access to a single file. Shows the Path to the Extent and Filesize fields.
Device
Shows after specifying Device in Extent Type. Select the unused zvol or zvol snapshot from the dropdown list.
Path to the Extent
Consists of two fields: a blank field for the mount path to the device or file, and a file browser field directly below it that allows browsing to select the file or zvol. After selecting a parent dataset, the Create Dataset link activates. Enter a slash (/) followed by a file or zvol name to create a file in a dataset, and append the file name to the path (/filename.ext).
Filesize
Enter 0 to use the actual file size of an existing file, or specify the file size for the new file added in Path to the Extent.
Product ID
Product identification string for the extent. The default is iSCSI Disk when left empty.
Logical Block Size
Shows the default 512 size. If the initiator requires a different block size, enter the numerical value.
Disable Physical Block Size Reporting
Select if the initiator does not support physical block size values over 4K (MS SQL).
Initiators Screens - Fibre Channel
The Initiators Groups screen shows a table listing initiator groups configured on the system.
Add opens the Add Initiator screen.
Edit opens a version of the Add Initiator screen with only two fields.
Delete opens a dialog to delete an initiator group.
Add Initiator Screen - Fibre Channel
Add opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.
Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description
Enter any notes about the initiators.
Connected Initiators
Shows the list of connected initiators on the system.
Allowed Initiators
Shows the list of allowed initiators on the system.
Refresh
Updates the screen.
Edit Initiator Screen - Fibre Channel
Edit opens the Add Initiator edit screen showing two options: Allow All Initiators and Description.
Save saves changes and closes the screen. Cancel closes the screen without saving changes.
Enter an optional description. Portals are automatically assigned a numeric group.
Add Listen
Click Add to show the IP Address field where you add the IP address and netmask (CIDR) for the portal.
IP Address
Shows several options for setting up a portal. Select from these options:
0.0.0.0 - Select to listen on all IPv4 addresses.
:: - Select to listen on all IPv6 addresses.
TrueNAS server IP address - Select to use the IPv4 address assigned to the primary network interface for the TrueNAS server being configured.
IPv6 address assigned to the system.
Authorized Access Screens - Fibre Channel
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Delete opens the Delete dialog for the selected portal ID. Confirm enables the delete option.
Delete deletes the selected portal and closes the dialog.
Add opens the Add Authorized Access screen.
Edit opens the Edit Authorized Access screen. Delete opens a dialog to delete the authorized access for the selected user.
The Add and Edit screens display the same settings.
Add Authorized Access Screen - Fibre Channel
The Add Target and Edit Target screens show the same configuration settings.
Enter a number. Allows configuring different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.
Discover Authentication
Select the discovery method for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets use to discover valid devices. Options are:
None - Select to allow anonymous discovery. When set to None, you can leave an iSCSI Group Authentication Method set to None or empty.
CHAP - Select to use CHAP as the authentication method. If set to CHAP enter or create a new group on the Add iSCSI Targetscreen.
Mutual Chap - Select to use the Mutual CHAP two-way authentication method. To show this option, configure the Peer User and the password.
User Settings
Setting
Description
User
User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret
Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a Password does not match error until you enter the same password in Secret (Confirm).
Secret (Confirm)
Enter the same password to confirm the user password.
Peer Settings
Setting
Description
Peer User
(Optional) Enter only when configuring mutual CHAP. Usually the same value as User. Configure the peer user name and password to see Mutual Chap in the Discover Authentication dropdown list.
Peer Secret
Enter the mutual secret password. Required if entering a Peer User. Peer user must use a different password than the password in Secret.
Peer Secret (Confirm)
Enter the same password to confirm the mutual secret password.
Fibre Channel Ports Screens
The Fibre Channel Ports screen shows a table listing fibre channels configured on the system. Virtual ports show as child elements to physical ports.
Ports are configured while setting up targets and extents. When migrating from earlier versions of TrueNAS, ports map from the earlier release to the latest TrueNAS release.
The Edit icon opens the Change Number of Virtual Ports dialog.
Change Number of Virtual Ports Dialog
The Change Number of Virtual Ports dialog shows the Virtual Ports field where you enter a numeric value to specify the number of ports for the selected fibre channel.
The NVMe-oF screens provide access to screens, widgets, settings, and dialogs to add, manage, or delete NVMe over Fabric subsystems (targets).
NVMe-oF (NVMe over Fabric) is a specification that extends NVMe storage access over network fabrics like Ethernet, Fibre Channel, and InfiniBand.
It allows hosts to access NVMe storage remotely while maintaining the high performance and low latency benefits of NVMe.
NVMe-oF Subsystems Widget
The NVMe-oF Subsystems widget shows on the Shares screen.
The header shows the status of the NVMe service as Stopped or Running, the Add button, and the more_vert dropdown menu with two options:
Turn Service On/Off toggle.
You can also turn the service on/off from the System > Services screen or set it to automatically restart after a system restart.
Config Service that opens the NVMe-oF Global Configuration screen.
You can access this configuration screen by going to System > Services or using the Global Configuration button on the NVMe-oF screen.
The table in the NVMe-oF Subsystems widget lists each subsystem added in TrueNAS.
Each row shows the subsystem name, the number of namespaces associated with the subsystem, the number of ports available through the subsystem, and the number of hosts allowed or restricted from accessing the subsystem.
The more_vert dropdown menu for each subsystem shows two options:
View - Opens the NVMe-oF screen showing the widgets for the selected subsystem.
Force forces the delete operation if the subsystem has a port or host associated with it.
Cancel closes the dialog without deleting the subsystem.
Delete removes the subsystem from the TrueNAS system.
NVMe-oF Screen
The NVMe-oF screen displays a table listing subsystems (targets) added to Truenas, and a set of Details widgets for the subsystem selected in the table. Shares on top breadcrumb returns you to the Shares screen.
Before adding an NVMe-oF subsystem, the NVMe-oF screen shows a general widget with information about subsystems and a basic comparison to iSCSI.
After adding a subsystem, the NVMe-oF screen Subsystem table lists it.
The first row of the table is selected by default and shows four Details widgets for that subsystem.
Select the row of any listed subsystem to view the detail widgets for that subsystem.
Subsystems Table
The NVMe-oF screen Subsystem table lists subsystems added to TrueNAS.
Each row shows the subsystem name, the number of namespaces associated with the subsystem, the number of ports available through the subsystem, and the number of hosts allowed or restricted from accessing the subsystem.
TrueNAS allows adding a subsystem without configuring a namespace, port, or host, which can be added later.
An report_problem alert icon shows beside the namespace name in the table and on the Ports and Namespaces widgets until these are added.
Details Widgets
Each subsystem shows a group of four Details for subsystemName widgets on the right side of the screen, subsystemName is the name given to the subsystem (i.e., test).
Subsystem widgets are:
The Details widget shows the name and NQN ID associated with the TrueNAS subsystem.
The NQN shows an edit edit icon that changes the NQN to a text-entry field.
Shows the name given to the subsystem at creation. The edit edit icon opens an edit field. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), etc.
NQN
The NVMe Qualified Name (NQN) that identifies the subsystem, includes the base NQN and name of the subsystem. The edit edit icon changes the NQN ID to a text-entry field. It accepts copy/paste of a new properly formatted NQN ID number.
Namespaces Widget
The Namespaces widget lists namespaces (zvol or file) added to the subsystem and the path to it.
Namespaces are similar to iSCSI extents.
The Add button to the right of Ports shows a dropdown list of options:
TCP - xx.xxx.x.xxx:#### if a TCP port is assigned this does not show on the list.
If a port is not assigned, any available port IP address:port number for a host shows on the list.
The Remove this port from the subsystem icon removes the port from the subsystem but does not delete the port from TrueNAS.
After removing a port, the Add button dropdown list shows the removed port and all available ports on the system in the format IP address:port.
Associated Hosts Widget
The Associated Hosts widget shows a list of hosts associated with the subsystem.
Shows All hosts are allowed if a host is not specified.
After adding a host, the widget shows the NQN identification number for the client host and the Removes this host from the subsystem icon that only removes the host from the subsystem but does not delete it from TrueNAS.
Allow all hosts that removes the host from the subsystem but does not delete it.
It toggles the Add dropdown list to show the available host NQN hidden by selecting Allow all hosts and removes Allow all hosts from the dropdown list.
NVMe-oF Global Configuration Screen
Set system-wide NVMe-oF settings.
Config Service on the NVMe-oF Subsystem widget dropdown menu, Global Configuration on the NVMe-oF screen, and the edit edit icon on the NVMe-oF row on the System > Services screen open the NVMe-oF Global Configuration screen.
Text-entry field that shows the TrueNAS NVMe NQN identification number and accepts manual or copy/paste entry of a NQN. It is used as the prefix of a subsystem NQN at creation if a subnqn is not supplied. Modifying this value does not change the subnqn of any existing subsystems.
Enable Asymmetric Namespace Access (ANA)
When enabled, allows an Enterprise-licensed High Availability (HA) storage system to inform a host about the optimal controller path to access a namespace. It is equivalent to Asymmetric Logical Unit Access (ALUA) in iSCSI. ANA helps storage arrays communicate with hosts and inform the host which controller provides the best (lowest latency) path to specific namespaces, enabling intelligent multipathing and improving performance in NVMe-oF environments.
Enable Remote Direct Memory Access (RDMA)
When enabled, allows configuring one or more ports after enabling and selecting RDMA as the transport. It requires an Enterprise license, and an RDMA-capable system and network equipment. Inactive on systems without an Enterprise license. If the system does not have the required hardware, it shows Not enabled, because this system does not support RDMA.
Generate Cross-port Referrals for Ports on This System
When enabled, allows xport_referral. If ANA is active, referrals are always generated between the peer ports on each TrueNAS controller node.
Add Subsystem Wizard
The Add Subsystem wizard opens after clicking Add on the NVMe-oF Subsystem widget or Add Subsystem on the NVMe-oF screen.
The wizard has two parts, What to Share and Access. What to Share shows by default.
What to Share
The What to Share screen allows configuring the subsystem and adding a namespace.
Text-entry field for the name of the subsystem. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#).
NQN
Shows Generate from global settings and the edit edit icon. Clicking on the edit edit icon or the text changes to a text-entry field that allows manually entering an NVMe Qualified Name (NQN) that is used to identify the subsystem. TrueNAS creates an NQN using the base NQN shown on the NVMe-oF Global Configuration screen.
The Access screen in the Add Subsystem wizard allows configuring hosts allowed to connect to the subsystem and ports the target uses to communicate with hosts.
Allow any host to connect is selected by default.
When selected, it allows connections to any host.
When not selected, it shows the Allow Hosts option and Add button that opens the Add Host screen.
The Add button to the right of Ports shows a dropdown list of options:
TCP - xx.xxx.x.xxx:#### if a TCP port is assigned this does not show on the list.
If a port is not assigned, any available port IP address:port number for a host shows on the list.
Save saves changes, creates the subsystem, closes the wizard screen, and returns to the previous screen.
Add Namespace Screens
The Add Namespace ** screens show settings and options to create namespaces.
Use to select or create the storage device (zvol or file) for the NVMe-oF share.
Add to the right of Namespaces on the What to Share option of the Add Subsystem wizard opens the Add Namespace screen.
Add on the Namespaces widget on the NVMe-oF screen opens the Add Namespaces screen.
The Zvol tab on the Add Namespace screen allows selecting an existing or creating a new zvol namespace.
There are two Path to Zvol fields: the blank field and the file browser field.
The top blank field populates with the path for the existing zvol or parent dataset selected using the file browser field below it.
Create Zvol only shows on the Zvol tab. It activates after selecting the parent dataset in the file browser field.
It opens the Add Zvol screen.
Existing File Tab
The Existing File tab on the Add Namespace allows selecting an existing file as a namespace.
There are two Path to File fields: the blank field and the file browser field.
The top blank field populates with the path for the existing file selected using the file browser field below it.
Shows two fields: a blank text-entry field and a file browser field. The top blank field populates with the path to the parent directory selected using the file browser field below it.
Filename
Text-entry field for the name of the file. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#).
File Size
Text-entry field for the storage capacity (size) you want to grant this file.
Save saves the settings, closes the screen, and returns to the previous screen.
Delete Namespace Dialog
The Delete Namespace opens after clicking the delete icon to the right of a zvol on the Namespaces widget.
Text-entry field for the name given to the zvol. Best practice is to enter a short name that does not exceed 63 characters to prevent issues with accessing the zvol. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#), etc.
Size
Text-entry field to specify the size and value allocated to the file. For example, enter 10 GiB.
Force size
When enabled, the system restricts creating a zvol that brings the pool to over 80% capacity. Set to force creation of the zvol (not recommended).
Sparse
Enables using thin provisioning where disk space for this volume is allocated on demand as new writes are received. Use caution when enabling this feature, as writes can fail when the pool is low on space.
Sync
Sets the data write synchronization. Options are:
Inherit takes the sync settings from the parent dataset.
Standard uses the settings requested by the client software.
Always waits for data writes to complete.
Disabled never waits for writes to complete.
Compression
Encodes information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of saved space. LZ4 is generally recommended because it maximizes performance and dynamically identifies the best files to compress. GZIP options range from 1 for least compression and best performance, through 9 for maximum compression with greatest performance impact. ZLE is a fast algorithm that only eliminates runs of zeroes.
ZFS Deduplication
Transparently reuses a single copy of duplicated data to save space. Deduplication can improve storage capacity, but it is RAM-intensive. Compressing data is generally recommended before using deduplication. Deduplicating data is a one-way process. Deduplicated data cannot be undeduplicated!
Read-only
When enabled, it prevents modifying the zvol.
Block size
Shows a dropdown list of options to set the zvol default block size. Block size is automatically chosen based on the number of disks in the pool for a general use case.
Snapdev
Dropdown list of options to control whether the volume snapshot devices under /dev/zvol/⟨pool⟩ are hidden or visible. The default value is Inherit (hidden).
Encryption Settings
Encryption settings secure data within this zvol. These settings establish the level and type of encryption applied.
The default setting is Inherit (non-encrypted) when the root or parent dataset for the new storage is unencrypted.
If encrypted, this shows Inherit (encrypted).
Clearing the checkbox shows the Encryption Type setting with two options: Key and Passphrase. Each option shows different setting options.
The Key settings accept a system-generated or user-entered encryption key.
Creating a new key file invalidates the previously downloaded key file associated with this dataset.
Shows with Generate Key selected by default. This automatically generates an encryption key for the zvol. Clearing the checkmark shows the additional key encryption settings.
Randomly generates an encryption key to secure the zvol. Disable to manually enter an encryption key.
WARNING: The encryption key is the only means to decrypt the information stored in this zvol. Store the encryption key in a secure location.
Key
Text-entry field that accepts manually entering or copy/pasting an alpha-numeric string to use as the encryption key for this zvol.
Algorithm
Dropdown list of mathematical instruction sets that determine how plain text is converted into cipher text. See [Advanced Encryption Standard (AES)(https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)] for more details.
Passphrase Type Settings
The Passphrase settings set encryption to a passphrase of your choice to encrypt the data in the zvol.
Text-entry field that accepts manual or copy/paste of a user-defined string that decrypts the zvol. Use instead of an encryption key.
WARNING: The passphrase is the only means to decrypt the information stored in this dataset. Be sure to create a memorable passphrase or physically secure the passphrase.
Confirm Passphrase
Confirms the user-defined string entered in Passphrase. Entries must match.
pbkdf2iters
The pencil icon shows a dropdown list of options to set the number of password-based key derivation function 2 (PBKDF2) iterations to reduce vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Algorithm
The pencil icon shows dropdown list of options to set the mathematical instruction that determine how plain text is converted into cipher text. See Advanced Encryption Standard (AES) for more details.
Add and Edit Host Screens
The Add Host screen specifies a host and adds it to a subsystem when the Allow any host to connect option on the Add Subsystem > Access screen is not enabled.
The Edit Host screen shows the fields associated with the subsystem and allows you to change the host settings.
Text-entry field that accepts manual or copy/paste of the unique identifier obtained from the host you allow to access the subsystem. Format of the NQN is nqn.2019-05.com.example:storage-array-01.
Require Host Authentication
When selected/enabled, shows additional authentication settings: Hash, Key For Host To Present, Key For TrueNAs To Present (Optional), generate keys for each key option, and Also use Diffie-Hellman key exchange for additional security.
Hash
Shows the current hash option SHA-256 and the edit edit icon that shows a dropdown list of hash options. Options are SHA-256, SHA0384, and SHA-512.
Key For Host To Present
The DH-CHAP key, obtained from the host, to authenticate access to the subsystem. Accepts manual or copy/paste entry of a hash. Use Generate Key directly under the field to have TrueNAS create a key to copy/paste into the host to use as the authentication key for that host.
Generate Key
Populates the Key For Host To Present field with a TrueNAS system-generated DH-CHAP key for the host.
Key For TrueNAs To Present (Optional)
The secret key the TrueNAS system presents to the host that further validates the connection between the host and TrueNAS when the host connects to the subsystem (bi-directional authentication). Accepts copy/paste of a key or use the Generate Key directly below this field to populate with a system-generated key. Provide this key to the host connecting with TrueNAS to authenticate the TrueNAS system in the connection authorization.
Generate Key
Populates the Key For TrueNAS To Present field with a system-generated bi-directional authentication key.
Also use Diffie-Hellman key exchange for additional security
Enables further security through a Diffie–Hellman key exchange. This affords greater authentication security than using only the CHAP keys for authentication.
Hosts Window
The Hosts window shows a table listing the host NQN, if it requires authentication, and the number of subsystems that use it.
The host row shows the edit edit icon and the delete delete icons.
Cancel closes the dialog without removing the host from the subsystem.
Delete Anyway deletes the host from the subsystem(s) specified in the dialog.
Add Port Screen
The Add Port Screen shows settings to add or select a port to associate with the subsystem. Ports are formatted as IP address:port.
4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.
Sets the transport type. Options are: TCP, RDMA, or Fibre Channel. The RDMA and Fibre Channel options require Enterprise licenses and systems with compatible/supporting hardware.
Port
Sets the current port assignment. 4420 is the default and recommended port number. We recommend using this port rather than entering a custom port number.
Address
Sets an existing static IP address for the port assignment.
Edit Port Screen
The Edit Port screen shows current port settings for the selected subsystem.
The edit edit icon on the port row listed on the Ports dialog opens the Edit Port screen.
Dropdown list of options for the transport type. Options are TCP, RDMA, or Fibre Channel. The RDMA and Fibre Channel options require Enterprise licenses and systems with compatible/supporting hardware.
Port
Text-entry field that shows the current port assignment and allows manual or copy/past entry of a new port number.
Address
Dropdown list that shows the current static IP address assignment and any other static IP on the system the subsystem can use.
Ports Window
The Ports window shows a table showing the port name, type, IP address, communication port number, and the number of subsystems that use it.
The port row shows the edit edit icon and the delete delete icon.
The Delete Port confirmation dialog removes the port from the selected subsystem but does not delete it from TrueNAS. A deleted port shows on the Add dropdown list on the Ports widget for a selected subsystem on the NVMe-oF screen.
The dialog shows the name of the subsystem and the assigned IP address:port assignment.
Cancel closes the dialog without removing the port from the subsystem.
Delete Anyway removes the port assignment from the subsystem specified in the dialog.
Data Protection
The Data Protection screen allows users to set up multiple redundant tasks that protect and/or backup data in case of drive failure.
Scrub tasks can provide early disk failure alerts by identifying data integrity problems and detecting various indicators of drive reliability.
TrueCloud Backup, Cloud sync, periodic snapshot, rsync, and replication tasks provide backup storage for data and allow users to revert the system to a previous configuration or point in time.
Rsync Tasks Screens: Provides information on the Rsync Tasks screens and settings.
Periodic Snapshot Tasks Screens: Provides information on the Data Protection and Periodic Snapshot Task screens and settings.
VMWare Snapshots Screen: Provides information on the VMWare-Snapshot Add screen settings and functions.
Replication Task Screens: Provides information on the Replication screens, wizard, and settings used to add or edit replication tasks.
TrueCloud Backup Tasks Screens
The TrueCloud Backup Tasks widget on the Data Protection screen shows configured TrueCloud tasks, and provides access to configuration screens to add or schedule recurring transfers between TrueNAS and a cloud storage provider account like Storj iX.
TrueCloud backup tasks effectively back up data to remote locations, restore snapshots, and perform cloud-storage migration.
TrueCloud Backup Tasks Widget
The TrueCloud Backup Tasks widget shows a list of tasks configured on the system.
play_arrowRun Now starts and runs the backup task outside of the scheduled time.
visibility View Details opens the TrueCloud Backup Tasks screen that lists backup tasks configured on the system. Click on a task to see details for the selected task.
deleteDelete opens a confirmation dialog before the system deletes the task.
State shows the status of the previous or current task. Possible status indications are:
SUCCESS for completed tasks.
FAILED if the task fails to complete.
RUNNING for tasks in progress.
N/A for scheduled tasks before they run.
TrueCloud Logs Dialog
The state oval opens the Logs dialog for that task.
Download Logs saves a copy of the current task logs.
The TrueCloud Backup Tasks screen lists all tasks configured on the system.
The TrueCloud Backup Tasks open_in_new on the widget title or visibility View Details on a task opens the TrueCloud Backup Tasks screen.
play_arrowRun Now starts and runs the backup task outside of the scheduled time.
deleteDelete opens a confirmation dialog before the system deletes the task.
Select any task to see details for the configured task, such as the schedule, path to the dataset or directories, snapshots, and other task options.
Snapshots Widget
The Snapshots widget lists existing TrueCloud snapshots for the selected backup task.
It contains options to restore from or delete an existing snapshot.
deleteDelete opens a confirmation dialog before the system deletes the snapshot.
Restore from Snapshot Screen
The Restore from Snapshot screen shows the date and time of the selected snapshot.
It shows Remote and Local configuration options to restore the TrueCloud snapshot.
Remote Settings specify all data in the backup or exclude some data from a restoration.
Additional settings show depending on the Include/Exclude selection.
Settings
Description
Include Everything
Select to restore all backed-up data from the remote snapshot to the selected local path.
Include from subfolder
Select to restore data from a subfolder within the backed-up data.
Subfolder
Shows when Include from subfolder is selected. Enter or browse to the subfolder within the snapshot with the data to restore.
Included Paths
Shows when Include from subfolder is selected. Select files and directories to include from the backup. Leave empty to include everything in the selected subfolder.
Select paths to exclude
Select to exclude only certain paths from the data to restore.
Excluded Paths
Shows when Select paths to exclude is selected. Enter or select files and directories to exclude from the backup. Select as many checkboxes as desired to select multiple paths or separate multiple entries with a comma.
Exclude by pattern
Select to exclude files and directories matching defined glob patterns.
Pattern
Shows when Exclude by pattern is selected.
Local Settings
Use Local settings to select the target mount point on the current (local) system where files are restored.
Be cautious when setting the restore target to avoid overwriting existing files.
Target settings allow entering the path to the dataset or directory or browse to the location to populate the field with the local directory where files are restored.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
create_new_folder Create Dataset opens a dialog to name and create a new dataset at the selected target.
Save starts restoring data from the snapshot.
Add and Edit TrueCloud Backup Task Screen
The Add TrueCloud Backup Task and Edit TrueCloud Backup Task screens contain options to configure a new backup task.
The edit screen opens populated with the existing task settings.
Each screen shows the Local, Remote, Task Settings, and Control settings.
The Advanced and Advanced Remote Options are for advanced users.
Local settings set the dataset or directory used in the task. Selecting the dataset populates the Source Path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Enter or browse to select the dataset or directory with the data to send to the cloud backup provider set in the task. Click the arrow_right arrow to the left of the /mnt folder to expand and show datasets and directories within that folder. This is the dataset or directory location with the data the TrueCloud backup task sends to the cloud storage provider. Click the arrow_right arrow to the left of the /mnt folder again to collapse the directory tree.
Remote Settings
The Remote settings specify the TrueCloud credential and destination storage locations.
Settings
Description
Credential
Select an existing Storj iX credential from the dropdown list. TrueNAS automatically validates the selected credential. Select Add New to open the Cloud Credentials screen. This is the same configuration screen that opens when you click Add on the Credentials > Backup Credentials screen.
Bucket
Displays after selecting the Storj credential. Select a pre-configured Storj bucket. Only TrueNAS-compatible Storj buckets are selectable. Select Add New to create a new Storj bucket from the TrueNAS UI.
New Bucket Name
Displays when Add New is selected in the Bucket field. Enter a name for the new bucket. Only lowercase letters, numbers, and hyphens are allowed.
Folder
Enter or browse to select the dataset or directory to receive the backed-up data. Click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task. Enter /name, where name is a folder that does not exist, to create a new folder in the bucket.
Task Settings
Task Settings specify the task name, snapshot retention policy, and password for the backup repository.
Settings
Description
Name
Enter a name for the TrueCloud backup task.
Keep Last
Enter a number for the past snapshot copies to retain before removing older snapshots.
Password
Enter a password for the backup repository. Record this password in a secure location. Required to recreate the task using the same bucket/folder, such as in a new TrueNAS install or system, or to restore data from the existing snapshots in another TrueNAS system.
Control Settings
Control settings establish a schedule for when to run the backup task.
Settings
Description
Schedule
Select a schedule preset or choose Custom to open the advanced scheduler.
Enabled
Select to enable the TrueCloud task. Leave clear to disable the task without deleting it and keep the configuration available without allowing the specified schedule to run the task. The toggle in the Enable column on the TrueCloud Backup Tasks widget enables/disables the task.
Advanced Scheduler
Choosing a Presets option populates the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
Specific time ranges are set by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, while entering * in Days means the task runs every day of the month, */2 means the task runs every other day.
Combining all the above examples together creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
There is an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days.
This is in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour (every quarter hour). */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
Days can be specified as days of month, or days of week.
With these options, you can create flexible schedules similar to these examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday, Wednesday and Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Advanced Options Settings
Advanced Options settings are intended for advanced users.
Select to set the TrueCloud Backup Task to use a snapshot of the dataset before a push transfer.
Use Absolute Paths
Select to ensure that restic backups contain absolute paths. If you do not select this option, the restic backup contains relative paths.
Pre-Script
(For advanced users only) Enter a script to execute before running the task. See the Managing TrueCloud Backup Tasks tutorial for more information. See Script Environment Variables below for a list of variables for scripts.
Post-Script
(For advanced users only) Enter a script to execute after running the task. See the Managing TrueCloud Backup Tasks tutorial for more information. See Script Environment Variables below for a list of variables for scripts.
Exclude
Enter a list of files and directories to exclude from the backup. Separate entries by pressing Enter. See restic exclude patterns for more information about the --exclude option and proper syntax.
Script Environment Variables
The following environment variables can be used in pre and post-scripts.
CLOUD_BACKUP_ID
CLOUD_BACKUP_DESCRITPION
CLOUD_BACKUP_PASSWORD
CLOUD_BACKUP_KEEP_LAST
CLOUD_BACKUP_TRANSFER_SETTING
CLOUD_BACKUP_ACCESS_KEY_ID
CLOUD_BACKUP_FOLDER
CLOUD_BACKUP_BUCKET
CLOUD_BACKUP_FAST_LIST (always zero (0) for false, planned removal in Fangtooth)
Advanced Remote Options
Advanced Remote Options settings are intended for advanced users.
Settings
Description
Transfer Settings
Select the option from the dropdown list to set the number of simultaneous file transfers to allow. Options:
Default - Select to use the Restic PACK_SIZE of 16 Mib and READ_CONCURRENCY to two files.
Perfromance - Select to set the Restic PACK_SIZE to 29 MiB and READ_CONCURRENCY to two files.
Fast Storage - Select to set the Restic PACK_SIZE to 58 MiB and READ_CONCURRENCY to 100 files.
Cloud Sync Tasks Screens
The Cloud Sync Tasks widget on the Data Protection screen shows configured cloud sync tasks, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS and a cloud storage provider.
Cloud sync tasks are an effective data backup method that sends data to a remote location, or when performing cloud-storage-migration through a provider.
These providers are supported for Cloud Sync tasks in TrueNAS:
Each task includes a vertical ellipses more_vert icon that opens a dropdown menu with five options for various functions:
The editEdit icon opens the Edit Cloud Sync Task screen populated with with the settings for that task.
The play_circle_filledRun Now icon starts the cloud sync, running it outside of the scheduled time.
The loopDry Run icon performs the same function as the Dry Run button on the add and edit configuration screens.
It tests and validates the configured settings.
During a dry run, you can close the window and monitor the task using the Jobs option on the top toolbar.
The restoreRestore icon creates a new cloud sync task from an existing task.
The new task has the same settings but reverses the data transfer.
The deleteDelete icon opens a confirmation dialog before the system deletes the task.
State shows the status of the next cloud sync task:
SUCCESS for completed tasks.
FAILED if the task fails to complete the sync.
PENDING for tasks not run yet.
When clicked, the state oval opens the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Expand any task to see details on the configured task, such as the cloud sync provider, direction, transfer mode, path to the dataset or directories, and other options for that task.
Buttons for these task options perform the same functions as the icons on the widget:
Run Now starts the task outside of the scheduled period.
Dry Run performs a test of the configuration.
This is the same function as the Dry Run button on the Edit Cloud Sync Task screen and the Advanced Options for the Cloudsync Task Wizard.
Restore opens the Restore Cloud Sync Task window where you can create a new cloud sync task from an existing task with the same options, but the new task reverses the transfer from PUSH to PULL and vice-versa.
Delete opens a dialog where you confirm the action before the system deletes the task.
Cloudsync Task Wizard
The Cloud Sync Task wizard screens simplify the task creation process.
The wizard has two screens, Provider and What and When.
Provider Wizard Screen
The Provider wizard screen allows you to select the cloud sync provider with the Credentials dropdown.
Select the provider from the dropdown list to show the additional credential settings the selected provider requires to establish a connection.
Add New opens the Cloud Credentials screen. The same configuration screen opens when you click Add on the Credentials > Backup Credentials screen.
Advanced Options opens a screen with the same settings as the Edit Cloud Sync Task screen.
Verify Credentials tests the settings before you advance to the settings on the What and When wizard screen.
What and When Wizard Screen
The What and When screen sets the direction (push or pull), transfer mode (move, copy, or sync), select the datasets or directories source and destination, and the schedule for the transfer.
Bucket shows for providers that use buckets to hold transferred files, folders, etc.
Advanced Options shows at the bottom of this screen.
Advanced Options and Edit Cloud Sync Task Screens
Advanced Options accessed from the Cloudsync Task Wizard and Edit Cloud Sync Task show the same settings, and settings are grouped into Transfer, Remote, Control, and Advanced Options.
Transfer settings change the cloud sync task direction (PUSH or PULL), set the data transfer method (COPY, MOVE, or SYNC), and set the dataset or directory to use in the task. Selecting the dataset or file populates the Directory/Files field.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
A human-readable summary about the task. This is for administrator reference only.
Direction
Defines whether TrueNAS sends or receives data. PUSH sends data to cloud storage. PULL receives data from cloud storage and is the default setting.
Transfer Mode
Defines how files are handled during the task. There are three options:
COPY - Select to duplicate each source file into the destination. If files with the same names are present on the destination, they are overwritten.
MOVE - Select to transfer files from the source to the destination and delete source files. Copies files from the source to the destination and then deletes them from the source. Files with the same names on the destination are overwritten.
SYNC - Select to change files on the destination to match those on the source. If a file does not exist on the source, it is also deleted from the destination.
Directory/Files
Enter or browse to select the source or receiving dataset or folder. Click the arrow_right arrow to the left of /mnt folder to expand and show datasets and directories within that folder. After selecting the dataset or directory location (source) to send to the cloud for push syncs, or as the destination to write to for pull syncs. Be cautious with pull destinations to avoid overwriting existing files. Click the arrow_right arrow to the left of /mnt folder again to collapse the directory tree. Note: Clear the checkmark to the left of /mnt. Not clearing this checkmark can result in an All selected directories must be at the same level error message.
Remote Settings
The Remote settings specify the cloud sync provider and destination storage locations.
The option selected in Credential changes settings displayed in the Remote settings area.
The Manage Credentials link opens the Backup Credentials screen where you can add a new provider credential.
Settings
Description
Credential
Defines which preconfigured cloud storage account participates in this task. A Bucket setting displays after selecting a credential that uses S3, like Amazon S3. TrueNAS automatically validates the selected credential.
Bucket
Sets the pre-defined bucket to use. For Storj-iX credentials, select Add New to open the Add Bucket screen and create a new bucket on your Storj account from the TrueNAS UI.
Folder
Enter or browse to select the dataset. Click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task.
Add Bucket Screen
The Add Bucket screen opens when Add New is selected from the Bucket dropdown in Remote Settings.
It is only available for Storj-iX provider credentials.
Click Save on the Add bucket screen to create the remote bucket on Storj and then return to the Cloud Sync Task Wizard.
Control Settings
Control settings establish a schedule for when the cloud sync task occurs.
Settings
Description
Schedule
Sets a schedule preset or choose Custom to open the advanced scheduler.
Enabled
Enables this cloud sync task. Leave clear to disable the task without deleting it and keep the configuration available without allowing the specified schedule to run the task. You can use the toggle in the Enable column on the Cloud Sync Tasks widget to enable or disable the task.
Advanced Scheduler
Choosing a Presets option populates the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
Specific time ranges are set by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, while entering * in Days means the task runs every day of the month, */2 means the task runs every other day.
Combining all the above examples together creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
There is an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days.
This is in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour (every quarter hour). */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
Days can be specified as days of month, or days of week.
With these options, you can create flexible schedules similar to these examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday, Wednesday and Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Advanced Options Settings
Advanced Options settings are for advanced users.
Selecting Push in Direction adds the Use Snapshot option.
Create empty source dirs on destination after sync
Creates an empty source directory in the cloud-storage provider folder when pushing data to the cloud provider location, or in TrueNAS if pulling data from the cloud storage provider.
Follow Symlinks
Sets symbolic links (symlinks) to follow when enabled and copies the items to which they link.
Pre-Script
For advanced users. Sets a script to execute before running sync to what is entered. See the Cloud Sync tutorial for more information.
Post-Script
For advanced user. Sets a script to execute after running sync to what is entered. See the Cloud Sync tutorial for more information.
Exclude
Sets up a list of files and directories to exclude from sync. Enter one or separate additional entries by pressing Enter. Examples of proper syntax to exclude files/directories are:
photos</code> excludes a file named photos
/photos> excludes a file named photos from root directory (but not subdirectories)
photos/ excludes a directory named *photos
/photos/ excludes a directory named photos from root directory (but not subdirectories).
See rclone filtering for more details about the --exclude option.
Advanced Remote Options
The Advanced Remote Options settings are for advanced users to configure remote encryption (if selected), transfer bandwidth speed, and bandwidth limit.
The Edit Cloud Sync Task screen Advanced Remote Options screen has an additional setting not found on the Add Cloud Sync Task screen.
Select to use rclone crypt encryption during pull and push transfers. Selecting PUSH in Direction encrypts files before transfer and stores the encrypted files on the remote system. Files are encrypted using the encryption password and encryption salt values. Selecting PULL decrypts files stored on the remote system before the transfer. Transferring the encrypted files requires entering the same encryption password and encryption salt used to encrypt the files. Additional details about the encryption algorithm and key derivation are available in the rclone crypt File formats documentation. Selecting Remote Encryption shows the Filename Encryption, Encryption Password, and Encryption Salt settings.
Filename Encryption
Not recommended (see below). Shows after selecting Remote Encryption. When selected, transfers encrypt and decrypt file names with the rclone Standard file name encryption mode. The original directory structure of the files is preserved. When enabled, file names are encrypted, file names are limited to 143 characters, directory structure is visible, and files with identical names have identical uploaded names. File names can use sub-paths, single-copy files, and shortcuts to shorten the directory recursion. When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, and you can use sub-paths, and copy single files.
Encryption Password
Shows after selecting Remote Encryption. Enter the password to encrypt and decrypt remote data. Warning: Always securely back up this password! Losing the encryption password results in data loss.
Encryption Salt
Shows after selecting Remote Encryption. Enter a long string of random characters to use as salt for the encryption password. Warning: Always securely back up the encryption salt value! Losing the salt value results in data loss.
Transfers
Sets the option for the number of simultaneous file transfers based on the available bandwidth and destination system performance to the option selected on the dropdown list. Options: Low Bandwidth(4), Medium Bandwidth (8), High Bandwidth(16), and Custom. See rclone –transfers.
Bandwidth limit
Sets the bandwidth limit. Enter a single bandwidth limit or bandwidth limit schedule in rclone format. For example: 08:00,512 12:00,10MB 13:00,512 18:00,30MB 23:00,off. Separate entries by pressing Enter. You can specify units with the beginning letter b, k (default), M, or G. See rclone –bwlimit.
We do not recommend enabling Filename Encryption for any cloud sync tasks that did not previously have it enabled.
Users with existing cloud sync tasks that have this setting enabled must leave it enabled on those tasks to be able to restore those existing backups.
Do not enable file name encryption on new cloud sync tasks!
Rsync Tasks Screens
The Rsync Task widget on the Data Protection screen shows configured rsync tasks configured on the TrueNAS system, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS and an rsync backup server.
Rsync tasks are an effective method to back up data to a remote location.
Rsync Task Widget
The Rsync Tasks widget shows a list of tasks configured on the system.
Each task includes a vertical ellipses more_vert icon that opens a dropdown menu with three options for various functions:
The editEdit icon opens the Edit Rsync Task screen populated with with the settings for that task.
The play_arrowRun Now icon starts the rsync, running it outside of the scheduled time.
The deleteDelete icon opens a confirmation dialog before the system deletes the task.
State displays the status of the next cloud sync task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Each task shows details about the configured task and the same icon buttons found on the Rsync Task widget to run the task outside of the scheduled time, edit, or delete the task.
Add and Edit Rsync Task Screens
The Add Rsync Task and Edit Rsync Task screens display the same settings.
Source and Remote Options
Source settings specify the location of the stored data to sync with a remote server, set the user that performs the task, and the direction of the task (send or receive data).
The Remote settings specify the mode for the task and remote host connection information.
Settings change based on the Rsync Mode selected (Module or SSH).
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
(Required) Enter or browse to the dataset or directory to sync with a remote server. Use the arrow_right to the left of /mnt folder to expand the folder tree, then click on the name to select and populate the Path field. Linux file path limits apply. Other operating systems can have different limits, which might affect how to use them as sources or destinations.
User
(Required) Select the user to run the rsync task. Select a user who has permissions to write to the specified directory on the remote host. If setting Rsync Mode to SSH, the user must have an SSH private key in their home directory if Connect using is set to SSH private key stored in user’s home directory.
Direction
(Required) Select the direction of the flow of data to the remote host. Options are:
Push - During a push, the dataset copies data to the remote module.
Pull - During a pull, the dataset stores data copied from the remote system.
Description
(Optional) Enter a description of the rsync task.
Rsync Mode
Select the mode from the dropdown list. Options are:
Module - Select to use a custom-defined remote module from the rsync server.
SSH - Select to use an SSH configuration for the rsync task. The remote system must have SSH enabled. The host system needs an established SSH connection to the remote for the rsync task. SSH displays more settings.
Remote Host
(Required) Enter the IP address or host name and domain of the remote system. Use the format username@remote_host if the user name differs on the remote host.
Remote Module Name
(Required) If Rsync Mode is set to Module, specify the name of the module on the remote rsync server. Define at least one module per rsyncd.conf(5) on the remote rsync server. Enter the Module Name exactly as it appears on the remote system.
Connect using
(Required) If Rsync Mode is set to SSH, select the connection method from the dropdown list. Options are:
SSH private key stored in user’s home directory - If selected, the user entered in User must have an SSH private key added and stored in the home directory for the user. Create the SSH connection and keypair, download the keys, then add the private key to the user in the UI and to the home directory either from the Shell using Linux CLI commands or while in an SSH session with the system.
SSH connection from the keychain - Requires creating an SSH connection and keypair before setting up the rsync task.
Remote SSH Port
(Required) If Rsync Mode is set to SSH, enter the SSH port number of the remote system. By default, 22 is reserved in TrueNAS.
Remote Path
Enter an existing path on the remote host. Maximum path length is 255 characters.
Validate Remote Path
Shows when Rsync Mode is set to SSH. Set to test the remote server connection and verify that the defined Remote Path exists.
Schedule and More Options
Schedule defines when the remote sync task occurs.
The More Options specify other settings related to when and how the rsync occurs.
Select a schedule preset or choose Custom to open the advanced scheduler.
Recursive
Select to include all subdirectories of the specified directory. When cleared, only the specified directory is included.
Enabled
Select to enable this rsync task. Clear to disable this rsync task without deleting it.
Advanced Scheduler
Choosing a Presets option populates the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
Specific time ranges are set by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, while entering * in Days means the task runs every day of the month, */2 means the task runs every other day.
Combining all the above examples together creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
There is an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days.
This is in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour (every quarter hour). */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
Days can be specified as days of month, or days of week.
With these options, you can create flexible schedules similar to these examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday, Wednesday and Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
More Options Settings
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Setting
Description
Times
Select to preserve modification times of files.
Compress
Select to reduce the size of data to transmit. Recommended for slow connections.
Archive
Select to preserve symlinks, permissions, modification times, group, and special files. When selected, rsync runs recursively. When run as root, owner, device files, and special files are also preserved. Equal to passing the flags -rlptgoD to rsync.
Delete
Select to delete files in the destination directory that do not exist in the source directory.
Quiet
Select to suppress informational messages from the remote server.
Preserve Permissions
Select to preserve original file permissions. Useful when the user is set to root.
Preserve Extended Attributes
Select to preserve extended attributes, but this must be supported by both systems.
Delay Updates
Select to save a temporary file from each updated file to a holding directory until the end of the transfer. All transferred files are renamed once the transfer is complete.
Auxiliary Parameters
Enter additional rsync(1) options to include. Separate entries by pressing Enter. Note: You must escape the * character with a backslash (\*.txt) or inside single quotes ('*.txt').
Periodic Snapshot Tasks Screens
The Data Protection screen Periodic Snapshot Task widget displays periodic snapshot tasks created on the system.
A periodic snapshot task allows scheduling the creation of read only versions of pools and datasets at a given point in time.
Periodic snapshot tasks display the machine time, browser time, or both depending on individual user timezone settings. Users can update timezone settings by utilizing the General Settings screen.
Periodic Snapshot Task Widget
The Periodic Snapshot Task widget displays a list of tasks configured on the system.
If a periodic snapshot task is not yet configured No Periodic Snapshot Task configured displays in the widget.
The vertical ellipses more_vert icon at the right of the task on the Periodic Task Widget opens a dropdown menu with thow task options: Edit and Delete.
The deleteDelete opens a delete dialog. Confirm activates the Delete. Delete deletes the saved periodic snapshot task.
Edit opens the Edit Periodic Snapshot Task screen.
State show the status of the next cloud sync task, and when clicked, opens a Logs window for that task.
Logs Window
Download Logs saves a copy of the current task logs.
Periodic Snapshot Task Screen
Periodic snapshot tasks show on both the Periodic Snapshot Task widget on the Data Protection screen and the Periodic Snapshot Tasks screen.
The Columns dropdown list shows options to customize the list view.
Options are Select All, Recursive, Naming Schema, When, Frequency, Next Run, Keep snapshot for, VMWare Sync, Enabled, State, and Reset to Defaults.
State shows the current state of the task.
The expand_more expand icon at the right of the task opens the details for the selected task.
Delete opens the delete dialog that removes the task from the system.
Add and Edit Periodic Snapshot Screens
The Add Periodic Snapshot Task and Edit Periodic Snapshot Task show the same settings.
Dataset Options
Dataset settings show on both the add and edit configuration screens.
Dataset Settings
Setting
Description
Dataset
Sets the pool, dataset, or zvol you want to take a snapshot of.
Exclude
Excludes specific child datasets from the snapshot. Use with recursive snapshots. List paths to any child datasets to exclude. Example: pool1/dataset1/child1. A recursive snapshot of pool1/dataset1 includes all child datasets except child1. Separate entries by pressing Enter.
Recursive
Sets the task to take separate snapshots of the dataset and each of its child datasets. Leave checkbox clear to take a single snapshot only of the specified dataset without child datasets.
Schedule Settings
Schedule settings show on both the add and edit configuration screens.
Setting
Description
Snapshot Lifetime
Sets the length of time to retain a snapshot on this system. Enter a numeric value and a single lowercase letter for units. Examples: 3h is three hours, 1m is one month, and 1y is one year. Does not accept minute values. After the time expires, the snapshot is removed during the next snapshot scheduled execution finds the snapshot lifetime is expired. Snapshots replicated to other systems are not affected.
Naming Schema
Snapshot name format string. The default is auto-%Y-%m-%d_%H-%M. Must include the strings %Y, %m, %d, %H, and %M, which are replaced with the four-digit year, month, day of month, hour, and minute as defined in strftime(3). For example, snapshots of pool1 with a Naming Schema of customsnap-%Y%m%d.%H%M have names like pool1@customsnap-20190315.0527.
Schedule
Sets the schedule to a preset selected from the dropdown list. Select Custom to open the advanced scheduler.
Begin
Sets the start time for a snapshot. shows when Schedule is set to Hourly. Enter the hour and minute when the system can begin taking snapshots.
End
Sets the end time for a snapshot. Shows when Schedule is set to Hourly. Enter the hour and minute the system must stop creating snapshots. Snapshots already in progress continue until complete.
Allow Taking Empty Snapshots
Sets the task to allow taking a snapshot and creating a dataset even when there are no changes to the dataset from the last snapshot. Recommended for long-term restore points, multiple snapshot tasks pointed at the same datasets, or compatibility with snapshot schedules or replications created in TrueNAS 11.2 and earlier. For example, you can set up a monthly snapshot schedule to take monthly snapshots and still have a daily snapshot task taking snapshots of any changes to the dataset.
Enabled
Activates this periodic snapshot schedule. To disable this task without deleting it, leave the checkbox cleared.
VMWare Snapshots Screen
Use the VMware Snapshot Integration option on the Data Protection > Periodic Snapshot Tasks widget to create snapshots when you are using TrueNAS as a VMWare datastore.
See Creating VMWare Snapshots for a detailed tutorial.
VMware Snapshot Integration opens the VMWare Snapshots screen.
Enter the IP address or host name of the VMWare host. When clustering, enter the vCenter server for the cluster.
Username
Enter the user on the VMWare host with permission to snapshot virtual machines.
Password
Enter the password associated with the user entered in Username.
Datastore
Select a VMFS datastore to synchronize with the host from the dropdown list of options. Click Fetch DataStores to populate this list with options from the VMWare host. You must click Fetch Datastores before you click in this field or the creation process fails. Selecting a datastore also selects any mapped datasets.
ZFS Filesystem
Select a TrueNAS ZFS dataset from the dropdown list of options. This field does not populate until you click Fetch Datastores. You must click Fetch Datastores before clicking in this field or the creation process fails.
Click Fetch DataStores to connect TrueNAS to the VMWare host.
This synchronizes TrueNAS with the VMWare host and populates the ZFS Filesystem and Datastore dropdown lists with the information from TrueNAS and the VMWare host response.
Configured snapshots show on the VMware Snapshots screen.
The Replication Task widget on the Data Protection screen lists replication tasks configured on the TrueNAS system.
Replication tasks work with periodic snapshot tasks to complete the replication.
After scheduling a replication task, the Periodic Snapshot Task widget shows a new task for the newly added replication task.
The delete Delete icon opens a delete confirmation dialog.
State displays the status of the replication task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Replication Tasks Screen
The Replications Tasks screen lists the replication tasks configured on the system.
Columns displays a list of options to customize the list view to add or remove information to the table.
Options are Select All, Name, Direction, Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, Auto, Last Run, State, Enabled, Last Snapshot, and Reset to Defaults.
Before adding replication tasks this screen displays No Replication Tasks and the Add Replication Tasks option that opens the Replication Task Wizard.
Enter a new name for the task and select the location to store the data, then click Restore.
The system creates the new file and displays the task on both the widget and list screen with the PENDING status.
Download encryption keys Option
When a replication task involves a key-encrypted source or destination, the icon shows in the task options.
This downloads any encryption keys to your local system.
Delete Option
The deleteDelete icon opens a delete confirmation dialog.
There are two ways to add a replication task, the wizard and the advanced creation screen.
These two methods share many settings that are described below. The Edit Replication Task screen shows the same settings.
Shared settings are documented in these sections:
Add, or if no replication task exist, Add Replication Tasks opens the wizard.
Replication Task Wizard
The wizard has two screens:
What and Where settings specify the task name, data source and destinations, the type of replication (local or remote), transport options (SSH connection), schema or regular expression that names the snapshot created by the task, and if selected, sets up encryption on the data transfer.
When settings specify when to run the task and how long to retain the replicated snapshots.
Advanced Replication Creation opens the Add Replication Task screen with the same settings found in the wizard and more advanced settings.
If you populate wizard settings and then click Advanced Replication Creation, TrueNAS shows you the dialog asking you to confirm you want to leave the screen.
After clicking Yes the Add Replication Task screen opens but values entered in the wizard are not transfered to the Add Replication Task screen.
What and Where Wizard Screen
The What and Where screen shows settings for both the source and destination information (path to the dataset), the source and destination transfer direction, encryption settings for the data transfer, remote replication SSH connections, naming schema to apply to the snapshot taken through the replication task, and the name for the task.
The Encryption and SSH Connection options show when the source or destination is set to On a Different System.
Encryption applies another layer of protection to the data transfer, it is not the encryption of the data stored or the dataset.
You can use an existing SSH connection created using the Credentials > Backup Credentials > SSH Connection screen or create a new connection through the replication task wizard or screens.
SeeConfigure SSH for more information on adding a Backup Credential SSH credentials.
Settings showing on the wizard screen change based on the Source Location and Destination Location option selected.
On this System (local replication) and On a Different System (remote replication) show settings that apply to or are needed to set up that type of replication.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Setting Source Location to On This System and Destination Location to On a Different System and making naming schema choices changes the wizard screen to show all available settings.
Shows a list of previous replication tasks that, when selected, loads settings from the saved replication task. Select an existing snapshot to populate the Source Location, Destination Locations, Source, and Destination fields. Also populates Task Name with a name that is a combination of the source-destination for the selected task.
Source Location
Select the storage location of the original replicated snapshots. Options:
On this System (local replication) - Allows setting On a Different System to a local or remote destination.
On a Different System (remote replication) - When set to On a Different System, the Destination Location automatically changes to On this System and the Destination field displays the path to the snapshot location. For more information on these setting options see Source Location Setting Options.
Source
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Location
Select the storage location for the replicated snapshots. Options are On this System or On a Different System but if Source is set to On a Different System, the Destination Location automatically changes to On this System, and the Destination field displays.
Destination
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Destination field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
SSH Connection
Shows a list of existing SSH connections saved on the system and the option to add a new SSH connection. Select an existing SSH connection to a remote system or select Create New to open the New SSH Connection window to configure a new SSH connection to a remote system. Shows the Use Sudo for ZFS Commands dialog to enable sudo for SSH sessions.
Use Sudo For Zfs Commands
Select if setting up remote replication tasks when logged in as an admin user.
Recursive
Select to also replicate all snapshots contained within the selected source dataset snapshots. Leave clear to only replicate the selected dataset snapshots.
Replicate Custom Snapshots
Shows after setting Source Location to On this System. Select to replicate snapshots that are not created by an automated snapshot task. After selecting, shows the Also include snapshots with the name setting options. This setting requires setting a naming schema for the custom snapshots through one of the two methods: Naming Schema or Snapshot Name Regular Expression.
Also include snapshots with the name
Select the option to set the snapshot naming pattern as either a naming schema or regular expression. Options:
Naming Schema and Snapshot Name Regular Expression.
Naming Schema
Shows after selecting Naming Schema under Also include snapshots with the name. Enter the pattern of naming custom snapshots to replicate. Enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Naming schema must include %Y, %m, %d, %H and %M. Separate entries by pressing Enter. The number of snapshots matching the patterns displayed on the screen.
Snapshot Name Regular Expression
Shows after selecting Snapshot Name Regular Expression under Also include snapshots with the name. Enter the regular expression that the replicated snapshot(s) should match. This option replicates all snapshots with names matching the specified regular expression. Performance on systems with large numbers of snapshots is lower as this process reads snapshot metadata to determine snapshot creation order. Naming of regular expressions include name followed this pattern, auto-[0-9-]+|manual-[0-9]+.
SSH Transfer Security
Shows after selecting Replicate Custom Snapshots. Applies data transfer security. Shows two options: Encryption (more secure, but slower) and No Encryption (less secure, but faster). The connection is authenticated with SSH. Encryption is recommended, but can be disabled for increased speed on secure networks.
Encryption
Select to apply an extra layer of encryption on the data transfer when replicating data. For more information on all options, see Encryption below.
Task Name
Shows the name the system adds from the source and destination options or enter a different name for this replication configuration to overwrite the automatically populated task name. By default, the system populates Task Name with the source-destination names selected or loaded by selecting a task in Load Previous Replication Tasks. The system prompts you to change the name if a task uses the name. Changing the name can be as simple as adding an iteration number, such as 2 or 3, to the default name.
Encryption Options
The Encryption option shows additional settings on the Add Replication Task screen and the What and Where wizard screen below the Destination settings.
Select to apply an extra layer of encryption when replicating data to a remote server. Shows additional encryption settings Encryption Key Format and Store Encryption key in Sending TrueNAS database options.
Inherit Encryption
Select for the target dataset to inherit encryption from its parent dataset.
Encryption Key Format
Select the encryption option from the dropdown list. Hex (base 16 numeral) or Passphrase (alphanumeric) style encryption key. Selecting Hex displays the Generate Encryption Key option. Selecting Passphrase displays the Passphrase option.
Generate Encryption Key
Displays after selecting Hex in Encryption Key Format. Selected by default. Clearing the checkbox displays the Encryption Key field.
Encryption Key
Displays after clearing the Generate Encryption key checkbox. Use to import a custom hex key.
Passphrase
Displays when Encryption Key Format is set to Passphrase. Enter the alphanumeric passphrase to use as an encryption key.
Store Encryption key in Sending TrueNAS database
Displays after selecting Encryption. Selected by default. Select to store the encryption key in the TrueNAS database. Clearing the checkbox displays the Encryption Key Location in Target System field.
Encryption Key Location in Target System
Displays after clearing the Store Encryption key in sending TrueNAS database checkbox. Enter a temporary location for the encryption key that decrypts replicated data.
New SSH Connection
The New SSH Connection window opens after selecting Create New in the SSH Connection field.
It allows you to set up a new SSH connection for the remote system.
(Required) Enter a unique name for this SSH connection.
Setup Method
Select how to configure the connection from the dropdown list. Options:
Manual - Select to configure authentication on the remote system. This option can include copying SSH keys and modifying the root user account on that system.
Semi-Automatic - Select when configuring an SSH connection with a remote TrueNAS system. This method uses the URL and login credentials of the remote system to connect with and exchange SSH keys. This option only works when the other system is a TrueNAS system.
TrueNAS URL
(Required) Ener the host name or IP address of the remote system. A valid URL scheme is required. For example, https://10.235.12.20.
Admin Username
(Required) Enter the user name for logging into the remote system via the UI.
Admin Password
(Required) Enter the password for logging into the remote system.
One-Time Password (if necessary)
Enter the one-time password if two-factor authentication is enabled.
Username
(Required) Enter the user name for logging into the remote system via SSH.
Private Key
(Required) Select a saved SSH keypair or Generate New to create a new keypair to use for this connection.
Connect Timeout
Enter the time (in seconds) before the system stops attempting to establish a connection with the remote system.
When Wizard Screen
The When wizard screen sets the schedule for running the task and the retention period for keeping the replicated snapshots.
Replication Schedule and Destination Snapshot Lifetime options change the setting displayed on the screen.
Replication Schedule Options
The Replication Schedule options set when to run the task based on the schedule defined in Schedule or to run it one time.
Displays the Schedule option where you select a preset time or select Custom to use the advanced scheduler.
Run Once
Runs the replication task after you click Start Replication. Displays the Make Destination Dataset Read-only? option. Removes the Schedule option.
Schedule
Displays after selecting the Run On a Schedule radio button. Select a preset time or can select Custom to use the advanced scheduler.
Make Destination Dataset Read-only?
Displays after selecting the Run Once radio button. Select to change the destination dataset to be read-only. To continue using the default or existing dataset read permissions, leave this checkbox cleared.
Destination Snapshot Lifetime Options
The Destination Snapshot Lifetime setting determines how long the replicated snapshot is retained on the destination server.
TrueNAS always preserves the latest snapshot so replication can resume later.
If you delete a dataset or zvol on the source, you must manually delete the replicated dataset or zvol and the most recent snapshot on the destination.
Select to use the configured snapshot Lifetime value from the source dataset periodic snapshot task.
Never Delete
Select to never delete snapshots from the destination system.
Custom
Select to define how long the snapshot remains on the destination system. Displays the number of and measure of time fields to set the schedule.
Number of
Enter a numeric value to work with the measure of time selection to set the custom lifetime of the snapshot.
Measure of time
Select the option for Hours, Days, Weeks, Months, or Years to work with the number-of field to set the custom lifetime of the snapshot.
Add and Edit Replication Task Screens
Advanced Replication Creation opens the Add Replication Task screen.
The Edit icon button opens the Edit Replication Task screen. The Add Replication Task and Edit Replication Task screens show the same setting options.
The Add Replication Task screen shows the Switch to Wizard button at the bottom of the screen.
Switch to Wizard, like Advanced Replication Creation shows the dialog asking you to confirm you want to leave the screen. After clicking Yes the wizard or Add Replication Task screen opens.
Settings entered on either screen do not carry over when switching from one screen to the other.
General and Transport Options Settings
The settings in General and Transport Options specify the name of the task, the direction of the data transfer, the transport connection type, and method settings for each type.
The Transport setting changes options displayed in the Transport Options area (SSH is the default setting).
All three Transport field options share the two settings displayed for Local, and the SSH Connection field displays for both the SSH and SSH+NETCAT transport selections.
(Required) Enter a descriptive name for the replication.
Direction
Select the direction for the replication from the dropdown list. Push sends snapshots to a destination system. Pull connects to a remote system and retrieves snapshots matching the value specified in Naming Schema.
Transport
Select the method of connecting to a remote system for exchanging data from the dropdown list. Options:
SSH - Default option that is supported by most systems, but does not achieve great performance. Transfers the snapshot via an SSH connection. It requires a previously created SSH connection on the system.
SSH+NETCAT - Uses SSH to establish a connection to the destination system, then uses py-libzfs to send an unencrypted data stream for higher data transfer speeds. This can only be used in trusted networks and requires a port to be open on the NETCAT active side. This only works when replicating to a FreeNSAS, TrueNAS, or other systems with py-libzfs installed.
LOCAL - Efficiently replicates snapshots to another dataset on the same system without using the network. Removes Transport Options SSH setting options from the screen.
Use Sudo For Zfs Commands
Select if setting up remote replication tasks when logged in as an admin user. Controls whether the user used for SSH/SSH+NETCAT replication have passwordless sudo enabled to execute zfs commands on the remote host. If not selected, zfs allow must be used to grant non-user permissions to perform ZFS tasks. Mounting ZFS file systems by non-root is notpossible due to Linux restrictions.
Number of retries for failed replications
Enter the number of times the replication is attempted before stopping and marking the task as failed.
Logging Level
Select the level of message verbosity in the replication task log from the dropdown list. Options are Default, Debug, Info, Warning, and Error.
Enabled
Select to enable the replication schedule.
Transport Options Settings - Local Transport Option
These settings display for all three Transport options.
Selected by default. If the system does not support large block transfers this is not selected by default. Allows replication to send large data blocks. The destination system must also support large blocks. This setting cannot be changed after it is enabled and the replication task is created. See sfs(8) for more information.
Allow Compressed WRITE Records
Selected by default. If enabled, allows using compressed write records to make the stream more efficient. The destination system must also support compressed write records. See zfs(8).
Transport Options Settings - SSH Transport Option
When Transport is set to SSH, the settings listed below show in addition to the setting options the Allow Blocks Larger than 128KB and Allow Compressed WRITE Records options shown when Transport is set to Local.
Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Stream Compression
Select a compression algorithm from the dropdown list to reduce the size of the data being replicated. Only appears when SSH is chosen as the Transport type.
Limit (Examples: 500 KiB, 500M, 2 TB)
Enter the number of bytes per second to limit replication speed to this number of bytes per second.
Transport Options Settings - SSH+NETCAT Transport Option
When Transport is set to SSH+NETCAT, the settings listed below show in addition to the setting options the Allow Blocks Larger than 128KB and Allow Compressed WRITE Records options shown when Transport is set to Local.
Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Netcat Active Side
Select the option for the system that opens ports from the dropdown list. Options are Local or Remote. Establishing a connection requires that one of the connection systems has open TCP ports. Consult your IT department to determine which systems are allowed to open ports.
Netcat Active Side Listen Address
Enter the IP address on which the connection Active Side listens. Defaults to 0.0.0.0.
Netcat Active Side Min Port
Enter the lowest port number of the active side listen address that is open to connections.
Netcat Active Side Max Port
Enter the highest port number of the active side listen address that is open to connections. The first available port between the minimum and maximum is used.
Netcat Active Side Connect Address
Enter the host name or IP address used to connect to the active side system. When the active side is Local, this defaults to the SSL_CLIENT environment variable. When the active side is Remote, this defaults to the SSH connection host name.
Advanced Source Options
Source settings specify the location of files you push or pull in the replication task, and the properties applied to the replicated data.
Selections made in Recursive and Replicate Specific Snapshots change the Source setting options, and each option shows additional setting options.
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset. Click the arrow_drop_down at the /mnt to collapse the dataset tree.
Recursive
Select to replicate all child dataset snapshots. When selected, Exclude Child Datasets displays.
Exclude Child Datasets
Displays after selecting Recursive. Enter the specific child dataset snapshots to exclude from the replication. Separate each entry by pressing Enter.
Include Dataset Properties
Select to include ZFS dataset properties with the replicated snapshots. Shows additional settings: Properties Overide and Properties Exclude. For more information on ZFS dataset properties see ZFS manpages.
Full Filesystem Replication
Select to completely replicate the selected dataset. The target dataset gets all the properties of the source dataset, child datasets, clones, and snapshots that match the specified naming schema. Hides the Recursive and Include Dataset Properties options, and shows Properties Override and Properties Exclude. Set Snapshot Name Regular Expression to .* to replicate all snapshots.
Properties Override
Enter properties to replace existing dataset properties within the replicated files.
Properties Exclude
Enter any existing dataset properties to remove from the replicated files.
Advanced Destination Options
The settings in Destination specify the location of files you push or pull in the replication task, and the properties applied to the replicated data.
Selections made in Encryption and Snapshot Retention Policy change the destination setting options, and each show additional setting options.
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. Selecting a location defines the full path to that location as the destination. Appending a name to the path creates a new zvol at that location. For example, selecting pol1/dataset1 stores snapshots in dataset 1, but adding /zvol1 after dataset1 creates zvol1 for snapshot storage. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Dataset Read-Only Policy
Select the policy from the dropdown list. Options:
Set - Select to change all destination datasets to read only after a successful replication.
Require - Select to stop replication unless all existing destination datasets are read only.
Ignore - Select to disable checking read only during replication.
Encryption
Select to use encryption when replicating data. For more information on all options, see Encryption.
Replication from scratch
Select if the destination system has snapshots, but does not have any data in common with the source snapshot, destroy all data in destination snapshots, and do a full replication. WARNING! Enabling this option can cause data loss or excessive data transfer if the replication is misconfigured.
Snapshot Retention Policy
Select the policy from the dropdown list to apply when replicated snapshots are deleted from the destination system. Options are:
Same as Source - When selecting Same as Source use the Snapshot Lifetime from the source periodic snapshot task.
Custom - When selecting Custom define a Snapshot Lifetime for the destination system. Also displays the Snapshot Lifetime and Unit options.
None - When selecting None never delete snapshots from the destination system.
Snapshot Lifetime
Use to enter a numeric value to work with the measure of time field below to specify how long a snapshot remains on the destination system.
Unit
Select the measure of time from the dropdown list to work with the numeric value in Snapshot Lifetime. Options are Hour(s), Day(s), Week(s), Month(s), and Year(s).
Various Snapshot Options
The snapshot settings below change options displayed based on selections made.
Select the snapshot schedule for this replication task from the dropdown list. Select from previously configured periodic snapshot tasks. This replication task must have the same Recursive and Exclude Child Dataset values as the selected periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
Replicate Specific Snapshots
Select to only replicate snapshots that match a defined creation time. Selecting this option shows the By snapshot creation time field. Select the preset schedule or Custom to use the advanced scheduler.
Begin
Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created before this selected time are not included in the replication.
End
Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created after this selected time are not included in the replication.
Also include snapshots with the name
These radio buttons change the naming schema setting option below it. See Snapshot Naming in the wizard section for details on this option and the radio buttons.
Matching naming schema
Displays the Also Include Naming Schema setting.
Matching regular expression
Displays the Matching regular expression setting.
Also Include Naming Schema
Displays after selecting Matching naming schema. Enter the pattern of naming custom snapshots to include in the replication with the periodic snapshot schedule. Enter the strftime(3) strings that match the snapshots to include in the replication. When a periodic snapshot is not linked to the replication, enter the naming schema for manually created snapshots. Has the same %Y, %m, %d, %H, and %M string requirements as the Naming Schema in a Add Periodic Snapshot Task. Separate entries by pressing Enter.
Matching regular expression
Displays after selecting Matching regular expression. Replicates all snapshots that match the specified regular expression. This process reads snapshot metadata to determine the snapshot creation order. This slows regular performance on the systems with a large number of snapshots.
Save Pending Snapshots
Prevents source system snapshots that have failed replication from being automatically removed by the Snapshot Retention Policy.
Replication Schedule Advanced Options
These schedule setting options are common to both the Replication Task Wizard and Add Replication Task screens.
Select to start this replication task immediately after the linked periodic snapshot task completes.
Schedule
Select to create a replication schedule if not selecting Run Automatically. Displays the Frequency and Only Replicate Snapshots Matching Schedule options. Shows a list of schedule preset options. See Schedule Presets below for more info.
Frequency
Displays after selecting Schedule. Select a preset schedule or choose Custom to use the advanced scheduler and show the Begin and End options.
Begin
Displays after selecting Hourly in Frequency. Select the start time for the replication task.
End
Displays after selecting Hourly in Frequency. Select the end time for the replication task. A replication that is already in progress can continue to run past this time.
Only Replicate Snapshots Matching Schedule
Displays after selecting Schedule. Select to use the Schedule in place of the Replicate Specific Snapshots time frame. The Schedule values are read over the Replicate Specific Snapshots time frame.
Network
The TrueNAS Network screen shows network configuration and settings options, in widgets for active interfaces, static routes, and the network configuration.
The Network screen also provides access to IPMI channels. IPMI only shows on systems with physical hardware but not for virtual machine deployments.
To access the Network screen, go to System on the main navigation menu, then click Network.
The articles listed below provide more information on Network screen widgets and screens.
Additional Network Articles
Network Interface Screens: Provides information on the Network screen Interfaces widget and configuration screens.
Network Configuration Screens: The Network Configuration widget shows the general TrueNAS network settings not specific to any interface.
Static Routes Widget: The Static Routes widget displays existing static routes or sets up new ones.
IPMI Screens: Provides information on the Network screen IPMI widget and configuration screen.
Network Interface Screens
The Interfaces widget on the Network screen shows the configured interface port names and IP addresses, and the MAC addresses associated with network interface cards in your TrueNAS system.
High Availability (HA) Enterprise systems cannot reset or edit interface settings with failover enabled.
On systems with HA failover enabled, the refresh Reset Configuration or edit Edit options are disabled.
Go to System > Failover to disable failover before attempting to modify interfaces on HA systems.
Confirm validates the reset activity and activates the Reset button.
Reset resets the configuration for that interface. Resetting the configuration shows the test change options to prevent losing access to that interface and the TrueNAS system.
Add/Edit Interface Screens
The Add Interface screen allows you to configure the settings for a new interface.
The Edit Interface screen allows changes to settings for an existing interface.
Both screens show the test changes options to validate settings and prevent losing access to the TrueNAS system if the interface is incorrectly configured.
The setting on the Add Interface and Edit Interface screens are almost identical.
Type only shows on the Add Interface screen. It cannot be changed on the Edit Interface screen.
Type is a required field. The additional settings show on the Add Interface screen based on the selected type.
Apply saves setting changes, and shows the test changes options.
Interface Settings
Interface settings configure the network interface name, type, and IP address assignment. These settings are common to the three interface types.
(Required) Only shows on the Add Interface screen. Sets the type of interface based on the selection on the dropdown list. Options are:
Bridge - Creates a logical link between multiple networks.
Link Aggregation (LAGG) - Combines multiple network connections into a single interface.
VLAN - Partitions and isolates a segment of the connection.
Each type of interface shows additional configuration settings for that type. The type cannot be changed after clicking Apply, and testing and accepting the interface change.
Name
(Required) Accepts manual or copy/paste entry of a name for the interface. Names must use the format bondX for a LAGG, vlanX for a VLAN, or brX for a bridge, and where X is a number representing a non-parent interface. Assign the first interface of any type the appropriate name plus zero, for example, br0 for the first bridge interface created. You cannot change the interface name after clicking Apply. After saving, Name becomes a read-only field when editing an interface.
Description
Accepts manual or copy/paste entry of a description for the interface. Descriptions can provide additional information about how the interface is used or what it connects to.
DHCP
Enable DHCP, allowing it to assign IP addresses to the interface. Shows two options: Get IP Address Automatically from DHCP and Define Static IP Addresses.
Get IP Address Automatically from DHCP
Allows DHCP to assign the IP address for the interface. Only one interface can be configured using DHCP.
Define Static IP Addresses
Allows adding a static IP address to the interface using the Static IP Addresses fields.
Static IP Addresses
Shows IP address and netmask (CIDR) fields after clicking Add. Click Add for each static IP address to add to/associate with the interface.
Autoconfigure IPv6
Select to automatically configure the IPv6 address with rtsol(8). Only one interface can be configured this way.
MTU
Sets the maximum transmission unit (MTU), which is the largest protocol data unit that can be communicated. The largest workable MTU size varies with network interfaces and equipment. 1500 and 9000 are standard Ethernet MTU sizes. Leaving blank restores the field to the default value of 1500.
Bridge Settings
Bridge settings show after setting Type to Bridge. TrueNAS automatically populates the Name with the default br1.
Use Description to further define or clarify how or where the bridge is used.
(Required) Select the network interfaces to include as members of the bridge. The dropdown lists interfaces eligible for bridging.
Enable Learning
Select to enable MAC address learning. With learning enabled, the bridge records the MAC address of each incoming frame along with the member interface it arrived on. The bridge then uses this table to send outbound traffic only to the relevant member instead of flooding it to every member. Selected by default. Disable only in specialized configurations where the default learning behavior conflicts with how the bridge is being used, such as when a bridge member might not be available when the bridge starts.
Link Aggregation Settings
Link aggregation (LAGG) settings show after setting Type to Link Aggregation. TrueNAS automatically populates Name with the default bond1.
Use Description to further define or clarify how or where the LAGG is used.
The protocol determines the outgoing and incoming traffic ports. Shows a dropdown list with three Link Aggregation (LAGG) protocol options:
LACP - Use if the network switch is capable of active LACP (this is the recommended protocol). LACP shows additional settings.
Failover - Use if the network switch does not support active LACP. This is the default protocol choice and is only used if the network switch does not support active LACP. Failover uses only the Link Aggregation Interfaces setting. <br
Loadbalance - Use to set up loadbalancing. This does not use any other link aggregation settings.
Link Aggregation Interfaces
(Required) Shows a dropdown list of interfaces in the system. Select the interfaces to use in the aggregation. Warning! Link Aggregation creation fails if any of the selected interfaces are manually configured!
Failover shows the interfaces that can be enabled for failover. Enabling the toggle select the interface.
Loadbalance shows the Transmit Hash Policy setting.
Transmit Hash Policy
Shows when the protocol is set to LCAP or Loadbalance. Dropdown list shows three hash policy options, LAYER2, LAYER2+3 the default, or LAYER3+4.
LACPDU Rate
Shows when the protocol is set to LCAP. Shows a dropdown list with two options: Slow or Fast.
VLAN Settings
VLAN settings show after setting Type to VLAN. TrueNAS automatically populates the Name with the default vlan1.
Use Description to further define or clarify how or where the bridge is used.
Shows a dropdown list of VLAN parent interface options. Options are usually an Ethernet card connected to a switch port configured for the VLAN. New link aggregations are not available until you restart the system.
VLAN Tag
(Required) Accepts manual or copy/paste entry of the numeric tag configured in the switched network. Request this tag from your IT department if you are not the network administrator for your systems.
Priority Code Point
Shows a dropdown list of the class of service options. The available 802.1p class of service ranges from Best effort (default) to Network control (highest).
Test Changes
These options show above the Interfaces widget after applying changes to a network interface that can affect access to the UI., and are used to test network changes when creating a new or changing an existing network interface
Revert Changes discards changes made within the 60-second period.
Save Changes shows after logging into the UI in a new browser window. Makes network changes permanent. Shows as the final part of the testing network interface changes process.
Network Configuration Screens
The Network Configuration widget shows the general networking settings for the TrueNAS system.
DNS Servers shows the IP addresses for the primary and secondary name servers.
Default Route shows the IP address for the default gateway.
The remaining general network settings shown in the widget are the system host name, domain name, HTTP proxy address, any configured service announcement, additional domains, the host name database, and the outbound network setting.
Settings opens the Edit Global Configuration screen, where you can add or change global network settings for the TrueNAS system.
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Do not configure network settings to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers.
This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started.
Edit Global Configuration Screen
The Edit Global Configuration screen manages general network settings for your TrueNAS system that are not specific to any interface.
Many of these fields have default values, but users can change them to meet local network requirements.
Some fields only show in the Edit Global Configuration screen when the appropriate hardware is present.
Setting
Description
Hostname
Sets the system host name. The default value is truenas. Some applications require setting this to a value other than truenas. If using Active Directory or SMB services, the hostname is also used as the NetBIOS name and must comply with NetBIOS naming restrictions: maximum 15 characters, cannot contain `\ / : * ? " < >
Inherit domain from DHCP
Sets the domain to be inherited from DHCP when selected.
Hostname (TrueNAS Controller 2)
Sets the system host name for a second controller in High Availability (HA) systems where there is a second TrueNAS controller. A name can consist of upper and lower case alphanumeric and allowed special characters dot (.) and/or dash (-).
Hostname (Virtual)
Sets a virtual host name that shows when using a virtual host, for example, on a TrueNAS High Availability system. Also used as the Kerberos principal name. Enter the fully qualified host name plus the domain name. A name can consist of upper and lower case alphanumeric and the allowed special characters, dot (.) and/or dash (-).
Domain
Enter a system domain name, for example, example.com.
Additional Domains
Specifies additional domains to search. Separate entries by pressing Enter. Adding search domains can cause slow DNS lookups.
Service Announcement Settings
Setting
Description
NetBIOS-NS
Sets TrueNAS to use a legacy NetBIOS name server. This advertises the SMB service NetBIOS name. Setting this might be required for legacy SMB1 clients to discover the server. When advertised, the server appears in Network Neighborhood.
mDNS
Sets TrueNAS to use multicast DNS. This uses the system host name to advertise enabled and running services. For example, it controls whether the server shows under Network on MacOS clients.
WS-Discovery
Sets TrueNAS to use the SMB service NetBIOS name to advertise the server to WS-Discovery clients. This can cause the computer to appear in the Network Neighborhood of modern Windows operating systems.
Sets the IP address for the primary DNS server (nameserver 1).
Secondary
Sets the IP address for the secondary DNS server (nameserver 2).
Tertiary
Sets the IP address for the third DNS server (nameserver 3).
Setting
Description
IPv4 Default Gateway
Sets the IPv4 address for the default gateway. This overrides a default gateway provided by DHCP.
IPv6 Default Gateway
Sets the IPv6 address for the default gateway of the IPv6 network. This overrides a default gateway provided by DHCP.
Outbound Network and Other Settings
The Outbound Network setting should match the preferred system services allowed to communicate externally for your use case.
The Other Settings allow setting an HTTP proxy and any host name database preferences.
Allows any system service to communicate externally.
Deny All
Restricts this system from communicating externally.
Allow Specific
Allows a limited set of system services to allow to communicate externally to those selected on the dropdown list. All other external traffic is restricted. A dropdown list shows the services you select to allow external communication.
Allow All Except
Allows all system services to communicate externally except for the services selected on the dropdown list. A dropdown list shows the services you select to deny external communication.
Specifies additional hosts to append to /etc/hosts. Accepts manual or copy/paste entry in the format IP_address space hostname where multiple host names can be used if separated by a space. Separate entries by pressing Enter. Hosts defined here are still accessible by name even when DNS is not available. See hosts for additional information.
Static Routes Widget
The Static Routes widget on the Network screen shows static IP addresses configured as static routes.
Allows manual entry of IP address routes to network destinations outside the TrueNAS network so the router can send packets to a destination network.
Select which controller to configure IPMI settings for. Options are Active or Standby controller. All IPMI configuration changes and the identify light feature apply only to the selected controller.
DHCP
Select to use DHCP to assign IPv4 network values. Clear the checkbox to manually configure a static IPv4 connection.
IPv4 Address
Enter the IPMI web interface static IPv4 address.
IPv4 Netmask
Enter the IPv4 address subnet mask.
IPv4 Default Gateway
Enter the IPv4 connection default gateway.
VLAN ID
Enter the VLAN identifier of the IPMI out-of-band management interface is not on the same VLAN as management networking.
Password
Enter an 8-16 character password for connecting to the IPMI interface from a web browser. The password must include at least one upper case letter, one lower case letter, one digit, and one special character (punctuation, e.g. ! # $ %, etc.).
Save
Save the configuration.
Manage
Opens the IPMI manager in a new browser tab where users can communicate with the server without having direct access to the hardware.
Flash Identify Light
Flashes the system IPMI light on the compatible connected hardware. On HA systems, flashes the light on the selected controller only.
Stop Flashing
Stops flashing the system IPMI light on the compatible connected hardware. On HA systems, stops flashing the light on the selected controller only.
Credentials
TrueNAS Credential options are collected in this section of the UI and organized into a few different screens:
Contents
Users Screens: Provides information on the Users screens and settings in TrueNAS.
Groups Screens: Provides information on the Groups screens and settings.
Backup Credentials: Information on backup credential screens and settings to integrate TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about the Certificates screen and widgets.
KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS Enterprise.
Users Screens
The Credentials > Users screen shows a table with all users created on the system. A set of cards shows for the selected user row (the first row is selected by default).
The truenas_admin user is the first user row, and it therefore shows by default when you first access the screen.
Switch to Advanced link shows in the search field when in basic search mode.
Switch to Advanced shows advanced search options, an advanced search syntax example in the search field, and several Add Filter buttons directly below the search field for common search options. The users table shows all users in the system.
Switch to Basic option shows in the search field when in advanced search mode. Switch to Basic returns to the basic user table view.
User Table
The Users screen user table shows the Username, Full Name, Type, and pre-defined administrator role assigned to the user (Access) for each user.
Username, Full Name, and Type sort the list in ascending or descending order.
Each user row also shows an icon showing the level of access given to the user.
Icon
Description
Indicates the user has TrueNAS Access.
Indicates the user has SMB access.
power
Indicates the user has an API key.
By default, only local users show in the user table. The Filter by Type dropdown list has three options to show all users in the system:
Built-in - Shows all built-in users.
Local - Shows all users added by an administrator account.
Directory Services - Shows all users added by a directory service like LDAP, FreeIPA, or Active Directory.
Filter by Type allows selecting multiple filter options.
The selected user row shows values for that user in the Details for user cards.
User Cards
The User screen shows up to three cards for each user based on the type of user:
Profile - Shows for all user types (local, built-in, directory service created users).
Password - Shows for users that require access to the UI, SSH, or communication to or with external services or users.
The Password card shows for users who require credentials to access the UI, an SSH session, or have external communication capabilities (Built-in users).
The card shows the password age, which is how long that password has been in use, and the date and time it was last changed.
The Password card for the truenas_admin and admin users not currently logged in shows the Generate One-Time Password button. To see this button, the selected user must not be the user currently logged into TrueNAS, must not be a built-in user, and must have TrueNAS Access selected and a role assigned with account write permissions (e.g., the Full Admin role).
Copy to Clipboard copies the password key to the clipboard so you can paste it into a saved text file for later use when TrueNAS prompts you to enter it.
Access Card
The Access card has three sections: last action, password status, and any roles, API keys, or access privileges granted to SSH and shell, and shows the Shell settings and access path. When global two-factor authentication is set, it shows the Clear Two-Factor Authentication button.
Information details on the Access card:
Last Action can be a method call for the action taken (like opening a log file), log in or log out, or none. It shows the date and time of that last action.
See Logs link opens the Audit screen for the selected user.
Password Login status is Enabled or Disabled. A key icon when the user has a password, or an inactive key icon when the user does not have a password. Users with passwords show the Password card.
Service access, such as SMB Access or WebShare Accesss indicates the user has that access granted.
TrueNAS Access and the role assigned to the user, such as Full Admin, Share Admin, Read Only Admin.
API keys assigned or not. When a key exists, the icon changes and shows a number with the key, for example, 1 key.
Add API Keys link shows when no key exists, and it opens the Add API Key screen.
View API Keys link shows when a key exists and opens the User API Key screen.
SSH Access is active or inactive if not granted.
Shell Access path.
Sudo Command Access granted.
Allowed Sudo Commands setting
Allowed Sudo Commands (No Password) setting
The following table legend shows the icons found on the Access card:
Icon
Description
Indicates user has a password.
Indicates the user has TrueNAS Access.
Indicates the user has SMB access.
power
Indicates the user has an API key.
Indicates the user has SSH access.
Indicates the user has shell access.
Lock User/Unlock User
Lock User opens a confirmation dialog before locking the user. A locked user is prevented from logging in or using password-based services while locked.
This button toggles to Unlock User, which shows a confirmation dialog before unlocking the user.
Clear Two-Factor Authentication shows when the user has 2FA configured. Opens a confirmation dialog before clearing the two-factor authentication settings for the user.
This administrative function helps users who have lost access to their authenticator device or are experiencing 2FA-related login issues.
When cleared, the user can log in without 2FA. If Global 2FA is enabled, the user is prompted to reconfigure 2FA on their next login.
Clearing 2FA for a user should only be done when necessary, such as when the user has lost access to their authenticator device. This action temporarily reduces account security until 2FA is reconfigured.
Delete User
The Delete User dialog shows the name of the user selected in the user table on the Users screen.
Deleted user primary group name removes the primary group created for the user (of the same name as the username) from TrueNAS.
Delete removes the user profile from TrueNAS and the primary group if the option is selected.
Add or Edit User Screens
The Add User and Edit User configuration screens show the same setting options, but a few options are not editable.
Built-in users (except the root user) do not show the home directory settings, but all new users created and the SMB share smbguest user do.
Username and Allow Access Settings
The Username and Allow Access settings specify the username and level of access (privileges granted) given to the user.
Each access option changes the settings shown in other sections of the Add User and Edit User screens.
Specifies the required name for the user. A user name consists of up to 32 characters. When using NIS or other legacy software with limited user name lengths, keep names to eight characters or less for compatibility. Names should not begin with a hyphen (-), include a space, tab, or these special characters: comma (,), plus (+), ampersand (&), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), question mark (?), greater-than or less-than symbols (<)(>), or equal (=).
Allow Access
Specifies the access granted to the user account. Each option shows different settings. Access options are:
SMB Access - The default option is pre-selected.
WebShare Access - Adds WebShare access for the user.
TrueNAS Access - Shows the Select Role dropdown and the custom roles link that opens the TrueNAS documentation article on pre-defined administrator roles.
Shell Access - Adds the Shell and Sudo Commands options to the Additional Details section.
SSH Access - Deactivates the Shell Access option, but shows the Shell and Sudo Commands options found with Shell Access. Shows the Allow SSH Login with Password (not recommended) option, and the Public SSH Key field.
Select Role
Sets the privilege level for the user to one of the predefined user roles (Full Admin, Sharing Admin, or Readonly Admin). Shows after selecting TrueNAS Access. Each role adds the appropriate group to the Groups option under Additional Details.
Authentication Settings
Authentication settings show after selecting Shell Access or SSH Access options under Allow Access. Password shows for all access options.
(Required) Text entry field for the password or passphrase the user enters when logging into the UI or an SSH session. A password cannot contain a question mark (?).
Disable Password
Disables password-based authentication for the user account. When selected, TrueNAS removes the existing password and hides the Password card. Users with disabled passwords cannot access password-based services like SMB shares or SSH password authentication. This option is not available (grayed out) when SMB Access is selected.
Public SSH Key
Only shows after selecting SSH Access. Text entry field that accepts manual or copy/paste entry of the public SSH key for any key-based authentication. Do not paste the private key in this field!
Additional Details Settings
The edit edit icon or the field shows a text entry, dropdown list, or other setting fields.
Some settings show additional settings, for example, the Group, Home Directory, and Sudo Commands.
Specifies the full name (first and last) for the user.
Email
Specifies the email address of the new user. This email address receives notifications, alerts, and messages based on configured settings.
Groups
Sets the group membership for the user. Shows the Create New Primary Group pre-selected by default, and Auxiliary Groups settings after clicking the edit icon. Shows Create New Primary Group with the same name entered in Username. Disabling Create New Primary Group shows the Primary Group dropdown list with group options.
Create New Primary Group
Sets TrueNAS to automatically create a new primary group for the user named the same as the username. Selected by default. Shows after clicking in the Group field. Disabling shows the Primary Group setting.
Primary Group
Sets the name of the primary group for the user from the options on the dropdown list. Shows after clicking in the Group field and disabling Create New Primary Group.
Auxiliary Groups
Sets membership in the selected auxiliary group. Shows after clicking in the Groups field. For example, to add built-in administrator or truenas_readonly_administrator group privileges.
UID
Shows the default Next Available. Shows a text entry field that accepts manual entry of a new number for the user ID after clicking edit. Enter a number greater than 1000 for user accounts. System accounts use an ID equal to the default port number used by the service.
Home Directory
Sets the home directory for the user. Shows the default New directory under /var/empty when not configured. Shows Create Home Directory preselected by default, and the Create Home Directory Under mount path and file browser fields show after clicking edit. D
Default Permissions is preselected by default. It Disabling Default Permissions shows the .
Shell
Select the shell for local and SSH logins from the dropdown list. Options are bashdash, rbash, sh, tmux, TrueNAS CLI, TrueNAS Console, and zsh.
Create Home Directory
Sets the mount path for the home directory for the selected user. Selected by default. Disabling hides the Default Permissions option, and Create Home Directory changes the mount path and browser fields to Home Directory.
Home Directory
Sets the mount path to the location for the home directory. Shows a pair of fields: a blank mount path field and a file browser directly under the blank field. The blank field allows typing the mount path or using the file browser to set the mount path. The file browser allows creating a new dataset after clicking on an existing dataset. If the directory exists and matches the value in Username, it is set as the home directory for the user. When the path does not end with a subdirectory matching the username, a new subdirectory is created if the Create Home Directory option is selected.
Default Permissions
sets the home directory ACL permissions to 700 or owner - all, others-none. Enabled by default. Disable to show the Home Directory Permissions permission options.
Home Directory Permissions
Sets custom home directory permissions using the Read/Write/Execute and User/Group/Other checkboxes.
Sudo Commands
Shows options for entering sudo commands. Options are:
Allowed Sudo Commands, Allow all sudo commands, Allowed sudo commands with no password, and Allow all sudo commands with no password.
Allowed Sudo Commands
Limits this user to the specific sudo commands entered in the field. Enter allowed commands as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands, and prompts the user for their account password.
Allow all sudo commands
Grants the user permission to use all sudo commands, but prompts the user to enter their password.
Allowed sudo commands with no password
Limits the sudo commands the user can enter without seeing a prompt to enter their password. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands. Exercise caution when allowing sudo commands without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks.
Allow all sudo commands with no password
Gives this user administrator permissions and the ability to use all sudo commands without seeing a prompt to enter their password. This is not recommended!
Shell Options
You can set a specific shell for the user from the Shell dropdown list options.
Shell
Description
nologin
Use when creating a system account or creating a user account that can authenticate with shares, but cannot log in to the TrueNAS system using SSH. In rare cases, where a TrueNAS 13.0 user has /etc/netcli set as the user shell, and then after migrating to TrueNAS 24.04 or later, the user shell changes to /user/sbin/nologin as the default.
Opens Shell in the CLI. Eliminates the need to enter cli at the Shell system prompt to enter the TrueNAS CLI. Enter ls to see the list of namespaces.
TrueNAS Console
Opens Shell in the Console Setup menu. Eliminates the need to enter menu. This option provides the user access to the Linux and TrueNAS CLI shells.
Groups Screens
Groups Screen
The Credentials > Groups screen displays a list of groups configured on the screen. By default, built-in groups are hidden until you make them visible.
When enabled, the Show Built-In Groups toggle turns blue and shows built-in groups. When disabled, the toggle turns grey and shows only non-built-in groups.
The Credentials > Groups screen displays the No groups screen if no groups other than built-in groups are configured on the system.
Use Members to manage membership and Edit or Delete to manage the group.
Add and Edit Group Screens
The Add Group and Edit Group screens show the same settings but the GID is not editable after saving changes on the Add Group screen.
Add opens the Add Group configuration screen.
The Edit icon opens the Edit Group screen.
(Required) Assigns the entered unique number as the group ID (GID) TrueNAS uses to identify a Unix group. Enter a number above 1000 for a group with user accounts. If a system service uses the group, the group ID must match the default port number for the service. Shows the group ID assigned at the time the group is created on the Edit Group screen but cannot be changed.
Name
(Required) Assigns the entered name to the group. A group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?), greater or less than (<) (>), equal (=). You can only use the dollar sign ($) as the last character in a group name. Group names must also align with the Portable Filename Character Set defined by The Open Group.
Privileges
Attaches a role privilege to the group as assigned and configured on the Add or Edit Privileges screens. Using custom administrator roles aside from the defaults is an experimental feature and is not supported. Do not modify the local administrator or default admin user privileges! Only use if you need users in this group to access limited areas of the TrueNAS UI or authentication for TrueNAS API calls.
Allowed sudo commands
Permits the group members to enter the specific sudo commands in this field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Using sudo prompts the user for their account password.
Allow all sudo commands
Enable to give group members permission to use all sudo commands. Using sudo prompts the user for their account password.
Allowed sudo commands with no password
Permits group memebers to enter the specific allowed sudo commands entered in this field without requiring the user to enter their password. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Exercise caution when allowing sudo commands without password prompts. Recommended to limit the privilege to trusted users and specific commands to minimize security risks.
Allow all sudo commands with no password
Not recommended. Enable to give group members the ability to enter all sudo commands without needing to enter a password. Does not require specifying allowed commands.
SMB Group
Select to make the group available for permissions editors over SMB protocol (and the share ACL editor). Not used for SMB authentication or determining the user session token or internal permissions checks.
Update Members Screen
The Update Members screen manages group permissions and access for large numbers of user accounts.
The right arrow adds a user account to the group after selecting the user.
The left arrow removes the selected user account from the group.
Hold Ctrl while clicking each entry to select multiple groups.
Privileges Screen
The Privileges feature in releases earlier than 24.10 is experimental, but as of 24.10 onwards is no longer experimental.
Do not edit the existing predefined administrator roles (Full Control Admin, Readonly Admin, and Sharing Admin)!
Editing an unrestricted administrator account privilege can result in lost access to the system!
The Privileges screen shows pre-defined and user-configured roles defined on the system.
The Privileges screens show the default administrator groups and roles and define customized groupings of roles for different local or directory service-imported account groups.
The new and edit privilege screens show the same settings but not all settings are editable.
TrueNAS Enterprise
Enterprise-licensed systems can enable Active Directory to provision groups in TrueNAS. To make this possible, join Active Directory, then go to System > Advanced Settings > Access and enable the Allow Directory Service users to access WebUI option.
After enabling this, the Edit Privilege screen lists AD groups on the Groups dropdown list.
See Allowing Directory Service Users to Access the UI for more information.
Add opens the New Privilege screen.
The Edit icon opens the Edit Privilege screen for the selected privilege.
Setting
Description
Name
Assigns the name entered to a new privilege. Names can include the dash (-) or underscore(_) special characters, and upper and lowercase alphanumeric characters. Enter a descriptive name for the privilege. Name shows on the Edit Privilege screen but is not editable.
Groups
Shows a list of groups configured on the system. Select a group from the dropdown list after clicking in the field. The privilege is applied to the selected group(s).
Roles
Select from a dropdown list of all available roles available to assign to the new privilege or change an existing privilege. Only the Readonly Admin, Sharing Admin, or Full Admin roles are supported in the web UI.
Web Shell Access
Select to allow a user to assign the new privilege access to the System > Shell screen.
Assigned administrator roles show on the Users Screen.
Directory Services Screens
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
The Directory Services screen configuration options set up access to directory servers through domain and account settings, and can set up ID mapping or Kerberos authentication and authorization services.
The screen shows the status of directory services when a service is not configured or when it is configured but disabled.
The main option displays:
Configure Directory Services opens the Directory Services Configuration form where you can set up Active Directory, IPA, or LDAP connections.
Advanced Settings opens a warning dialog before showing configuration options for Kerberos.
After configuring Active Directory, IPA, or LDAP, the Directory Services screen includes the widget for the configured service, and adds the Show button to the right of Advanced Settings. Show opens the warning dialog stating incorrectly configuring advanced settings is dangerous.
Advanced Settings shows a warning dialog stating incorrectly configuring advanced settings is dangerous.
Continue closes the dialog and shows the Kerberos Settings, Kerberos Realms, and Kerberos Keytabs configuration widgets.
Active Directory Screens: Provides information on the **Active Directory** configuration screens and settings.
IPA Screens: Provides information on the IPA screen and widget settings.
LDAP Screens: Provides information on the **LDAP** screen and widget settings.
Kerberos Settings Screen: Provides information on the **Kerberos Settings** widget and configuration screen settings.
Kerberos Realms Screens: Provides information on the **Kerberos Realms** widget and configuration screen settings.
Kerberos Keytab Screens: Provides information on the **Kerberos Keytabs** screen and widget settings.
Active Directory Screens
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
Configuring Active Directory
The Active Directory directory service configuration screen shows after selecting Active Directory in the Configuration Type dropdown list in the Directory Services Configuration screen.
The Active Directory widget displays after configuring TrueNAS to access your Active Directory domain controller.
The widget shows Status, Domain Name, and Domain Account Name.
Settings opens the Active Directory configuration screen.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or if there are fewer users than expected available in the permissions editors.
Leave Domain removes the TrueNAS system from the Active Directory server.
Directory Services Active Directory Configuration Screen
The Directory Services Configuration screen organizes settings into multiple sections: Basic Configuration, Credential Configuration, Active Directory Configuration, Trusted Domains Configuration, and IDMAP Configuration.
The Directory Services Configuration screen is used to configure one of three directory services: Active Directory, IPA, or LDAP. The configuration sections and settings change based on the Configuration Type selected.
Active Directory Basic Configuration Section
The Basic Configuration section settings control core Active Directory service settings.
Sets the type of directory service. Active Directory shows Active Directory domain integration settings.
Enable Service
Activates the Active Directory configuration. Enabled by default. Clear to disable the configuration without deleting it. Re-enable it later without reconfiguring it. The Directory Services screen returns to the default and provides the options to configure AD, LDAP, or IPA.
Enable Account Cache
Caches user and group information. Caching makes directory users and groups available in UI dropdown menus. Enabled by default.
Enable DNS Updates
Allows the directory service to update DNS records. Enabled by default.
Timeout (seconds)
The number of seconds before the directory service connection times out. Valid range is 1-40 seconds.
Kerberos Realm
Defines the Kerberos realm for authentication. This field auto-populates after joining the Active Directory domain.
Active Directory Credential Configuration Section
The Credential Configuration section settings define authentication methods for Active Directory access.
(Required) The hostname for the TrueNAS system. This value must match the Hostname setting on the Network > Global Configuration screen and cannot exceed 15 characters. Cannot contain: `\ / : * ? " < >
Domain Name
(Required) The Active Directory domain name (for example, example.com) or child domain (for example, sales.example.com) if configuring access to a child domain.
Site Name
The relative distinguished name (RDN) of the site object in the AD server. TrueNAS automatically detects this from the Active Directory server.
Computer Account OU
The organizational unit (OU) where the TrueNAS computer object is created when joining the Active Directory domain for the first time. The OU string includes the distinguished name (DN) of the Computer Account OU. For example, OU=Computers,DC=example,DC=com.
Use Default Domain
Removes the domain name prefix from AD users and groups. This setting may be required for specific configurations such as Kerberos authentication with NFS for AD users. Note that using this setting can cause collisions with local user account names.
Trusted Domains Configuration Section
The Trusted Domains Configuration section controls access for trusted domains.
Trusted Domains Configuration Settings
Setting
Description
Enable Trusted Domains
Allows clients to access TrueNAS if they are members of domains with a trust relationship. Starting in TrueNAS 25.10, trusted domains are configured as part of the Active Directory configuration rather than as separate IDmap entries. When enabled, additional trusted domain configuration options appear. Each trusted domain requires an IDMAP Backend selection.
IDMAP Configuration Section
The IDMAP Configuration section controls identity mapping settings.
IDMAP (Identity Mapping) ensures that UIDs and GIDs assigned to Active Directory users and groups have consistent values domain-wide. By default, TrueNAS uses an algorithmic method based on the RID component of the user or group SID, which is suitable for most environments. Only administrators experienced with configuring ID mapping should customize IDMAP settings.
IDMAP Configuration Settings
Setting
Description
Use TrueNAS Server IDMAP Defaults
Uses default IDMAP configuration. Enabled by default and recommended for most setups. Clear to reveal additional configuration options: Builtin section with optional Name field and required Range Low and Range High fields, and IDMAP Domain section with required IDMAP Backend, Name, Range Low, and Range High fields.
IDMAP Backend
Sets the backend plugin interface for Winbind to store SID in UID/GID mapping tables. Options include AD, AUTORID, LDAP, NSS, RFC2307, RID, and TDB.
Range Low
The lowest UID/GID number the IDMAP backend translates. Works with Range High to establish the range.
Range High
The highest UID/GID number the IDMAP backend translates. Works with Range Low to establish the range.
IPA Screens
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Configuring IPA
The IPA directory service configuration screen shows after selecting IPA in the Configuration Type dropdown list in the Directory Services Configuration screen.
For detailed configuration instructions, see Configuring IPA.
IPA Widget
The IPA widget displays after configuring settings for an IPA directory server.
The widget shows the Status of the directory server, and the Target Server, Domain, and Base DN.
Settings opens the IPA configuration screen.
Directory Services IPA Configuration Screen
The Directory Services Configuration screen organizes settings into multiple sections: Basic Configuration, Credential Configuration, IPA Configuration, and SMB Domain Configuration.
The Directory Services Configuration screen is used to configure one of three directory services: IPA, LDAP, or an Active Directory. The configuration sections and settings change based on the Configuration Type selected.
IPA Basic Configuration Section
The Basic Configuration section settings control core IPA service settings.
Sets the type of directory service. IPA shows Identity, Policy, and Audit directory service integration settings.
Enable Service
Activates the IPA configuration. Enabled by default. Clear to disable the configuration without deleting it. Re-enable it later without reconfiguring it. The Directory Services screen returns to the default and provides the options to configure AD, LDAP, or IPA.
Enable Account Cache
Caches user and group information. Caching makes directory users and groups available in UI dropdown menus. Enabled by default.
Enable DNS Updates
Allows the directory service to update DNS records. Enabled by default.
Timeout (seconds)
The number of seconds before the directory service connection times out. Valid range is 1-40 seconds.
Kerberos Realm
Defines the Kerberos realm for authentication (usually the uppercase version of the domain name, e.g., EXAMPLE.COM). This field auto-populates when selecting Active Directory domain.
IPA Credential Configuration Section
The Credential Configuration section settings define authentication methods for IPA access.
Credential Type (Required) Sets the appropriate credential type for IPA authentication to the option selected on the dropdown list. Options include Kerberos User and Kerberos Principal.
IPA Configuration Section
The settings on the IPA Configuration section settings define the connection parameters and validation options.
(Required) Enter the IPA server host name or IP address.
TrueNAS Hostname
(Required) Enter the host name for this TrueNAS system.
Domain
(Required) Enter the domain name.
Base DN
(Required) Sets the base distinguished name for the IPA directory. For example: dc=example,dc=com.
Validate Certificates
Verifies certificate authenticity when connecting to the IPA server. TrueNAS validates the full certificate chain when this option is enabled. TrueNAS does not support non-CA certificates when certificate validation is required.
SMB Domain Configuration Section
The SMB Domain Configuration section controls SMB integration settings.
Uses default SMB domain settings when enabled, shows the additional Name, Domain Name, Range Low, Range High, and Domain SID settings when disabled. IPA includes integrated Samba support and can provide user and group information for SMB authentication.
LDAP Screens
Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel).
Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.
Configuring LDAP
The LDAP directory service configuration screen shows after selecting LDAP in the Configuration Type dropdown list in the Directory Services Configuration screen.
The LDAP widget displays after configuring TrueNAS settings for your LDAP instance.
The widget includes Status, and the Hostname, Base DN, and Bind DN configured.
Settings opens the Directory Services Configuration screen where you can modify your LDAP settings.
Clear Config removes the LDAP directory service configuration. A confirmation dialog appears before clearing the configuration.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or there are fewer users than expected available in the permissions editors.
Directory Services LDAP Configuration Screen
The Directory Services Configuration screen organizes settings into multiple sections: Basic Configuration, Credential Configuration, and LDAP Configuration (with subsections for Auxiliary Parameters, Search Bases, and Attribute Maps).
The Directory Services Configuration screen is used to configure one of three directory services: Active Directory, IPA, or LDAP. The configuration sections and settings change based on the Configuration Type selected.
The screen includes a Clear Config button that removes the entire directory service configuration after confirmation. See Removing LDAP from TrueNAS for details.
LDAP Basic Configuration Section
The Basic Configuration section settings control core LDAP service settings.
Sets the type of directory service. LDAP shows LDAP directory service integration settings.
Enable Service
Activates the LDAP configuration. Enabled by default. Clear to disable the configuration without deleting it. Re-enable it later without reconfiguring it. The Directory Services screen returns to the default and provides the options to configure AD, LDAP, or IPA.
Enable Account Cache
Caches user and group information. Caching makes directory users and groups available in UI dropdown menus. Enabled by default.
Enable DNS Updates
Allows the directory service to update DNS records. Enabled by default.
Timeout (seconds)
The number of seconds before the directory service connection times out. Valid range is 1-40 seconds.
Kerberos Realm
Defines the Kerberos realm for authentication (usually the uppercase version of the domain name, for example, EXAMPLE.COM).
LDAP Credential Configuration Section
The Credential Configuration section settings define authentication methods for LDAP access.
Credential Configuration Settings
Setting
Description
Credential Type
(Required) Sets the credential type for LDAP authentication. Options include LDAP Anonymous, LDAP Plain, LDAP MTLS, Kerberos Principal, and Kerberos User.
Bind DN
The administrative account name for the LDAP server. Displays when LDAP Plain is selected. For example, cn=Manager,dc=test,dc=org.
Bind Password
The password for the Bind DN. Displays when LDAP Plain is selected.
Client Certificate
The certificate to use for LDAP MTLS authentication. Displays when LDAP MTLS is selected.
Kerberos Principal
The location of the principal in the keytab. Displays when Kerberos Principal is selected.
Username
The LDAP administrative account username. Displays when Kerberos User is selected.
Password
The password for the administrative account. Displays when Kerberos User is selected.
LDAP Configuration Section
The LDAP Configuration section settings define the connection parameters and validation options.
(Required) The LDAP server URLs. Separate multiple entries by pressing Enter. Multiple URLs create an LDAP failover priority list. If a host does not respond, TrueNAS tries the next host until it establishes a connection. If using a cloud service LDAP server, do not include the full URL.
Base DN
(Required) The top level of the LDAP directory tree to use when searching for resources. For example, dc=test,dc=org.
Start TLS
Encrypts the LDAP connection with STARTTLS on the default LDAP port 389.
Validate Certificates
Verifies certificate authenticity when connecting to the LDAP server.
Schema
(Required) The LDAP NSS schema. Options are RFC2307 or RFC2307BIS.
Auxiliary Parameters Subsection
The Auxiliary Parameters subsection allows customization of auxiliary parameters.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Auxiliary Parameters Settings
Setting
Description
Use Standard Auxiliary Parameters
Uses default auxiliary parameters. Enabled by default. Clear to reveal the Auxiliary Parameters text field for custom options for nslcd.conf.
Search Bases Subsection
The Search Bases subsection allows customization of search base DNs.
Search Bases Settings
Setting
Description
Use Standard Search Bases
Uses default search bases. Enabled by default. Clear to reveal User Base DN, Group Base DN, and Netgroup Base DN fields for custom search base configuration.
Attribute Maps Subsection
The Attribute Maps subsection allows customization of attribute mappings.
Attribute Maps Settings
Setting
Description
Use Standard Attribute Maps
Uses default attribute mappings. Enabled by default. Clear to reveal four subsections for customization: LDAP Password Attributes, LDAP Shadow Attributes, LDAP Group Attributes, and LDAP Net Group Attributes.
Kerberos Settings Screen
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD.
You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Settings Widget
The Kerberos Settings widget in the Advanced Settings on the Directory Services screen displays current settings.
Settings opens the Kerberos Settings configuration screen.
Kerberos Settings Screen
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
The Kerberos Settings configuration screen is available for advanced Kerberos configuration.
Advanced Kerberos auxiliary parameter configuration options are removed in TrueNAS 25.10. Kerberos settings are now managed through the unified directory services configuration.
Setting
Description
Appdefaults Auxiliary Parameters
Additional Kerberos application settings. See the appdefaults section of krb.conf(5) for available settings and usage syntax.
Libdefaults Auxiliary Parameters
Additional Kerberos library settings. See the libdefaults section of krb.conf(5) for available settings and usage syntax.
Kerberos Realms Screens
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD.
You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Realm Widget
The Kerberos Realms widget in the Advanced Settings on the Directory Services screen displays currently configured realms.
Add opens the Add Kerberos Realm configuration screen.
Click on any instance to open the Edit Kerberos Realm screen.
Click on the Kerberos Realms widget header to open the Kerberos Realms screen.
Kerberos Realms Screen
The Kerberos Settings configuration screen is available for advanced Kerberos configuration.
Actions includes the option to Add a new realm. Add opens the Add Kerberos Realm screen.
The edit button opens the Edit Kerberos Realm screen for the selected realm. The delete button opens a delete confirmation dialog for the Kerberos realm.
Add and Edit Kerberos Realm Screens
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Setting
Description
Realm
(Required) Enter the name of the realm as a domain name, For example, example.com. AD configured TrueNAS systems pre-populate this field with the required information.
KDC
Enter the name of the Key Distribution Center (KDC). The KDC acts as the third-party authentication service for Kerberos. If left blank, TrueNAS uses DNS discovery to locate the KDC. Separate multiple values by pressing Enter. For example, kdc1.example.com press Enter then kdc2.example.com.
Primary KDC
Specifies the primary Key Distribution Center (KDC) for the realm. The Kerberos client uses this KDC when acquiring credentials if the current KDC fails with a bad password error. This is valuable for domains with hub-and-spoke topology where password changes slowly propagate from the hub to the spoke.
Admin Server
Define the server that performs all database changes. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
Password Server
Define the server that performs all password changes. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
Kerberos Keytab Screens
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD.
You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Keytab Widget
The Kerberos Keytab widget in the Advanced Settings on the Directory Services screen displays added keytabs.
Add opens the Add Kerberos Keytab configuration screen.
Sync synchronizes Kerberos keytabs with Active Directory. This button only appears when the system is joined to Active Directory. Click Sync to open the synchronization confirmation dialog.
Click on any keytab instance to open the Edit Kerberos Keytab screen.
The Kerberos Keytab widget header opens the Kerberos Keytabs screen.
Kerberos Keytab Screen
The Kerberos Keytabs screen displays a list view of keytabs configured on your TrueNAS system.
Actions includes options to Add a new keytab or Sync keytabs with Active Directory:
Add opens the Add Kerberos Keytab screen.
Sync synchronizes Kerberos keytabs with Active Directory. This button only appears when the system is joined to Active Directory. Click Sync to open the synchronization confirmation dialog.
The more_vert button opens the actions options for the selected keytab. Options are Edit which opens the Edit Kerberos Keytab screen for the selected keytab, and Delete that opens a delete confirmation dialog.
Add and Edit Kerberos Keytab Screens
The settings found on the Add Kerberos Keytab and Edit Kerberos Keytab screens are the same.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Setting
Description
Name
Enter a name for this Keytab. If configured, TrueNAS populates this field with what it detects in Active Directory.
Kerberos Keytab
Browse to the keytab file to upload.
Backup Credentials
TrueNAS stores cloud backup services credentials, SSH connections, and SSH key pairs configured using the widgets on the Backup Credentials screen.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
The Cloud Credentials configuration screen opens pre-populated with Storj-iX as the provider.
It shows settings to add or edit cloud credentials TrueNAS uses to integrate with cloud storage providers.
Provider shows a list of available providers.
Select the name of a cloud provider to populate the configuration screen with credential settings for that provider.
Verify Credentials uses the credentials entered to verify access to the cloud storage provider account.
Name and Provider Settings
The selection in Provider changes the Authentication settings.
Setting
Description
Provider
(Required) Default is set to Storj. Select the cloud storage provider from the options on the dropdown list.
Name
Enter a name for this cloud credential. For example, cloud1 or amazon1.
Storj iX Credential
Storj authentication includes going to the Storj iX sign-in screen to either create a new Storj iX account or log into an existing Storj iX account.
After configuring the Storj account in the Storj-iX portal, return to TrueNAS to enter the S3 credentials provided by Storj.
Enter the alphanumeric key that is between 5 and 20 characters for the Amazon Web Services Key ID. Find this on Amazon AWS by going through My account > Security Credentials > Access Keys (Access Key ID and Secret Access Key).
Secret Access Key
Enter the alphanumeric key that is between 8 and 40 characters for the Amazon Web Services password. If you cannot find the Secret Access Key, go to My Account > Security Credentials > Access Keys and create a new key pair.
Amazon S3 Advanced Authentication Options
This section provides information on Amazon S3 advanced authentication settings for endpoints. The basic authentication settings are required when using the advanced settings.
Enter a value to define the maximum number of chunks for a multipart upload. Setting a maximum is necessary if a service does not support the 10,000 chunk AWS S3 specification.
Endpoint URL
(Optional) When using AWS, you can leave the endpoint field empty to use the default endpoint for the region and automatically fetch available buckets, or enter an S3 API endpoint URL. Refer to the AWS Documentation for a list of Simple Storage Service Website Endpoints.
Region
(Optional) Enter an AWS resources in a geographic area. Leave empty to detect the correct public region for the bucket. Entering a private region name allows interacting with Amazon buckets created in that region. For example, enter us-gov-east-1 to discover buckets created in the eastern AWS GovCloud region.
Disable Endpoint Region
Select to prevent automatic detection of the bucket region. Select only if your AWS provider does not support regions.
Use Signature Version 2
Select to force using Signature Version 2 to sign API requests. Select only if your AWS provider does not support default version 4 signatures.
BackBlaze B2 Credential
This section provides information on the BackBlaze B2 authentication settings.
Enter or copy and paste the alphanumeric Backblaze B2 Application Key ID string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.
Application Key
Enter or copy and paste the alphanumeric Backblaze B2 Application Key string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.
OAuth and Access Token Authentication Credentials
Several cloud storage providers use OAuth authentication and a required access token to authenticate the cloud storage account.
Providers using these methods are Box, Dropbox, Google Photos, pCloud, and Yandex.
Use Login to Provider to enter the account username and password.
Setting
Description
OAuth Client ID
Enter the public identifier for the cloud application.
OAuth Client Secret
Enter the secret phrase known only to the cloud application and the authorization server.
Token
Enter a User Access Token for Box. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
Hostname
(Optional) pCloud only. Enter the host name to connect to.
FTP and SFTP Credentials
FTP and SFTP cloud storage providers use host name, port, and user credentials to authenticate accounts. SMTP uses SSH hosts, port, and user credentials and also uses a private key.
Enter the FTP host name, or for SFTP, the SSH host name to connect. For example, ftp.example.com.
Port
Enter the FTP or for SFTPP, the SSH port number. Leave blank to use the default port 21 for FTP or 22 for SFTP.
Username
Enter a username on the FTP or for the SFTP host system, the SSJ user name. This user must already exist on the host.
Password
Enter the password for the user account.
Private Key ID
(SFTP only) Import the private key from an existing SSH keypair or, if no keypairs exist on the system, select Add on the SSH Keypairs widget to open the SSH Keypairs screen. Enter a name, and then click Generate New to create a new SSH key for this credential.
Use Choose File to browse to the file location on the server. Opens a file browser to select the Google service account key credential file generated by the Google Cloud Platform Console to authenticate the account.
Preview JSON Service Account Key
Shows the JSON file downloaded to the system server from Google Cloud Storage and uploaded with Choose File.
Google Drive Credential
Google Drive also uses OAuth authentication, a required access token, and a team drive ID to authenticate accounts.
Google Drive adds one additional authentication setting to the general OAuth settings.
Use Login to Provider to enter the account username and password.
Setting
Description
OAuth Client ID
Enter the public identifier for the cloud application.
OAuth Client Secret
Enter the secret phrase known only to the cloud application and the authorization server.
Access Token
(Required) Token created with Google Drive. Access Tokens expire periodically, so you must refresh them.
Team Drive ID
(Optional) Google Drive only when connecting to a team drive, and is the top-level folder ID for the team drive.
HTTP Credential
HTTP uses an HTTP host URL to authenticate account credentials.
It is a read-only client that supports directory listings from popular web servers like Apache and Nginx.
Hubic Credential
Hubic uses an access token to authenticate the account.
Enter the token generated by a Hubic account into the Access Token field.
Microsoft Azure Blob Storage Credential
Microsoft Azure Blob Storage uses the Microsoft Azure account name and account key to authenticate the account credentials.
Enter an endpoint. For example, blob.core.usgovcloudapi.net.
OpenStack Swift Credential
OpenStack Swift uses several required settings to authenticate credential accounts.
The AuthVersion setting selection changes setting options displayed in Advanced Options.
(Required) Enter the Openstack API key or password. This is the OS_PASSWORD from an OpenStack credentials file.
Authentication URL
(Required) Enter the authentication URL for the server. This is the OS_AUTH_URL from an OpenStack credentials file.
AuthVersion
Authentication version set to default. Click on field to specify different authentication version (rclone documentation).
OpenStack Authentication Advanced Options
The Authentication Advanced Options screen shows different options based on the AuthVersion setting.
Auto(vX), v1, and v2 use the same advanced authentication settings.
(Optional for v1 auth) Enter the tenant ID Enter the tenant ID. For more information, see rclone documentation.
Auth Token
(Optional) Enter the auth token from alternate authentication. For more information, see rclone documentation.
Region Name
(Optional) Enter the region name. For more information, see rclone documentation.
Storage URL
(Optional) Enter the storage URL. For more information, see rclone documentation.
Endpoint Type
Select service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended. For more information, see rclone documentation.
V3 Authentication Settings
Setting AuthVersion to v3 shows additional authentication settings.
(Required) Enter the URL of the HTTP host to connect to.
WebDAV Service
(Required) Select the name of the WebDAV site, service, or software used from the dropdown list. Options are NEXTCLOUD, OWNCLOUD, SHAREPOINT, or OTHER.
Username
(Required) Enter the WebDAV account user name.
Password
(Required) Enter the WebDAV account password.
Microsoft OneDrive Credential
Microsoft OneDrive uses several required settings to authenticate credential accounts.
(Required) Enter the OneDrive access token found in your Microsoft account.
Drives List
Enter the drives and IDs registered to your Microsoft account. Entering a value in this field also fills out the Drive ID field.
Drive Account Type
(Required) Select the type of OneDrive account you are authorizing. This is automatically selected when you log in to your Microsoft account.
Drive ID
Enter a unique drive identifier or keep the auto-filled entry that appeared when you filled out the Drives List field above.
SSH Screens
The Backup Credentials screen displays the SSH Connections and SSH Keypairs widgets.
These widgets are used to manage SSH credentials specifically for automated tasks such as replication, backups, cloud sync, or other system-to-system operations. You can generate, store, and manage SSH key pairs and define SSH connections that TrueNAS uses for these automated processes. The key pairs managed here are not tied to individual user logins, but are instead used by the system for secure communication with other systems or services.
For individual user SSH access, configure SSH keys in the user account settings under Credentials > Users.
You must also configure and activate the SSH Service to allow SSH access.
SSH Connection and Keypairs Widgets
The SSH Connections and SSH Keypairs widgets display a list of SSH connections and key pairs configured on the system.
The SSH Connections widget allows users to establish Secure Socket Shell (SSH) connections.
The SSH Keypairs widget allows users to generate SSH key pairs required to authenticate the identity of a user or process that wants to access the system using SSH protocol.
Add in the SSH Connections widget opens the SSH Connections configuration window.
The connection name on the widget is a link that opens the SSH Connections configuration screen already populated with the saved settings for the selected connection.
The more_vert icon shows options to Edit or Delete the connection. Delete opens a dialog with an option to delete the associated SSH Keypair.
SSH Connections Screens
The settings on the SSH Connections configuration screens are the same whether you add a new connection or edit an existing connection.
(Required) Enter a unique name for this SSH connection. For example, use ssh and a server name or number like sshsys1 or sshtn121 where sys1 or tn121 are server designations.
Setup Method
Select the setup method to use from the dropdown list of options. Options are:
Semi-automatic (TrueNAS only) - Select to simplify setting up an SSH connection with another TrueNAS or FreeNAS system without logging into that system to transfer SSH keys. The default is set to Semi-automatic (TrueNAS only).
Manual - Select to enter all settings when setting up an SSH connection with a non-TrueNAS server. Displays other setting options required to manually configure an SSH connection. Requires copying a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.
Authentication - Semi-Automatic Method Settings
These authentication settings show when Setup Method is Semi-automatic (TrueNAS only).
(Required) Enter the host name or IP address of the remote system. Use a valid URL scheme for the remote TrueNAS URL. IP address example of https://10.231.3.76.
Admin Username
Enter the user name for logging into the remote system. The default is set to root but change this to the name of the system administrator for the remote system for this connection.
Admin Password
(Required) Enter the administrator user account password for logging into the remote system.
One-Time Password (if necessary)
One-time password if two-factor authentication is enabled.
Username
(Required) Username on the remote system used to log in via SSH.
Private Key
(Required) Select a saved SSH key pair, import the private key from a previously created SSH key pair, or select Generate New to create a new key pair to use for the connection to this remote system.
Authentication - Manual Method Settings
These authentication settings show when Setup Method is Manual. You must copy a public encryption key from the local system to the remote system.
A manual setup allows a secure connection without a password prompt.
(Required) Enter the host name or IP address of the remote system. A valid URL scheme is required. An IP address example is https://10.231.3.76.
Port
(Required) Enter the port number on the remote system to use for the SSH connection.
Username
(Required) Enter the user name for logging into the remote system.
Private Key
(Required) Select a saved SSH key pair or select Generate New to create a new key pair to use for the connection to this remote system.
Remote Host Key
Enter the remote system SSH key for this system to authenticate the connection. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate this field.
Discover Remote Host Key
Click to connect to the remote system and attempt to copy the key string to the related TrueNAS field.
The name of the key pair listed on the widget is a link that opens the SSH Keypairs configuration screen.
The more_vert icon shows a dropdown list of options: Download, Edit, and Delete. Download saves the public and private key strings as text files for later use. Edit opens the SSH keypair configuration screen. Delete opens the delete dialog. If the keypair is used by SSH Connections, deleting it also deletes those connections. Click Confirm and then Delete to remove the stored key pairs from the system.
SSH Keypairs Screen
The SSH Keypairs configuration screen displays the same settings for both add and edit options. Click Add to open a new configuration form, or click on an existing key pair to open the configuration screen populated with the settings for the selected key pair.
Required. Enter a unique name for this SSH key pair. Automatically generated key pairs are named after the object that generated the key pair with key appended to the name.
Generate Keypair
Click to have TrueNAS automatically generate a new key pair and populate the Private Key and Public Keys fields with these values.
Save adds the key pair to the widget and activates the more_vert with options to Download Private Key and Download Public key.
Certificates
The Certificates screen displays widgets for Certificates, Certificate Signing Requests (CSRs), and ACME DNS-Authenticators that each provice access to all the information for certificates, certificate signing requests (CSRs), and ACME DNS-authenticators respectively.
Each TrueNAS comes with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
Contents
Certificates Screens: Provides information on the Certificates screens and settings.
The more_vert icon for a listed certificate shows a dropdown list of options to download, edit, or delete an existing certificate.
Each TrueNAS has an internal certificate that enables encrypted access to the web interface.
downloadDownload downloads the certificate to the system. In Windows, this is the Downloads folder.
(Required) Descriptive identifier for this certificate. Accepts manual or copy/paste entry of a name.
Add To Trusted Store
Adds the imported certificate to the trusted store in TrueNAS.
Certificate
(Required) Field to paste the certificate for the certificate you are importing.
Private Key
(Required) Paste the private key associated with the certificate you are importing. Provide a key at least 1024 bits long.
Passphrase
(Required) Text entry field that accepts manual or copy/paste of a password associated with the private key for the certificate you are importing.
Confirm Passphrase
(Required) Text entry field where you can manually re-enter or copy/paste the passphrase entered in Passphrase.
Edit Certificate Screen
The Edit Certificate screen shows the current certificate identifier (name), subject information for the certificate, the view/download certificate and key options, and allows you to add the certificate to the TrueNAS trusted store.
The Subject area of the Edit Certificate screen shows information about the certificate.
Setting
Description
Common
Shows the common name for the certificate. A name can include the underscore (_) or dash (-) special characters. The default value for the truenas_default certificate is localhost.
SAN
Shows the subject alternative name (SAN) name for the certificate. The default value for the truenas_default certificate is DNS:localhost.
Distinguished Name
Shows the full directory service distinguished name for the certificate. This includes the country, organization, common name, email address, state, locality, and SAN properties.
Country
Shows the country where the certificate is issued. The default value for the truenas_default certificate is US.
State
Shows the organization for the certificate. The default value for the truenas_default certificate is iXsystems.
City
Shows the city where the certificate organization is located. The default value for the truenas_default certificate is Maryville
Organization
Shows the country where the certificate is issued. The default value for the truenas_default certificate is US
Organizational Unit
Shows the department in the organization for the certificate. No default value for the truenas_default certificate is specified.
Email
Shows the email address associated with the certificate. The default value for the truenas_default certificate is info@ixsystems.com.
Type
Shows the type of certificate. The default value for the truenas_default certificate is Certificate.
Path
Shows the path to where the certificate is stored. The default value for the truenas_default certificate is /etc/certificates.
Digest Algorithm
Shows the authentication protocol for the certificates. The default value for the truenas_default certificate is SHA256S.
Key Length
Shows the number of characters in the key for the certificate. The default value for the truenas_default certificate is 2048.
Key Type
Shows the certificate key type. The default value for the truenas_default certificate is RSA.
Until
Shows the expiration date for the certificate.
Lifetime
Shows the number of days the certificate remains valid. The default value for the truenas_default certificate is 397 days.
View/Download Certificate opens a window with the certificate string.
View/Download Key opens a window with the certificate private key.
The assignment clipboard icon copies the certificate or public key to the clipboard.
Download downloads a copy of the certificate to your server. Keep the certificate in a secure area where you can back it up and save it.
Delete Certificate Dialog
The Delete Certificate dialog removes the certificate from the TrueNAS system.
Force deletes the certificate if it is in use by a feature or function in the UI. For example, an application uses it for authentication.
Delete removes the certificate.
Certificate Signing Requests Screens
The Certificate Signing Requests widget, on the Certificates screen, shows a list of certificate signing requests (CSRs) configured on the system.
CSR.
A text entry field that accepts manual or copy/paste entry of a name for the certificate. A name consists of alphanumeric characters, and can use the underscore (_), and/or dash (-) special characters.
Terms of Service
Accepts the terms of service for the given ACME server.
Renew Certificate Days
Specified the number of days to renew the certificate before it expires.
Custom ACME Server Directory URI
Enables using a custom ACME server directory URI. If the ACME Server Directory URI is set to Lets Encrypt Staging Directory, enabling this option changes the ACME Server Directory URI value to show https://acme-staging-v02.api.letsencrypt.org/directory. If the ACME Server Directory URI is set to Let’s Encrypt Production Directory, enabling this option changes the ACME Server Directory URI value changes to show https://acme-v02.api.letsencrypt.org/directory.
ACME Server Directory URI
Sets the URI of the ACME server directory. Shows two preconfigured URI options on a dropdown list: Lets Encrypt Staging Directory and Let’s Encrypt Production Directory.
Lets Encrypt Staging Directory
Let’s Encrypt Production Directory
DNS:UnitedStates
Sets the authenticator to validate the domain. Shows a dropdown list of previously configured ACME DNS authenticators.
Edit CSR Screen
The Edit CSR screen shows the current CSR settings. It allows changing the CSR name (identifier), downloading or viewing the CSR, and provides access to the Create ACME Certificate screen.
Shows the common name for the certificate. A name can include the underscore (_) or dash (-) special characters. The default value for the truenas_default certificate is localhost.
SAN
Shows the subject alternative name (SAN) of the certificate. The default value for the truenas_default certificate is DNS:localhost.
Distinguished Name
Shows the full directory service distinguished name for the certificate. This includes the country, organization, common name, email address, state, locality, and SAN properties.
Country
Shows the country where the certificate is issued. The default value for the truenas_default certificate is US.
State
Shows the organization for the certificate. The default value for the truenas_default certificate is iXsystems.
City
Shows the city where the certificate organization is located. The default value for the truenas_default certificate is Maryville
Organization
Shows the country where the certificate is issued. The default value for the truenas_default certificate is US
Organizational Unit
Shows the department in the organization for the certificate. No default value for the truenas_default certificate is specified.
Email
Shows the email address associated with the certificate. The default value for the truenas_default certificate is info@ixsystems.com.
Type
Shows the type of certificate. The default value for the truenas_default certificate is Certificate.
Path
Shows the path to where the certificate is stored. The default value for the truenas_default certificate is /etc/certificates.
Digest Algorithm
Shows the authentication protocol for the certificates. The default value for the truenas_default certificate is SHA256S.
Key Length
Shows the number of characters in the key for the certificate. The default value for the truenas_default certificate is 2048.
View/Download Certificate opens a window with the certificate string.
View/Download Key opens a window with the certificate private key.
The assignment clipboard icon copies the certificate or public key to the clipboard.
Delete Certificate Dialog
The Delete Certificate dialog removes the certificate from the TrueNAS system.
Force deletes the certificate if it is in use by a feature or function in the UI. For example, an application uses it for authentication.
Delete removes the certificate.
Add CSR Wizard Screens
Certificate signing requests (CSR) allow configuring a message the TrueNAS system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
The Add CSR wizard has five screens to configure a new certificate signing request (CSR) on TrueNAS.
The wizard screens are:
The Add CSR wizard Identifier and Type settings specify the name, type, and profile to use when creating a new CSR.
Changing the Type setting to import a CSR changes the setting options and wizard screens shown.
Text entry field that accepts manual or copy/paste entry of a descriptive identifier for this CSR.
Type
Set the type of CSR and change the settings shown in the Add CSR wizard. Options are:
Certificate Signing Request - Controls when an external CA issues (signs) the certificate. Typically used with ACME or other CAs that most popular browsers trust by default.
Import Certificate Signing Request - Imports an existing CSR onto the system. Typically used with ACME CAs. Selecting Import Certificate Signing Request removes the Profile field, and the Certificate Subject and Extra Constraints wizard screens.
Profile
Sets the predefined certificate extention to either HTTPS RSA Certificate or HTTPS ECC Certificate.
Certificate Options Screen
Certificate Options show when Type is set to Certificate Signing Request on the Identifier and Type wizard screen. The settings specify the private key type, number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.
When Type is set to Import Certificate Signing Request, the settings shown add the signing request and private key of the imported certificate and the authentication credentials for the private key.
Shows when Key Type is set to EC. Shows EC type curve options: BrainpoolP512R1, BrainpoolP384R1, BrainpoolP256R1, SECP256K1, SECP384R1, SECP521R1, and ed25519. Brainpool curves can be more secure, while SECP curves can be faster. See Elliptic Curve performance: NIST vs Brainpool for more information.
Key Length
Shows when Key Type is set to RSA. Sets the number of bits in the key used by the cryptographic algorithm. Options are: 1024, 2048 or 4096. A minimum key length of 2048 is recommended for security reasons.
Digest Algorithm
Sets the cryptographic algorithm used. The options are: SHA1, SHA224, SHA256, SHA384 and SHA512. Only change the default SHA256 if the organization requires a different algorithm.
Import Certificate Screen
The Import Certificate screen shows when Type on the Identifier and Type screen is set to Import Certificate Signing Request.
Text entry field that accepts manual or copy/paste entry of the certificate for the signing request.
Private Key
Text entry field that accepts manual or copy/paste entry of the 1024-bit private key associated with the certificate when available.
Passphrase
Text entry field that accepts manual or copy/paste entry of the passphrase for the private key.
Confirm Passphrase
Text entry field that accepts manual or copy/paste re-entry of the passphrase for the private key.
Certificate Subject Settings
The Certificate Subject settings define the geographical location, name, and email for the organization using the certificate.
Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
Sets the country where the organization is located. Accepts keyboard entry to filter the dropdown list.
State
Text entry field that sets the state or province where the organization is located.
Locality
Text entry field that sets the city where the organization is located. For example, New York.
Organization
Text entry field that accepts manual or copy/paste entry of the name of the company or organization.
Organizational Unit
Text entry field that accepts manual of copy/paste entry of the organizational unit (department) name.
Email
Text entry field that accepts manual or copy/paste entry of the email address of the person responsible for the certificate.
Common Name
Text entry field that accepts manual or copy/paste entry of the fully qualified host name (FQHN) of the system. This name must be unique within a certificate chain.
Subject Alternate Names
Sets multi-domain support of additional domains to secure. Text entry field that accepts manual or copy/paste entry of additional domains to secure for multi-domain support. Separate each domain by pressing Enter. For example, if the primary domain is example.com, entering www.example.com secures both addresses.
Extra Constraints Settings
The Extra Constraints screen shows when adding a CSR. Settings on this screen are optional.
The Extra Constraints settings contain certificate extension options:
Basic Constraints limits the path length for a certificate chain.
Authority Key Identifier identifies the public key corresponding to the private key used to sign a certificate.
Key Usage defines the purpose of the public key contained in a certificate.
Extended Key Usage further refines key usage extensions.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, more settings show for that option.
Activates this extension. Identifies whether the subject of this certificate subject is a CA, and the maximum depth of valid certification paths that include this certificate.
Path Length
Shows when Basic Constraints is enabled. Text entry field that accepts manual or copy/paste entry of a number that sets the number of non-self-issued intermediate certificates that can follow this certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Value cannot be less than 0.
Basic Constraints Config
Specifies the extension type. The dropdown list options are:
CA - Select when the certificate is a certificate authority (CA)
Critical Extension - Select when the certificate is a critical extension. Clients must recognize critical extensions to prevent rejection.
Web certificates typically require you to disable CA and enable Critical Extension.
Extended Key Usage
Activates this certificate extension, and shows the Usages setting. The extended key usage extension identifies and limits valid uses for this certificate, such as client or server authentication. See RFC 3280, section 4.2.1.13 for more details.
Usages
Shows after selecting Extended Key Usage, and sets the options to identify the purpose of this public key. Typically used for the end entity certificates. You can select multiple usages. These show in the field separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CERTIFICATE_TRANSPARENCY, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_IKE, KERBEROS_PKINIT_KDC, OCSP_SIGNING, SERVER_AUTH, SMARTCARD_LOGON, or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. Using the Extended Key Usage and Key Usage extensions requires the purpose of the certificate to be consistent with both extensions. See RFC 3280, section 4.2.13 for more details.
Critical Extension
Shows after selecting Extended Key Usage. Sets the extension to critical or non-critical for the certificate. Critical extensions must be recognized by the system using the certificate, or this certificate is rejected. Extensions identified as non-critical can be ignored by the system using the certificate, and the certificate is still approved.
Key Usage
Activate this certificate extension, and shows the Key Usage Config field. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that can be used for a few operations should be restricted. For example, when an RSA key should only be used to verify signatures on objects other than public key certificates and CRLs, and the digital signature bits are asserted. Likewise, when an RSA key should only be used for key management, the key encipherment bit should be asserted. See RFC 3280, section 4.2.1.3 for more information.
Key Usage Config
Shows after selecting Extended Key Usage or Key Usage. Sets the key usage extension to valid option(s) on the dropdown list. Options are: Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. Web certificates typically need at least a digital signature and possibly key ecncipherment or key agreement, while other applications might need other usages.
Confirm Options
The Confirm Options screen shows a summary of settings for the CSR when adding a new certificate. It shows the Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and Basic Constraints Config setting values.
When importing a certificate, the screen shows the Type, Signing Request, and Private Key setting values.
Save adds the certificate to TrueNAS.
Back returns to previous screens to make changes before you save.
Next advances to the next screen in the sequence to return to Confirm Options.
ACME DNS-Authenticators Screens
The ACME DNS-Authenticators widget, on the Certificates screen, shows configured authenticators.
Automatic Certificate Management Environment (ACME) DNS-Authenticators allow users to automate certificate issuing and renewal.
The user must verify ownership of the domain before TrueNAS allows certificate automation.
ACME DNS is an advanced feature intended for network administrators or AWS professionals.
Misconfiguring ACME DNS can prevent you from accessing TrueNAS.
The system requires an ACME DNS authenticator and CSR to configure ACME certificate automation.
Fields change based on Authenticator selection. The Edit DNS Authenticator screen shows the current settings entered and saved on the Add DNS Authenticator screen.
Text entry field that accepts manual or copy/paste entry of an internal identifier (name) for the authenticator.
Authenticator
Sets a DNS provider to create an authenticator. The dropdown list of provider options: cloudflare digitalocean route53 OVH shell.
Cloudflare Email
Text entry field that accepts manual or copy/paste entry of your Cloudflare account email address. Shows when cloudflare is selected in Authenticator.
API Key
Text entry field that accepts manual or copy/paste entry of the API key obtained from Cloudflare. Shows when cloudflare is selected in Authenticator.
API Token
Text entry field that accepts manual or copy/paste entry of the API token obtained from Cloudflare. Shows when cloudflare is selected in Authenticator.
Digitalocean Token
Text entry field that accepts manual or copy/paste entry of the token obtained from Digitalocean. Shows when digitalocean is selected in Authenticator.
Access Key ID
Text entry field that accepts manual or copy/paste entry of the access key ID obtained from AWS Route53. Shows when route53 is selected in Authenticator.
Secret Access Key
Text entry field that accepts manual or copy/paste entry of the secret access key obtained from AWS Route53. Shows when route53 is selected in Authenticator.
Application Key
Text entry field that accepts manual or copy/paste entry of the application key obtained from OVH. Shows when OVH is selected in Authenticator.
Application Secret
Text entry field that accepts manual or copy/paste entry of the application secret key obtained from OVH. Shows when OVH is selected in Authenticator.
Consumer Key
Text entry field that accepts manual or copy/paste entry of the consumer key obtained from OVH. Shows when OVH is selected in Authenticator.
Endpoint
Text entry field that accepts manual or copy/paste entry of the endpoint. For example, ovh-us or ovh-ca depending on your region. Shows when OVH is selected in Authenticator.
Script
Text entry field that accepts manual or copy/paste entry of a path to where you filed the DNS challenge script. For example, /path/to/your-dns-script.sh. Shows when shell is selected in Authenticator. A DNS challenge script automates the process of proving domain ownership by updating DNS records. It allows creating TXT records, which ACME servers, like Let’s Encrypt, that query to verify domain control. It is particularly useful for obtaining wildcard certificates or when HTTP-based challenges are not feasible.
User
Text entry field that accepts manual or copy/paste of a user name. For example, root, adminUserName, etc. Shows when shell is selected in Authenticator.
Timeout
Text entry field that accepts manual or copy/paste of a numeric value that establishes how long TrueNAS waits (in seconds) for DNS propagation. The default is 120 or 300 seconds. Shows when shell is selected in Authenticator.
Delay
Text entry field that accepts manual or copy/paste entry of a numeric value (in seconds) that TrueNAS writes after the creation of the DNS record. The default is 60 or 120 seconds. Shows when shell is selected in Authenticator.
Delete DNS Authenticator Dialog
The Delete DNS Authenticator dialog shows a Confirm option that, when selected, activates the Delete button. TrueNAS asks you to confirm before you can delete the authenticator.
KMIP on TrueNAS Enterprise is used to integrate the system within an existing centralized key management infrastructure and use a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
The KMIP screen has two areas, KMIP Key Status that displays keys synced between a KMIP server and TrueNAS database and KMIP Server with the KMIP configuration settings.
The KMIP Key Status area of the KMIP screen lists ZFS/SED keys synced between a KMIP server and the TrueNAS database.
Sync Keys synchronizes keys issued by the KMIP server with the TrueNAS database. This button activates when a KMIP key sync is pending.
Clear Sync Keys cancels a pending synchronization. This button is active when a KMIP key sync is pending or in progress but not completed.
KMIP Server Settings
Setting
Description
Server
Text entry field that accepts manual or copy/paste entry of the host name or IP address of the central key server.
Port
Text entry field that accepts manual or copy/paste entry of a connection port number on the central key server. Default value 5696 is the kmip.truenas.com port number.
Certificate
Sets an existing certificate to one selected on the dropdown list, or enter a new one to use for key server authentication. Requires a valid certificate to verify the key server connection. Warning: for security reasons, protect the certificate used for key server authentication.
Manage SED Passwords
Manages the global self-encrypting drive (SED) password with KMIP when enabled. This option allows the key server to manage creating or updating the global SED password, and retrieving SED passwords when SEDs are unlocked. Disabling this option leaves SED password management with the local system.
Manage ZFS Keys
Uses the KMIP server to manage ZFS encrypted dataset keys when enabled. The key server stores, applies, and destroys encryption keys whenever an encrypted dataset is created, when an existing key is modified, an encrypted dataset is unlocked, or an encrypted dataset is removed. When not enabled, this option leaves all encryption key management with the local system.
Enabled
Activates KMIP configuration and begins syncing keys with the KMIP server when enabled.
Change Server
Moves existing keys from the current key server to a new key server when enabled. When switching to a different key server, enable key synchronization, then select this setting, update the key server connection configuration, and click Save.
Validate Connection
Tests the server connection and verify the chosen certificate chain when enabled. To test, configure the Server and Port settings, select a certificate, then select this setting, and click Save.
Force Clear
Cancels any pending key synchronization when selected.
Containers
Virtual Machines and Containers in TrueNAS 25.10
TrueNAS 25.04 introduced support for Containers (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in FreeBSD-based TrueNAS.
In TrueNAS 25.04.2 and later, virtual machines are created and appear on the Virtual Machines screen.
Legacy VMs created in 25.04.0 or 25.04.1 using the instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the Containers screen.
Legacy VMs on the Containers screen do not autostart in 25.10 or later.
Users with existing VMs on the Containers screen should consider migrating associated zvols to the Virtual Machines screen at this time to ensure compatibility with future TrueNAS releases.
For information on migrating your zvol storage volume to a new VM created in 25.10 or later, see Migrating Legacy VMs to Virtual Machines.
Due to backend technology changes in TrueNAS 27, containers on the Containers screen require migration when you upgrade from TrueNAS 25.10.
Containers migrate automatically at the first boot after upgrading, except on HA-capable TrueNAS Enterprise systems.
Containers on a passphrase-encrypted pool do not migrate, because the pool is still locked at first boot and the migration does not retry.
Switch the pool to key encryption before you upgrade.
Contact TrueNAS Enterprise Support if you have containers on a TrueNAS Enterprise system that does not migrate them.
Legacy VMs on the Containers screen are not migrated automatically and are removed from the Containers screen in TrueNAS 27.
Complete the steps in Preparing to Upgrade to TrueNAS 27 before you upgrade.
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.
Containers Screen
The Containers screen allows users to add, edit, or manage Linux containers.
The screen header displays a Pool is not selected status before a pool for containers is selected.
See Global Settings for more information.
Global Settings opens the Global Settings screen showing global options that apply to all containers, including selecting the storage pool for containers and network settings.
The Enable Containers toggle activates or deactivates containers.
The Pools dropdown list shows a list of available pools on the system for container storage.
The screen header displays a Pool is not selected status before a pool for containers is selected.
Container Storage Location
TrueNAS (25.10 and later) stores containers in a hidden .truenas_containers dataset on the selected pool.
Each container has its own dataset within .truenas_containers, named after the container: pool/.truenas_containers/containers/container_name.
The .truenas_containers dataset is mounted separately from the pool file system, at /mnt/.truenas_containers/pool, to prevent accidental inclusion in SMB or NFS shares.
TrueNAS manages the .truenas_containers dataset internally. Modifying it directly can cause container instability or data loss.
Default Network Settings
Default Network settings configure global networking defaults for the containers service.
Setting
Description
Bridge
Specifies the network bridge. Automatic uses the default network bridge for communication between containers and the TrueNAS host. The dropdown list option shows existing bridges. See Accessing NAS from VMs and Containers for more information.
IPv4 Network
Specifies the IPv4 address for the bridge specified when Bridge is set to Automatic. Enter the IPv4 address and subnet (e.g., 192.168.1.0/24) for the containers to use or leave empty to allow TrueNAS to use the default address.
IPv6 Network
Specifies the IPv6 address for the bridge specified when Bridge is set to Automatic. Enter the IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) for the containers to use or leave empty to allow TrueNAS to use the default address.
Manage Volumes
The Volumes screen lists all volumes currently configured for the containers service.
Specifies the Zvol to import. Enter or browse to select an existing Zvol.
Clone
Clones and promotes a temporary snapshot of the zvol into a custom storage volume. This option retains the original zvol while creating an identical copy as a containers volume.
Move
Relocates the existing zvol to the ix-virt dataset as a volume.
Delete Volumes
delete Delete on an image row deletes that image.
A Delete volume dialog displays.
The Users or Groups tabs display mappings for individual user or group accounts, respectively.
Existing mappings are shown in a table containing the group or user name, host ID, and container ID.
delete Delete on a row deletes that mapping.
Add New Mapping Settings
Setting
Description
User/Group
Specifies the user or group account name. Begin typing an account name to search for it or select it from the dropdown menu.
Map to the same UID/GID in the container
(Default) Specifies the host ID-to-container user or group ID mapping. Select to map the host ID to the same ID in containers.
Container UID/GID
(Displays when Map to the same UID/GID in the container is not selected) Specified the user or group ID. Enter the ID number (e.g., 1000) to map the host user or group ID to in containers.
Set creates the mapping.
Changes take effect immediately, but containers might require a restart to reflect the changes.
Create Container Wizard
The Create Container configuration wizard displays all settings to set up a new container.
Container Configuration
The Container Configuration settings specify the container name and operating system image.
Required. Enter an alphanumeric name for the container.
Image
Browse Catalog opens the Select Image screen with available Linux image choices from linuxcontainers.org. Search or browse to locate your desired image and click Select.
Name Requirements
A container name must meet these criteria:
It must be between 1 and 63 characters long.
It can only include letters, numbers, and dashes from the ASCII character set.
It cannot begin with a number or a dash.
It cannot end with a dash.
CPU & Memory
The CPU & Memory settings specify the number of virtual CPU cores to allocate to the container and memory size.
Enter the number of virtual CPU (vCPU) cores to allocate to the instance. Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores. For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node. For example, to assign cores 0,1,2,5,9,10,11, you can write: 1-2,5,9-11.
Set CPU limits or leave this field blank to allow access to all host CPUs.
Memory Size
Allocate RAM for the instance. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
Set memory limits or leave this field blank to allow access to all host memory.
Environment
The Environment settings configure optional environment variables to run on boot or execute.
(Required) Displays after clicking Add in Disks. Define an existing dataset or create a new dataset using the Create Dataset option. Creating a dataset requires entering a path or browsing to select a parent dataset from the dropdown list of datasets on the system. Enter a name for the new dataset in the Create Dataset window. Create adds the dataset.
Destination
(Required) Specifies the file system path to mount the disk in the container, for example /media or /var/lib/data.
Proxies
The Proxies settings allow you to forward network connections between the host and the container.
This routes traffic from a specific address on the host to an address inside the container, or vice versa, allowing the container to connect externally through the host.
Add displays a set of proxy configuration settings.
Sets the connection protocol for the TrueNAS host. Options are TCP or UDP.
Host Port
Sets TrueNAS host port to map to the instance port on the container, for example 3600.
Instance Protocol
Sets the connection protocol for the container. Select from the options TCP or UDP.
Instance Port
Sets the port number within the container. Enter a port number to use, for example 80.
Network
The Network settings configure how the container connects to the host and external networks.
Options include the default network bridge, an existing bridge interface, or a MACVLAN.
Select to use default network settings to connect the container to the host using the automatic bridge defined in Global Settings. Selected by default. Disable to display the Bridged NICs (if available) and Macvlan NICs settings.
Bridged NICs
Select an existing bridge on the TrueNAS host to connect to the container. Displays when one or more existing bridge interface(s) are available.
Macvlan NICs
Select an existing interface to create a virtual network interface based on it, assigning a unique MAC address so the container appears as a separate device on the network.
A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host.
MACVLAN sends traffic directly to the external network without passing through the host network stack.
The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.
USB Devices
USB Devices displays a list of available devices to attach to a container, allowing the device to function as if physically connected.
The Containers table lists each configured container, displaying its name, type, current state, and options to restart or stop it.
Stopped containers show the option to start the container.
The play_circle button starts a stopped container.
Search above the Containers table allows entering the name of a container to locate a configured container.
The checkbox on each container row shows the Bulk Actions dropdown.
Bulk Actions
The Bulk Actions dropdown list allows you to apply actions to one or more containers on your system.
Options are Start All Selected, Stop All Selected, and Restart All Selected.
The Details for Container widgets display information and configuration options for the selected container.
General Info Widget
The General Info widget displays the container status, autostart setting, base image, CPU, memory, and secure boot configuration.
It includes the Edit and Delete buttons for the container.
Edit opens an Edit Container: Container configuration screen populated with editable settings also found on the install wizard screen for the container.
Delete Containers
The Delete dialog asks for confirmation to delete the selected container.
The Disks widget shows the storage devices attached to the container, along with their associated paths.
It allows you to manage the disks, including adding new ones or modifying existing ones.
Add opens the Add Disk screen for adding new disks to the container.
For existing disks, the more_vert actions include options to Edit or Delete the disk mount.
For VMs, the widget displays the current root disk size.
The root disk stores the OS and serves as the boot disk for the VM.
Change opens the Change Root Disk Setup dialog.
Add/Edit Disk Screen
The Add/Edit Disk screen allows you to configure a new disk or modify an existing one attached to a container.
Increases the size of the VM root disk. Enter a new root disk size in GiB, such as 20.
Root Disk I/O Bus
Sets the communication pathway type for the root disk. Options are NVMe, Virtio-BLK, and Virtio-SCSI.
Save applies changes.
NIC Widget
The NIC Widget displays the network interfaces (NICs) attached to the container, along with their names and types.
It allows you to add new NICs and manage existing ones.
Confirm activates the Continue button.
Continue starts the delete operation.
Proxies Widget
The Proxies widget displays the network proxy settings configured for the container.
It allows you to manage these settings, including adding, editing, or removing proxies.
Confirm activates the Continue button.
Continue starts the delete operation.
Idmap Widget
The Idmap widget shows the user ID (UID) and group ID (GID) mappings used by the container to translate IDs between the host and the container.
It provides details such as the Host ID, Maprange, and NS ID for both UIDs and GIDs.
Host ID shows the starting ID used by the host for mapping to the container IDs.
Maprange indicates the range of IDs that the host allocates for the container.
NS ID represents the namespace ID used for the mapping.
For example, if the Host ID is 2147000001 and the Maprange is 458752, the container UID 0 (root) is mapped to the host UID 2147000001.
This ensures proper isolation and user/group identity management between the host and the container.
Tools Widget
The Tools widget provides quick access to various tools and utilities for managing your container.
You can open a shell, console, or VNC session directly from this widget.
Shell opens an Container Shell session for command-line interaction with the container.
Serial Console (VM only) opens an Container Console session to access the system console for the container.
VNC (VM only) opens a VNC connection using your preferred client.
It uses a VNC URL scheme (for example, vnc://hostname.domain.com:5930) to launch the session directly in the application.
If your environment does not support VNC URLs, you can manually connect using a VNC client by entering the host name or IP address followed by the port number without vnc:// (for example, hostname.domain.com:5930 or IP:5930).
Metrics Widget
The Metrics widget displays real-time graphs that monitor container performance, including CPU usage, memory usage, and disk I/O pressure.
CPU (%) shows the percentage of CPU usage over time.
Memory (MiB) displays the memory usage in MiB over time.
Disk I/O Full Pressure (%) tracks the disk input/output pressure as a percentage over time.
Edit Container Screen
The Edit Container: Container screen settings are a subset of those found on the Create Container Wizard screens.
It includes the general Container Configuration and CPU and Memory settings for containers.
Additionally, containers include Environment settings.
To edit device, disk, network, or proxy settings, use the Containers Widgets on the Containers screen.
Edit Container Configuration Settings
The Container Configuration settings on the Edit screen allow you to modify basic parameters for the container, such as startup behavior.
Enter the number of virtual CPU (vCPU) cores to allocate to the instance. Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores. For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node. For example, to assign cores 0,1,2,5,9,10,11, you can write: 1-2,5,9-11.
Set CPU limits or leave this field blank to allow access to all host CPUs.
Memory Size
Allocate RAM for the instance. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
Set memory limits or leave this field blank to allow access to all host memory.
Edit Environment Settings
The Environment settings on the Edit screen are the same as those in the Create Container wizard.
These settings configure optional environment variables for the container.
Use Search Devices or the Type dropdown to filter available devices.
The selected PCI device(s) must not be in use by the host or share an IOMMU group with any device the host requires.
Select attaches the selected device.
Virtual Machines
Virtual Machines Screen
The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) or VM devices in TrueNAS.
The No Virtual Machines screen shows when there are no VMs configured in or deleted from TrueNAS.
Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.
Each virtual machine listed includes the Running and Start on Boot toggles.
Running shows the current state of the VM.
Start on Boot automatically starts the VM after a system reboot.
Expanding a VM shows the details screen details on and options for that VM.
Virtual Machine Details Screen
The expanded Virtual Machines screen shows the details and options for a VM.
Details include the basic information on the number of virtual CPUs, cores, threads, the amount of memory, the boot loader, and system clock types.
Additional details include the display port number and the shutdown timeout in seconds.
Options shown change after starting a virtual machine.
When a VM is placed in a suspended state, the options shown on the VM details screen change to show only the Power Off and Resume options.
VM Options
Operation
Icon
Description
Start
Starts a VM. The toggle turns blue when the VM switches to running. The Start button toggles to Stop. While running, the screen shows the Restart,Power Off, Display, and Serial Shell buttons.
Restart
replay
Stops then starts the VM. Shows for a running VM.
Power Off
power_settings_new
Shows after starting a VM. Powers off and halts the VM, similar to turning off a computer power switch. Shows only when the VM is running.
Resume
Shows when a VM is placed in a suspended state. The VM resumes operation and returns to the normal Running state.
Stop
stop
Shows after starting a VM. Stops a running VM. Virtual machines do not always respond to STOP or the command might time out if the VM does not have an OS. Use Power Off instead. Stop toggles to Start after the VM stops.
Edit
mode_edit
Opens the Edit Virtual Machine with editable VM settings. You cannot edit a VM while it is running. Stop the VM to edit the properties and settings.
Delete
delete
Deletes a VM and removes it from the system. Opens a delete dialog. You cannot delete a virtual machine that is running. Stop the VM to delete it.
Shows after starting the VM. Makes an exact clone copy of the VM. Opens the Clone dialog.
Display
settings_ethernet
Shows after starting the VM. Opens the SPICE login screen in a new browser window and allows you to connect to the remote desktop after entering the password to access that remote desktop.
Serial Shell
keyboard_arrow_right
Shows after starting the VM. Opens the TrueNAS VM Serial Shell screen.
Download Logs
content_paste
Places a copy of the .log file on the system.
Delete Virtual Machine Dialog
The Delete Virtual Machine dialog shows options when deleting the VM and removing the VM configuration from your system.
Removes the data associated with this virtual machine. When selected, displays a list of disk and raw file devices to delete. Deleting a VM results in data loss if the data is not backed up. Do not select this option to keep the VM data intact.
Force Delete
Ignores the virtual machine status during the delete operation. Do not select this option to prevent deleting the VM when it is still active or the state is undefined.
Enter vmname below to confirm
Blank text entry field to manually enter the name of the VM to delete. This must match the name shown in the dialog.
Clone Virtual Machine Dialog
The Clone dialog settings create an exact duplicate (clone) of the VM. The blank field allows manual entry of a name for the clone of the selected VM.
Naming the clone VM is optional.
A cloned VM shows on the Virtual Machines list with the extension _clone0. Cloning the same VM again changes the extension for the second clone to clone1.
VM Serial Shell Screen
The Serial Shell button opens the VM Serial Shell screen, where you can enter commands for the selected virtual machine.
The Virtual Machines breadcrumb in the header to returns to the Virtual Machine screen.
Edit Virtual Machine Screen
The Edit VM screen shows a subset of settings in the Create Virtual Machine screens.
It includes the general settings also on the wizard Operating System screen, CPU and Memory, and GPUs screen settings.
To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.
General Settings
The Edit screen General Settings specifies the basic settings for a VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.
Required. Enter an alphanumeric name for the virtual machine.
Description
Enter a description (optional).
System Clock
Select the VM system time from the dropdown list. Options are Local or UTC. The default is Local.
Boot Method
Select the boot method option from the dropdown list. Select UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout
Enter the time, in seconds, the system waits for the VM to cleanly shut down. During the shutdown, the system powers off the VM after the shutdown timeout entered expires.
Start on Boot
Select to start this VM when the system boots.
Enable Hyper-V Enlightenments
Shows for VMs set for Windows OS. KVM implements Hyper-V Enlightenments for Windows guests. These features make Windows think they are running on a Hyper-V-compatible hypervisor and use Hyper-V-specific features. In some cases, enabling these enlightenments might improve the usability and performance for the guest.
Enable Secure Boot
Turns on the secure boot function in TrueNAS. Only available when using the wizard to create a new VM; it is not available on the edit screen. Some operating systems, like Windows 11, might not require secure boot.
Enable Trusted Platform Module (TPM)
Turns on the Trusted Platform Module (TPM) for enhanced security features in TrueNAS. TPM provides hardware-based cryptographic security functions. Some operating systems, like Windows 11, might require enabling this option.
Edit CPU and Memory Settings
The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.
Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores
Text entry field to manually enter the number of cores per virtual CPU socket.
Threads
Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)
Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus
Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model
Sets the CPU model to the option selected on the dropdown list.
Memory Size
Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size
Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)
Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).
Edit GPU Settings
The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.
Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device
Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs
Sets the GPU to the option selected on the dropdown list.
Devices Screens
The Devices screen shows a table listing of VM devices configured on your system. By default, the screen shows three devices: Disks, NIC, and Display.
Add opens the Add Device screen. Settings change based on the various device types.
The more_vert at the right of each device row shows options for that device:
Edit - Opens the Edit type Device screen where type is the device type selected.
Settings vary based on the type of device selected in Device Type. See Add Device screen.
Device Type only displays on the Add Device screens.
Delete - Opens the Delete Device dialog.
Details - Opens an information dialog showing the port, type, bind IP, and other details about the device.
Export to Image - Shows only for disk devices. Opens the Export Disk to Image window to convert the disk (zvol) to a portable disk image file in QCOW2, QED, RAW, VDI, VHDX, or VMDK format.
Create Virtual Machine Wizard Screens
The Create Virtual Machine wizard includes all settings to set up a new virtual machine in TrueNAS.
Next and Back advance to the next screen or return to the previous screen without saving or losing setting choices.
Save saves all settings, closes the wizard, and adds the new VM to the Virtual Machines screen.
Operating System Settings
The Operating System settings specify the VM operating system type, the time setting the VM system clock uses, the boot method, and the display type.
(Required) Sets the operating system for the VM operating system to the option selected on the dropdown list. Options are Windows, which adds the Enable Hyper-V Enlightenments option. Linux, and FreeBSD.
Enable Hyper-V Enlightenments
Only shows when Guest Operating System is set to Windows. When enabled, the VM emulates a Hyper-V-compatible hypervisor for the Windows guest operating system and makes some Hyper-V-specific features available.
Name
(Required) Text entry field that accepts manual or copy/paste entry of a name for the VM that consists of alphanumeric characters.
Description
(Optional) Text entry field that accepts manual or copy/paste entry of a brief description about the VM. For example, the type of OS for the VM or the purpose of the VM.
System Clock
(Required) Sets the VM system clock to the option selected on the dropdown list. Options are: Local, which uses the TrueNAS SCALE system clock setting, or UTC, which uses the Coordinated Universal Time clock. The default is Local.
Boot Method
(Required) Sets the boot method to the option selected on the dropdown list. Options are: UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Enable Secure Boot
Sets the VM to verify boot components using digital signatures. This prevents unauthorized code from running during startup and is required for Windows 11 and some Linux distributions.
Enable Trusted Platform Module (TPM)
Sets TrueNAS to provide a virtual TPM 2.0 device for the VM. This enables hardware-based security functions, including secure key storage and cryptographic operations. Required for Windows 11.
Shutdown Timeout
Text entry field that accepts manual entry of a time in seconds that the system waits for the VM to cleanly shut down. During system shutdown, the system powers off after the shutdown timeout for the VM expires.
Start on Boot
Sets the VM to automatically start after restarting the system or when it is rebooted. Selected by default.
Enable Display (VNC)
Enables a VNC display (Virtual Network Computing) remote connection. VNC is the default display type when adding a VM. Requires UEFI booting. Selected by default.
Bind
Shows when Enable Display is selected. Sets an IP address to use for remote VNC sessions. Note that this setting only applies when using a VNC client other than the TrueNAS WebUI.
Password
(Required) Displays when Enable Display is selected.Enter a password to secure access to the VM. Enter this when logging into the VNC display.
CPU and Memory Settings
The CPU and Memory settings specify the CPU mode, model, and memory size. They allow specifying the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.
Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores
Text entry field to manually enter the number of cores per virtual CPU socket.
Threads
Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)
Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus
Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model
Sets the CPU model to the option selected on the dropdown list.
Memory Size
Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size
Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)
Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).
Disks Settings
The Disks settings specify how virtual disks are added. Options are creating a new zvol on an existing dataset for a disk image, using an existing zvol for the VM, or importing an existing disk image file (QCOW2, QED, RAW, VDI, VHDX, VMDK) and converting it to a zvol.
Shows settings to create a new zvol on an existing dataset to use as a virtual hard drive for the VM. Displays the Select Disk Type, Zvol Location, and Size fields.
Use existing disk image
Shows settings to select an existing zvol for the VM. Displays the Select Disk Type and Select Existing Zvol fields.
Import Image
Checkbox option to import an existing disk image file and convert it to a zvol for VM use. When you select this option, the Image Source field displays. Supports QCOW2, QED, RAW, VDI, VHDX, and VMDK formats with automatic format detection.
Image Source
(Required) Displays when you select Import Image. Browse to and select the source disk image file to import. The system automatically detects the image format from the file.
Select Disk Type
Sets the disk type to the option selected on the dropdown list. Options are AHCI or VirtIO. Select AHCI for Windows VMs. VirtIO requires a guest OS that supports VirtIO paravirtualized network drivers.
Select Existing Zvol
(Required) Shows after selecting Use existing disk image. Sets the disk to the existing zvol selected from the dropdown list.
Zvol Location
(Required) Shows a dropdown list of datasets to select as the location where the system creates a new zvol. When you select Import Image, this specifies the destination dataset for the converted zvol. When you select Create new disk image, this specifies where the system creates the new zvol.
Size
(Required) Shows when Create new disk image is selected. Allocates space for the new zvol. (Examples: 500 KiB, 500M, 2 TB). Units smaller than MiB are not allowed.
Network Interface Settings
The Network Interface settings specify the network adapter type, MAC address, and physical network interface card associated with the VM.
Sets the adapter type to the option selected on the dropdown list. Options are:
Intel e82545 (e1000) - Emulates the same Intel Ethernet card and provides compatibility with most operating systems.
VirtIO - Provides better performance when the operating system installed in the VM supports VirtIO para-virtualized network drivers.
Mac Address
Shows the MAC address automatically entered by TrueNAS. Enter the desired address into the field to override the randomized MAC address.
Attach NIC
Sets the physical interface to associate with the VM selected on the dropdown list.
Trust Guest Filters
Enables and allows the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Enabling Trust Guest Filters has security risks because it allows the virtual server to change its MAC address and so receive all frames delivered to this address. Disabled by default.
Installation Media Screen
The Installation Media settings specify the location of the operating system installation media image in a TrueNAS dataset, or you can upload a copy from the local machine.
Shows two fields, the mount path field and a file browser field directly below it. Sets the mount path to what is selected in the file browser field. To collapse the file branch, click on the to the left of /mnt.
Upload New Image File
Opens the Upload Image File dialog, where you browse to, and select the image file location on the local system or a network location available to your TrueNAS system. Choose File sets the file location and activates Upload.
Enter the path or browse to the location where you want to install the image file.
Choose File
Click to save the path populated in the ISO save location field.
Upload
Click to upload the file selected in the ISO save location field.
GPU Screen
The GPU settings specify the graphics processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.
Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device
Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs
Sets the GPU to the option selected on the dropdown list.
Confirm Options Screen
The Confirm Options screen shows a summary of settings for the VM, including the number of CPUs, cores, threads, memory, name of the VM, and the disk size.
Save adds the VM to the Virtual Machines screen.
Add Device Screen
The Add Device screen shows different settings based on the option selected in Device Type. Settings change based on the type, except the Type and Device Order settings, which are common to all device types.
Type sets the device type to the option selected on the dropdown list. The default selection is CD-ROM.
Device Order sets the position of the device in the boot order used when the system boots up or restarts.
Accepts a number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
CD-ROM Settings
CD-ROM settings show when Device Type is set to CD-ROM.
CD-ROM Path shows two fields: the /mnt path field that populates with what is selected with the file browser field directly below it. The to the left of /mnt expands or collapses the directory branch while you browse to the location of the CD-ROM file on the system. |
NIC Settings
VM network interface card settings show when Device Type is set to NIC.
(Required) Sets the emulator type to the option selected in the dropdown list. Emulating an Intel e82545 (e1000) Ethernet card provides compatibility with most operating systems. VirtIO provides better performance for systems with VirtIO paravirtualized network driver support.
MAC Address
Shows the default auto-generated random MAC address the VM receives. Enter a custom address to override the default.
Generate
Generates a new randomized address in MAC Address.
NIC To attach
Sets a physical interface to associate with the VM to the device selected on the dropdown list.
Trust Guest Filters
Allows the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to “yes” has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address. The default setting is not enabled.
Disk Settings
Disk settings, including disk location, drive type, and disk sector size, show when Device Type is set to Disk.
A disk device has four options: Edit, Delete, Details, and Export to Image.
Export to Image opens the Export Disk to Image window.
Sets the zvol path to the options selected on the dropdown list.
Mode
Sets the drive type to the option selected on the dropdown list. Options are AHCI or VirtIO.
Disk sector size
Sets the disk sector size in bytes to the option selected on the dropdown list, or leave it set to Default. Options are: Default, which uses the ZFS volume values, 512, or 4096. Setting a sector size changes both the logical and physical sector size.
Display Settings
Display settings show when Device Type is set to Display. You can only have one display type set to VNC (the default when creating a new VM), but you can add a second display device and set it to SPICE.
Remote clients can connect to VM display sessions using a SPICE client, or by installing a third-party remote desktop server inside your VM.
SPICE clients are available from the SPICE Protocol site.
Sets a new display device type to the option selected. When a VM is created without a display device, the Display Type options are VNC or SPICE. When the VM is created with the display device set to the default VNC, only the SPICE option shows on the dropdown list. TrueNAS allows creating two display devices, one from the VM creation wizard, which uses the default VNC display, and a second through the Add Device screen with the Device Type set to Display. Only SPICE shows when adding the second display device.
Port
Text field that accepts manual or copy/paste entry of a port number. Can be set to 0, left empty for TrueNAS to assign a port when the VM is started, or set to a fixed preferred port number.
Resolution
Sets the screen resolution for the VM display session to the option selected on the dropdown list.
Bind
Sets the IP address used for the SPICE display sessions to the option selected on the dropdown list. Options include the default 0.0.0.0, ::, ::1, IP addresses obtained from your network, and the TrueNAS primary interface.
Password
Text field that accepts manual or copy/paste entry of a password, that is eight characters in length, that TrueNAS automatically passes to the remote display session.
Web Interface
Enables connecting to the SPICE web interface, and shows the Web Port field.
Web Port
Sets the web console port for browser-based access to the VM display.
Raw File Settings
Shows the raw file settings, including file location, size, disk sector size, and type when Device Type is set to Raw File.
Shows two fields. A file browser field and a blank field that populates with what is selected in the file browser directly below it. Use the to the left of /mnt to expand or collapse the directory branches as you browse to and select the location of the file on the system.
Disk sector size
Sets the disk sector size to the option selected on the dropdown list. Options are Default, which uses the ZFS volume values, 512 or 4096. Setting a sector size changes both the logical and physical sector size.
Mode
Sets the drive type to the option selected on the dropdown list. Options are:
AHCI - Emulates an AHCI hard disk for better software compatibility.
VirtIO - Uses paravirtualized drivers and can provide better performance, but the operating system installed in the VM must support VirtIO disk devices.
.
Raw filesize
Text field that accepts manual entry of a number for the size of the file in GiB.
PCI Passthrough Settings
Shows PCI passthrough device settings when Device Type is set to PCI Passthrough Device.
Depending upon the type of device installed in your system, you might see a PCI device does not have a reset mechanism defined warning.
You might experience inconsistent or degraded behavior when starting or stopping the VM.
If this occurs, determine if you want to proceed with this action.
PCI Passthrough Device sets the PCI device to what is manually entered or select on the dropdown list of options. Enter a device as bus#/slot#/fcn#, for example 0000:00:04.3 ‘System peripheral’: Sky Lake-E CBDMA Registers by ‘Intel Corporation’.
USB Passthrough Settings
Shows the USB passthrough device setting when Device Type is set to USB Passthrough Device.
(Required) Sets the controller to the option selected on the dropdown list. Options are: piix3-uhci, piix4-uhci, ehci, ich9-ehci1, vt82c686b-uhci, pci-ohci, nec-xhci, qemu-xhci.
Device
Sets the device to the option manually entered or selected on the dropdown list of options. Selecting Specify custom shows the Vendor ID and Product ID fields.
Export Disk to Image Window
The Export Disk to Image window shows a file browser and other settings to convert a VM disk (zvol) to a portable disk image file. You access it from a disk device on the Devices screen.
Sets the path to the desired dataset/directory where you want to export the image file. Enter the mount path, or use the file browser to browse to and select the mount path. When you click on the dataset/directory, the system selects it and populates the blank field directly above the file browser field.
Image Name
Shows the name for the exported image file. The system automatically adds the appropriate file extension based on the format you select in Image Format.
Image Format
Sets the type of image the system creates and adds the file extension to the name in Image Name. Options are:
QCOW2 - QEMU Copy On Write
QED - QEMU Enhanced Disk
RAW - Raw Disk Image
VDI - VirtualBox Disk Image
VHDX - Hyper-V Virtual Hard Disk
VMDK - VMware Virtual Machine Disk
Apps
The TrueNAS Applications Market is your new resource for the latest details about apps available within TrueNAS.
Discover which apps are widely used or recently added, filter the entire catalog to find the perfect app, and learn specifics that can help you deploy an app.
The website updates daily, so you’ll always have the latest info about TrueNAS applications!
We welcome community contributions to keep this documentation current!
Click Edit Page in the top right corner to propose changes to this article.
See Updating Content for more information.
There are two main application screens, Installed and Discover.
The Installed applications screen shows the status of installed apps, provides access to pod shell and logs screens and a web portal for the app (if available), and the ability to edit deployed app settings.
The Discover screen shows widgets for the installed catalog of apps.
The individual app widgets open app information screens with details about that application, and access to an installation wizard for the app.
It also includes options to install third-party applications in Docker containers that allow users to deploy apps not included in the catalog.
Installed Screen
The first time you go to Apps, the Installed applications screen header shows an Apps Service Not Configured status and dialog opens prompting you to choose the pool for apps to use.
You must choose the pool apps use before you can install applications. See Choose A Pool for Apps for more information.
Choose Pool opens the Choose a pool for apps dialog. The Pool dropdown list shows a list of available pools on the system.
Choose sets the selected pool for use by applications.
The first time you open the Installed applications screen a dialog prompts you to choose the pool for apps to use for storage.
Select the pool from the dropdown list, then click Save. This starts the applications service.
If you exit out of this dialog, to set the pool, click Settings > Choose Pool to select a storage pool for apps.
If a pool is not selected and you attempt to install an application, a dialog window prompts you to select a pool before the installation wizard shows.
Migrate Existing Applications
If you select a new pool in the Pool dropdown after previously configuring the apps service, the dialog displays the Migrate existing applications option.
Migrate existing applications migrates all installed applications to the new applications pool.
Migrate existing applications only affects data saved in the apps dataset, such as the installed app loacation and iXvolume storage.
Data in mounted host paths is not migrated.
Unset Pool
Unset Pool on the Settings menu opens the Unset Pool dialog.
Unset removes the pool configuration and turns off the application service.
When complete, a Success dialog displays.
Entering characters in the Search field on the screen header filters the images list to only the Image ID or Tags entries matching the entered characters.
Delete Delete in an image row opens the Delete image dialog.
The checkbox to the left of Image ID or an image shows the Batch Operations section and delete button.
Pull Image
Pull Image opens a side panel with options to download specific images to TrueNAS.
Target images must not be associated with any running container.
Select Confirm and then click Delete to delete the image(s).
Force allows deletion if an image is referenced by multiple tags or stopped containers.
Use Force with caution as it can potentially break dependencies or leave images without defined tags.
Docker Registries
The Docker Registries screen lists signed-in Docker registry records.
The Uniform Resource Identifier (URI) type for the registry. Options are Docker Hub or Other Registry. Hidden when a Docker Hub registry record is already configured.
URI
The valid Uniform Resource Identifier (URI) for the registry, for example https://index.docker.io/v1/. Displays when URI is set to Other Registry or when a Docker Hub registry record is already configured.
Name
Display name for the registry record. Displays when URI is set to Other Registry or when a Docker Hub registry record is already configured.
Username
The user name to sign in to the registry.
Password
The password for the user to sign in to the registry.
Settings
Settings opens the Settings screen showing four application train options, the option to add IP addresses and subnets for the application to use, check for Docker image updates, and if the system is equipped with a GPU, to enable TrueNAS to update drivers for that GPU.
Select the checkbox to the left of the train name to add another train to the applications catalog.
Train options:
stable the default train for official apps
enterprise for apps verified and simplified for Enterprise users, default for enterprise-licensed systems.
community for community proposed and maintained apps
test for application in development but not yet released in one of the other three trains.
You must specify at least one train.
The Address Pools shows the current IP address and subnet mask for the network used by applications.
Base shows the default IP address and subnet, and Size shows the network size of each docker network that is cut off from the base subnet.
Select a predefined range from the dropdown list.
This setting replaces the Kubernetes Settings option for Bind Network in 24.04 and earlier.
Use to resolve issues where apps experience issues where the TrueNAS device is not reachable from some networks.
Select the network option, or add additional options to resolve the network connection issues.
Install NVIDIA Drivers shows if the system has an NVIDIA GPU installed.
Select to enable TrueNAS to manually install drivers for this device.
When the TrueNAS Debug Kernel is enabled, NVIDIA drivers are disabled.
Systems with non-NVIDIA GPU devices do not show this option, but these GPUs are selectable in the app installation wizards in the Resources Configuration section for the app.
Check for docker image updates sets TrueNAS to check for docker image updates (default setting).
Applications Table
The Applications table on the Installed screen populates a row for each installed app that shows the current state, and the option to stop the app.
Stopped apps show the option to start the app.
After installing an application, the Installed screen populates the Applications table.
When returning to the Installed screen, the first application on the list is selected by default.
Each application row shows the name, status, and update information for the application.
Select the checkbox to the left of Applications to show the Bulk Actions dropdown menu.
Menu options are Start All Selected, Stop All Selected, Update All Selected, and Delete All Selected.
Performing a bulk action update opens a dialog listing the apps with available updates.
Select an application by clicking the radio button to the left of a listed application.
Click the expand icon for listed app to show the Version dropdown and Changelog for the selected version.
Update begins updating the applications one at a time. Apps status changes to STOPPED before it is updated, and then returns to RUNNING after the update completes.
Application Widgets
Installed applications have a set of widgets on the Installed screen.
Select an application row to view the information widgets for that application.
Information in the widgets changes based on the app row selected in the Applications table.
Application Info Widget
The Application Info widget shows the name, (upstream) app version number, catalog version number, source link for the application, and train name.
It includes the Edit, Delete, Roll Back and Web UI buttons for the application.
The more_vert dropdown contains the Update and Convert to custom app buttons.
Remove iXVolumes deletes hidden app storage from the apps pool.
Force-Remove iXVolumes deletes app storage created on TrueNAS 24.04 and migrated to 24.10 or later.
Remove Images prunes Docker images of the deleted app.
Confirm activates the Continue button. Continue initiates the delete operation.
Update Apps
Update shows on the Application Info widget after clicking Update All on the Installed applications header.
Both only show if TrueNAS detects an available update for an application.
The application widget on the Discover screen also displays an update badge.
Update opens an update window for the application that includes the Version to be updated to dropdown and Changelog options.
Update begins the process and opens a progress dialog that shows the update progress.
When complete, the update badge and buttons disappear.
The Update state on the application row on the Installed screen changes to Up to date.
Convert to Custom App
Convert to custom app on the more_vert dropdown opens a dialog to convert an installed catalog application to a custom YAML application.
Converting to a custom app direct editing to YAML configuration file for the app using the Custom App Screens.
The Version dropdown contains available app versions for roll back.
The version numbers displayed are the version of the app in the TrueNAS catalog, equivalent to the Version displayed on the app information card.
It is not equal to the App Version or the upstream release version.
See Understanding Versions on the TrueNAS Apps Market for more information.
Roll back snapshots restores the application data volume to match the selected version by rolling back to the snapshot for that version.
This reverts both the application and app data stored in the apps pool to the exact state from when the snapshot was created.
Roll back snapshots only affects data saved in the apps dataset, such as iXvolume storage.
Data in mounted host paths is not rolled back.
Cancel closes the dialog without completing the roll back.
Roll Back begins the operation.
Workloads Widget
The Workloads widget shows the container information for the selected application.
Information includes the number of pods, used ports, number of deployments, stateful sets, and container information.
It also shows the Shell, Volume Mounts and View Log icon buttons that provide access to the container pod shell and log screens and mount point windows.
The option to access the log and the shell remain available for stopped applications for fully deployed application containers, and for applications in the crashed state.
The Volume Mountsfolder_open button opens the Volume Mounts dialog.
The View LogsLogs button also opens the Pod Logs screen for the app.
Volume Mounts
Volume Mounts opens a dialog showing information on the app volume mounts for current and exited volume mounts for the application container.
The app has Volume Mount options to open windows for both the running mount point and permissions - exited mount point.
Use the logs to help troubleshoot problems with your container pods.
Notes Widget
The Notes widget shows information about the apps, TrueNAS Documentation Hub article locations, links to file bug reports through Jira or GitHub, and where to make feature requests.
View More expands the widget to show more information on application settings.
Collapse hides the extra information.
Application Metadata Widget
The Application Metadata widget shows application capabilities unique to the application, and Run As Content showing the user and group IDs, the default user and group name, and brief description for the application.
View More expands the widget to show more information on application settings.
Collapse hides the extra information.
Discover Apps Screen
The Discover screen displays application widgets for the official TrueNAS stable train by default.
Users can add the community and enterprise, or test train applications on the Settings screen.
Custom App opens the Install iX App screen with an install wizard.
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
The Discover screen includes a search field, links to other application management screens, and filters to sort the application widgets displayed.
Show All shows all application widgets in the trains added to the Stable catalog. The links are:
Refresh Charts that executes a job to refresh the catalog applications.
Manage Installed Apps that opens Installed applications screen.
Filters shows a list of sort categories that alter which application widgets show. Click on a category to select and filter app widgets.
Filter information includes the Category, App Name, and Updated Date.
Category sorts the app widgets by category or functional area.
For example, Media, Monitoring, Networking, Productivity. etc.
App Name sorts app widgets alphabetically (A to Z).
Updated Date sorts the app widgets by date of update.
Install Custom App Screens
TrueNAS 24.10 or later provides two options for installing a third-party application not included in the official catalogs using a Docker image.
Custom App opens the Install iX App guided installation wizard.
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
Each application widget on the Discover screen opens an information screen with details about that application, a few screenshots of the web UI for the application, and the Install button.
Application information shows the app version, GitHub repository link for the image, and date the image was last updated, keywords, the TrueNAS app train, and the app homepage location.
The application information screen shows two widgets:
Available Resources that show CPU and memory usage the app requires, the app pool, and available space in gigabits.
Application Info that includes the application version number, link to GitHub repository for the image, and date the image was last updated.
Some applications might also include the Run-As Content and Capabilities widgets.
The screen includes small screenshots of the application website that, when clicked, opens larger versions of the image.
Install opens the installation wizard for the application.
The bottom of the screen includes app widgets for similar applications found in the catalog.
Application Install or Edit App Wizards
The application Install Application wizard and Edit Application screens show the same settings, but un-editable settings are either not shown or are inactive to prevent edit attempts.
The Edit Application screen opens populated with the current settings for the application.
The install and edit wizard screens include a navigation panel on the right of the screen that lists and links to the setting sections.
A red triangle with an exclamation point marks the sections with the required settings.
An asterisk marks the required fields in a section.
You can enter a new setting in fields that include a preprogrammed default.
Custom App Screens: Provides information on the Install Custom App screen and configuration settings.
MinIO is a trademark of the MinIO Corporation.
Custom App Screens
Custom App on the Discover screen opens the Install iX App guided installation wizard.
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
Install iX App Screen
The Install iX App screen allows you to configure third-party applications using Docker settings.
Use the wizard to configure applications not included in the official catalog.
The panel on the right of the screen links to each setting area.
Click on a heading or setting to jump to that area of the screen.
Click in the Search Input Fields to see a list of setting links.
Enter a name for the application. The name must have lowercase alphanumeric characters, begin with an alphabet character, and can end with an alphanumeric character. The name can contain a hyphen (-) but not as the first or last character in the name. For example, use chia-1 but not -chia1 or 1chia- as a valid name.
Version
Displays the current version of iX-App. Accept the default number.
Image Configuration Settings
Image Configuration settings specify the container image details.
They define the image, tag, and when TrueNAS pulls the image from the remote repository.
(Required) Enter the Docker image repository name. For example, plexinc/pms-docker for Plex.
Tag
Enter the tag to use for the specified image. For example, public for Plex. Or accept the default latest.
Pull Policy
Select the Docker image pull policy from the dropdown list. Options are Only pull image if not present on host (default option), Always pull image even if present on host, and Never pull image even if it’s not present on host.
Container Configuration Settings
Container Configuration settings specify the entrypoint, commands, timezone, environment variables, and restart policy to use for the image.
These can override any existing variables stored in the image.
Check the documentation for the application you want to install for required entrypoints, commands, or variables.
Click Add to display a new field. Each field is an item in the ENTRYPOINT list in exec format. For example, to enter ENTRYPOINT ["top", "-b"], enter top in the first Entrypoint field. Click Add again. Enter -b in the second field.
Command
Click Add to display a new field. Each field is an item in the CMD list in exec format. For example, to enter CMD ["echo", "hello world"], enter echo in the first Command field. Click Add again. Enter hello world in the second field.
Timezone
Use the dropdown to select a timezone setting for the container or begin typing the timezone to see a narrowed list of options to select from.
Environment Variables
Click Add to display a block of environment variables. Click Add again to enter another set of environment variables.
Name
Enter the environment variable name or key. For example, enter MY_NAME.
Value
Enter the value for the variable specified in Environment Variable Name. For example, enter John Doe, John\ Doe, or John.
Restart Policy
Use the dropdown to select a restart policy to use for the container. Options are No - Does not restart the container under any circumstances., Unless Stopped - Restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed., On Failure - Restarts the container if the exit code indicates an error., and Always - Restarts the container until its removal..
Disable Builtin Healthcheck
Select to disable the built-in HEALTHCHECK defined in the image, for example to address performance or compatibility requirements.
TTY
Select to enable a pseudo-TTY (or pseudo-terminal) for the container.
Stdin
Select to keep the standard input (stdin) stream for the container open, for example for an interactive application that needs to remain ready to accept input.
Security Context Configuration Settings
Security Context Configuration settings allow you to run the container in privileged mode, grant the container Linux kernel capabilities, or define a user to run the container.
Select to run the container in privileged mode. Note that privileged mode grants the container nearly unrestricted access to the host system, providing full administrative access to the entire TrueNAS server. This includes access to privileged credentials, encryption keys, and all data. By default, containers cannot access host devices. With Privileged enabled, the container gains access to all host devices and system capabilities. Only enable privileged mode when absolutely necessary and when you fully trust the container source. A more secure solution is to use Capabilities below to grant specific, limited permissions as needed.
Capabilities
Click Add to display a container capability field. Enter a Linux capability to enable, for example, enter CHOWN. Click Add again to enter another capability.
Custom User
Select to display the User ID and Group ID fields.
User ID
Displays when Custom User is selected. Enter the numeric UID of the user that runs the container. Defaults to 568 (apps).
Group ID
Displays when Custom User is selected. Enter the numeric GID of the group that runs the container. Defaults to 568 (apps).
Network Configuration Settings
Network Configuration settings specify network, ports, and DNS servers if the container needs a custom networking configuration.
Use port forwarding to reroute container ports that default to the same port number used by another system service or container.
See Default Ports for a list of assigned ports in TrueNAS.
See the Docker Container Discovery documentation for more on overlaying ports.
By default, containers use the DNS settings from the host system.
You can change the DNS policy and define separate nameservers and search domains.
See the Docker DNS services documentation for more details.
Select to bind the container to the TrueNAS host network. When bound to the host network, the container does not have a unique IP-address, so port-mapping is disabled.
Ports
Click Add to display a block of port configuration fields to specify the port values and transfer protocol. Click again to add additional port mappings.
Container Port
Enter a port number in the container. Refer to the application documentation for default port values.
Host Port
Enter an open port number on the TrueNAS host.
Protocol
Select the protocol from the dropdown list. Options are TCP or UDP.
Nameservers
Use to add one or more IP addresses to use as DNS servers for the container. Click Add to the right of Nameservers to display a Nameserver entry field. Click again to add another name server.
Nameserver
Enter the IP address of the name server.
Search Domains
Use to add one or more DNS domains to search non-fully qualified host names. Click Add to display a Search Domain field to enter the domain you want to configure. Click again to add another search domain. See the Linux search documentation for more information.
Search Domain
Enter the search domain you want to configure. For example, mydomain.com.
DNS Options
Use to add one or more key-value pairs to control various aspects of query behavior and DNS resolution. Click Add to display an Option field. Click again to add another option. See the Linux options documentation for more information.
Option
Enter a key-value pair representing a DNS option and its value. For example, ndots:2.
Portal Configuration Settings
The Portal Configuration settings configure the web UI portal for the container.
Click Add to display the web portal configuration settings.
Enter a UI portal name to use and display in the UI. For example, MyAppPortal.
Protocol
Select the web protocol to use for the portal from the dropdown list. Options are HTTP or HTTPS.
Use Node IP
Select to use the TrueNAS node, or host, IP address to access the portal. Selected by default.
Host
Displays when Use Node IP is not selected. Enter a host name or an internal IP within your local network, for example my-app-service.local or an internal IP address.
Port
Enter the port number to use for portal access. The port number the app uses should be in the documentation provided by the application provider/developer. Check the port number against the list of Default Ports to make sure TrueNAS is not using it for some other purpose.
Path
Enter the path for portal access, for example /admin. Defaults to /. The path is appended to the host IP and port, as in truenas.local:15000/admin.
Storage Configuration Settings
The Storage Configuration settings specify persistent storage paths and share data claims separate from the lifecycle of the container.
For more details, see the Docker storage documentation.
You can mount TrueNAS storage locations inside the container with host path volumes.
Create the storage volumes in TrueNAS and set the host path volume to a dataset and directory path.
Define the path to the system storage and the container internal path for the system storage location to appear.
Alternatively, select ixVolume to allow TrueNAS to create a dataset on the apps storage pool.
Both Host Path and ixVolume attach container storage as a bind mount.
See Docker Bind Mount documentation for more information.
Users can create additional SMB share volume claims within the container to access an SMB share.
Share volumes consume space from the pool chosen for application management.
Finally, Tmpfs allows the container to utilize a temporary directory on the RAM.
See the Docker tmpfs documentation for more information.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the host path mounts inside the container.
Enable ACL
Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Host Path
(Required) Enter a path or click arrow_right to the left of /mnt to browse to the location of the dataset to populate the Host Path. Click on the dataset to select and display it in the Host Path field.
ACL Entries
Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type
Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID
Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access
Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.
Force Flag
Displays when Enable ACL is selected. Select to apply the configured ACL settings to a directory containing existing data.
ixVolume (Dataset created automatically by the system)
Use to configure a storage mount for a system created dataset on the applications pool.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the ixVolume mounts inside the container.
Enable ACL
Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Dataset Name
Enter a name for the dataset that is created and used for storage.
ACL Entries
Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type
Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID
Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access
Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the share volume mounts inside the container.
Server
(Required) Enter the IP address for the SMB server, for example 192.168.1.100. This can be the TrueNAS host.
Path
(Required) Enter the name of the SMB share, for example my-share.
Username
(Required) Enter the username of an account with permission to access the SMB share.
Password
(Required) Enter the password for the account in Username.
Domain
Enter the directory services domain. Only required if the domain is something other than the TrueNAS default WORKGROUP, for example on systems with Active Directory configured.
Tmpfs (Temporary directory created on the RAM)
Use to configure a memory-backed temporary directory.
See the Docker tmpfs documentation for more information.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data. Not recommended for memory-backed storage.
Mount Path
(Required) Enter the path where the memory-backed directory mounts inside the container.
Tmpfs Size Limit (in Mi)
(Required) Enter the maximum size of the temporary directory in mebibytes. Defaults to 500.
Resources Configuration Settings
Resources Configuration settings configure resources for the container.
Resource limits specify the CPU and memory limits to place on the container.
GPU Configuration settings configure GPU device allocation for application processes.
Settings only display if the system detects available GPU device(s).
See GPU Passthrough for more information.
Select to enable resource limits and display the CPUs and Memory (in MB) settings.
CPUs
Enter the maximum number of CPU cores the container can access. For example, 2.
Memory (in MB)
Enter the number of megabytes you want to limit memory to. For example, 4096.
Passthrough available (non-NVIDIA) GPUs
Select to allow the passthrough of non-NVIDIA GPU devices to the container.
Select NVIDIA GPU(s)
Displays if compatible NVIDIA GPU device(s) are installed and detected.
Use this GPU
Select to allow passthrough of the specified NVIDIA device to the container.
Add Custom App Screen
The Add Custom App screen allows you to configure third-party applications using Docker Compose YAML syntax.
Use the YAML editor to configure applications not included in the official catalog.
See the Docker Compose overview from Docker for more information.
Installing custom applications via YAML requires advanced knowledge of Docker Compose and YAML Syntax.
Users should be prepared to troubleshoot and debug their own installations.
The TrueNAS forums are available for community support.
TrueNAS applies basic YAML syntax validation to custom applications, but does not apply additional validation of configuration parameters before executing the file as written.
Enter a name for the application to be used in the TrueNAS UI. The name must use lowercase alphanumeric characters, start with an alphabetic character, and can end with alphanumeric character. A hyphen (-) is allowed but not as the first or last character, for example abc123, abc, abcd-1232, but not -abcd.
Custom Config
Enter a Docker Compose YAML file for the application.
Click Save to initiate app deployment.
Reporting
The Reporting screen displays graphs of system information for CPU, disk, memory, network, system functions, UPS, and ZFS.
Use the dropdown in the upper right corner to select between reporting graph display options.
The CPU report displays by default.
TrueNAS uses Netdata to gather metrics, create visualizations, and provide reporting statistics.
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.
To configure a third-party reporting integration, such as Graphite, click Exporters to open the Reporting Exporters screen.
Report Graphs
The following sections provide examples of each report graph.
There are a few controls to change the default graph view:
The Auto Refresh toggle updates the graphs with the latest reporting data every few seconds.
When active, the graph resets to the chosen Reset Zoom view every time the reporting data updates.
Disable Auto Refresh before manually zooming in on any section of the graph.
Step Back () moves the graph backward in time by whatever time increment is currently active in Reset Zoom.
Step Forward () moves the graph forward in time by whatever time increment is currently active in Reset Zoom.
The default graph view is to show the latest data, which disables this button.
Zoom Out () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views.
The Reset Zoom indicator shows which time value is active for the graph.
The default 1 Hour is the default (and minimum) time period that can be active.
When Zoom Out is active, click Reset Zoom to reset the graph view to 1 Hour.
Zoom In () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views.
This is active when the graph changes from the default 1 Hour view.
To manually adjust the vertical or horizontal precision of the graph, disable Auto Refresh, then click and drag within the graph view.
A left-to-right (or vice-versa) motion increases the horizontal view precision, while an up-to-down (or vice-versa) motion increases the vertical precision.
CPU Graphs
Shows the CPU temperature, CPU usage, and system load graphs.
CPU graphs show the amount of time the CPU spends in various states such as executing user code, executing system code, and idle time.
Graphs show short-, mid-, and long-term loads, along with CPU temperature graphs.
Shows graphs for each selected system disk, and by report type.
Disk graphs show read and write statistics on I/O, percent busy, latency, operations per second, pending I/O requests, and disk temperature.
Use the Select Disks dropdown to select the disks.
Use the Select Reports dropdown to select the report types to display.
Displays all available graphs for any or all disks selected on the Disks dropdown list.
Disk Temperature
Displays the minimum, maximum, and mean temperature readings for the disk selected.
Disk I/O
Displays the disk read and write I/O stats in bytes/s.
Temperature monitoring for the disk is disabled if HDD Standby is enabled.
Check the Storage > DisksEdit Disk* configuration form for any or all disks in the system if you do not see the temperature monitoring graph.
Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Memory Graphs
Shows the Physical memory available graph with the amount of free memory available based on current memory usage.
Shows an Interface Traffic graph for each interface in the system.
Network graphs report received and transmitted traffic in megabytes per second for each configured interface.
Shows the UPS UPS voltage for battery, input, and output, charging percentage, UPS runtime, UPS input current, frequency, and input load, and UPS temperature.
The UPS service must be configured with a compatible Uninterruptible Power Supply (UPS) device.
Exporter on the Reporting screen opens the Reporting Exporter screen.
The Reporting Exporters screen shows reporting exporters configured on the system.
Exporting enables TrueNAS to send reporting metrics to another time-series database.
Exporters send reporting records as JSON objects to third-party reporting collection cloud services or applications installed on servers.
Enter a unique name for the exporter configuration. If configuring multiple instances, give each a distinct name.
Type
Select the report object format. At present, GRAPHITE is the only current supported option. Selecting GRAPHITE displays the exporter configuration settings
Enable
Select to enable sending reporting data to the configured exporter. Leave the checkbox clear to disable the explorer without removing the configuration.
Additional settings populate based on the selected Type option.
(Required) Enter the IP address of the Graphite server.
Destination Port
(Required) Enter the port the Graphite server monitors.
Prefix
Enter the top level of the file hierarchy for the path to use to store exported records. For example, enter the top-level folder name for the path, and use Namespace to enter the folder for the data records. For example, enter dragonfish.
namespace
Enter the name of the folder where you store data records. Use the Prefix to define the full path. You can also enter the host name to add to all data records sent to the Graphite server. Defaults to truenas.
Update Every
(Optional) Enter the number of seconds for the interval to send data to the Graphite database. Defaults to 1.
Buffer On Failures
(Optional) Enter the number of iterations (Update Every seconds) to buffer data when the Graphite server is not available. Defaults to 10.
Send Names Instead Of Ids
(Optional) Enter true to send Netdata chart and dimension names to Graphite or false to send IDs. Defaults to true.
Matching Charts
(Optional) Enter one or more space-separated patterns in regular expression. Use the asterisk () as a wildcard to send all charts or the exclamation mark (!) to define a negative match to specify the charts to send to Graphite. Defaults to ().
Update Screens: Provides information on functions and fields on the TrueNAS Update screens.
General Settings Screen: Provides information on the General Settings screen, widgets, and configuration settings for getting support, changing console or the GUI, localization and keyboard setups, and system email.
Advanced Settings Screen: Provides information on the System Settings > Advanced screen, widgets, and configuration screen settings.
Boot: Provides reference descriptions of the boot environment screens and settings.
Services: Information on the Services screen and individual service articles in the Services area.
FTP Service Screen: Provides information on the FTP services screens and settings.
Truenas systems ship with a profile assigned to the system administration user, but users can select a different option on Select and update profile dropdown list.
TrueNAS checks the update server daily for updates available to the selected update profile.
An upgrade only shows when the system detects it. The screen shows four information areas:
Installed Version - Shows the current release of TrueNAS running on the system.
Other Options - Shows the Manual Install option, and a link to the TrueNAS Documentation Hub article on manually updating the release.
Update Profile - Shows the Select an update profile dropdown list.
Available Profiles - Shows a list of update profiles, and a description of what each provides.
Installed Version
This section shows the current TrueNAS release installed on the system. System is up to date shows when no updates are available to the profile set in Select an update profile.
If an update is detected, it and the Install Update button show below the current release version.
The update summary for this release shows the View Release Notes link that opens the release notes for the update version.
Each profile changes the type of releases or updates available. Default profiles are labeled.
Each update profile and the description of software in each shows on the Update screen in the Available Profiles area.
The profiles listed in this section show the profile and a brief description of releases made available to each profile. These profiles are on the Select an update profile dropdown list. Some profiles might not be available to all TrueNAS users, in particular Enterprise users.
Profile selections allow users to choose how conservative the software selection is based on the use case. The table below summarizes profiles and the intended users.
Profile
Description
Developer
Available to developer users. The developer profile is for nightly builds of software in active development. Expect many issues and frequent, sometimes twice daily updates.
Early Adopter
Available to Community users wanting to try out or test early or nightly releases still in development. Pre-release access to new features and functionality of TrueNAS software. Some issues might need workarounds, bug reports, or patience.
General
Available to Community and some Enterprise customers, but is not recommended for Enterprise customers. General releases are field-tested software with mature features. Expect a few issues in the general release profile.
Mission Critical
Available to Community and Enterprise users, especially TrueNAS HA systems. This profile is the most conservative release, and is mature software that enables 24x7 operations with high availability for a clearly defined use case. Software updates are very infrequent and based on need.
Save Configuration Settings Window
The Save configuration settings from this machine before updating? window opens after clicking Install to the right of Manual Install.
Export Password Secret Seed stores hashes of the passwords sufficient for authentication in the system, but it does not store user passwords.
The secret seed is used to decrypt encrypted fields in the TrueNAS configuration database.
Various fields are encrypted because they might contain sensitive information such as cryptographic certificates, passwords (not user login passwords), or weak hashing algorithms (for example, NT hashes of SMB users).
When a config file is restored without the secret seed, encrypted fields are set to empty values.
This means various services can be broken due to the missing information. Examples are SMB via local accounts and apps.
Save Configuration downloads the system configuration file to your system. Keep the configuration file in a safe place that is regularly backed up.
Manual Update Screen
The Manual Update screen opens after saving the system configuration settings.
Current Version shows the TrueNAS release version running on your system.
Choose File opens a browser window where you can locate the downloaded update file.
The Update File Temporary Storage Location dropdown list includes two options:
Memory Device
A mount location on the system designating where on the system to store the upgrade file. For example, a pool or dataset path on your system.
Apply Update starts the installation.
General Settings Screen
The General Settings screen has four widgets that show current general system settings and include buttons for related actions and configuration options. The widgets are:
Community systems show the same widgets, but are not eligible for Enterprise support options or licenses.
The TrueNAS logo shows for the Community Edition of TrueNAS.
Support Widgets
The Support widget for Community Edition TrueNAS shows the version, model number of the CPU detected, system memory detected, a system serial number if configured, and links to the Documentation Hub, TrueNAS Forums, and offers TrueNAS Licensing information.
The Community Edition Support widget shows a TrueNAS icon instead of a system image available for TrueNAS Mini and other platforms sold by TrueNAS.
Images of non-standard systems are not supported due to the number of different options available in the marketplace.
File Ticket opens a feedback/report issue window where users can provide feedback on the screen or report an issue and save/attach a system debug file.
Save Debug starts downloading a system debug file to the local machine.
TrueNAS Enterprise
The Support widget on the General Settings screen for Enterprise customers shows system licenses applied to the system, the system model, serial, license numbers not shown for Community Edition of TrueNAS, and any additional hardware associated with the system.
The This is a production system toggle, which shows only on TrueNAS Enterprise systems, opens the Update Production Status dialog.
Add License opens the License screen.
After adding a license, Update License replaces the Add License button.
Get Support dropdown shows two options: File Ticket and Proactive Support when the system is an Enterprise-licensed system.
Non-Enterprise licensed systems only show the File Ticket option.
Update Production Status Dialog
The Update Production Status dialog can set a TrueNAS Enterprise system to production status and can send an initial system debug to TrueNAS.
Send initial debug starts the debug download and file transfer to TrueNAS.
Proceed starts the process and sets the system to a production system.
Send Feedback Window
The Send Feedback window shows two options: Rate this page and Report a Bug, which is the default selection after clicking File Ticket.
The Rate this page is the default selection after clicking the option to rate a new screen shown in early release with new functional screens or redesigned screens.
Subject is a text entry field for a brief description of an issue experienced. For example, Traceback received when pressing Save.
Message is a text entry field for a longer description of what steps were taken and the result. The field provides examples of what to enter. This content populates the Jira ticket description field after clicking Login To Jira To Submit.
Attach debug, which is selected by default, downloads and attaches a system debug to the Private Attachment Area TrueNaS provides to secure user confidential data that is part of the debug file.
Take screenshot of the current page, selected by default, takes a screenshot of the current screen.
Attach additional images opens a file browser where you can locate and attach saved logs, screenshots, or video files that help explain the issue reported in the ticket.
Login To Jira To Submit opens a Jira login screen where you enter your Jira credentials so TrueNAS can create the ticket for you using your credentials.
Rate this page
Select the Rate this page to show options to submit review feedback on a UI screen.
Stars set a rating using one (lowest) to five (best) stars.
Message is a text entry field for comments about the screen you are rating. Include what you like, don’t like, works well, or does not work well, and your exerience with the screen.
Take screenshot of the current page, selected by default, takes a screenshot of the current screen.
Attach additional images opens a file browser where you can locate and attach saved screenshots or video files that help explain what you report in the ticket.
The License screen opens after clicking either Add License or Update License on the Support widget on the General Settings screen.
It allows pasting a copy of your license into the form and saving it.
End User License Agreement (EULA) opens a copy of the TrueNAS end user license agreement.
I AGREE digitally marks it signed, then closes the screen and updates the Support widget with the license and hardware information.
This is a production system indicates the system is used in a production, non-test environment.
Proceed sends TrueNAS an email notification that the system is in production.
Proactive Support Screen
Silver/Gold coverage customers can enable proactive support.
This feature automatically emails TrueNAS when certain conditions occur in a TrueNAS system.
Proactive Support opens a window where you configure proactive support.
Sets a color theme to the option selected from the dropdown list. Options are: ixDark (default option), ixBlue, Dracula, Nord, Paper, Soloarized Dark, Midnight, and High Contrast. Selecting an option immediately changes the UI to the selected color theme.
GUI SSL Certificate
Sets the selected certificate as the SSH certificate. truenas_default is the default certificate. The system uses a self-signed certificate to enable encrypted web interface connections. Manage Certificates opens the Certificates screen. Certificates added or imported into TrueNAS show on this list.
Web Interface IPv4 Address
Sets an IP address to limit the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface IPv6 Address
Sets an IPv6 address from the dropdown list to limit usage when accessing the administrative GUI. The default is ::. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface HTTP Port
Sets a non-standard port to access the GUI over HTTP. The default is 80. Changing this setting might require changing a Firefox configuration setting.
Web Interface HTTPS Port
Sets a non-standard port to access the GUI over HTTPS. The default is 443.
HTTPS Protocols
Sets a cryptographic protocol(s) for securing client/server connections. Select the Transport Layer Security (TLS) versions TrueNAS can use for connection security from the dropdown list of options:
TLSv1
TLSv1.1
TLSV1.2 selected by default
TLSv1.3 (selected by default)
Web Interface HTTP -> HTTPS Redirect
Redirects HTTP connections to HTTPS. A GUI SSL certificate is required for HTTPS. Activating this sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year. After adding a new certificate, select it or use the default TrueNAS certificate in GUI SSL Certificate.
Usage Collection & UI Error Reporting
When enabled, anonymous usage statistics and WebUI errors are reported to the TrueNAS engineering team. No personally identifiable information is collected. When disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g. TrueNAS 24.04.0, 55 TB) are still collected. Information about system configuration and usage is not collected. For more information about what usage data is collected, see the TrueNAS Data Collection Statement.
Show Console Messages
Shows console messages in real-time at the bottom of the browser screen.
Localization Settings Screen
The Localization widget shows the current language, date, time format, time zone, and console keyboard map settings for the TrueNAS system.
Provides access to a configuration screen to customize settings.
Sets the language for the UI screens. The default setting is English but might be customized to the language based on the country of origin for an Enterprise customer. Allows filtering the list by typing in the field after clearing the default value. Or scroll down to locate and select a language from the dropdown list.
Console Keyboard Map
Sets a language for the keyboard layout, for example, English (US) for American English. Select an option on the dropdown list, or type in the field to filter the list to show matching languages.
Timezone
Set the geographical time zone for the system. Allows filtering the list by typing in the field after clearing the default value. Or scroll down to locate and select a timezone from the dropdown list.
Date Format
Sets the date format to the option selected on the dropdown list.
Time Format
Sets the time format to the option selected on the dropdown list.
Email Options Screen
The Email widget shows the email configured on the system. Settings opens the Email Options configuration screen.
Setting options change based on the selected send-mail method. Options:
Select to enable SMTP AUTH using plain Simple Authentication and Security Layer (SASL) for authentication and data security. Applies and requires a valid simple username and password authentication method.
Username
Shows after selecting SMTP Authentication. Sets the username of the sending email account, which is typically the full email address. Enter the username if the SMTP server requires authentication.
Password
Shows after selecting SMTP Authentication. Sets the password for the sending email account for the SMTP server. Only plain ASCII characters are accepted.
OAuth Email Options
Gmail OAuth and Outlook OAuth options show the From Email and From Name fields and a log-in-to button for the email method selected.
GMail OAuth shows Log In To Gmail and Outlook OAuth shows Log In To Outlook.
These login methods step through a sequence of login screens for the selected method.
For more information, see Setting Up System Email
Advanced Settings Screen
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Advanced Settings screen provides configuration options for the console, syslog, audit, kernel, sysctl, storage (system dataset pool), replication, WebSocket sessions, cron jobs, init/shutdown scripts, NTP servers, allowed IP addresses, isolated GPU device(s), self-encrypting drives, and global two-factor authentication.
Pre-25.10 systems with S.M.A.R.T. testing schedules have these schedules appearing as cron jobs.
You can download or upload your system configuration files from this screen.
The TrueNAS UI has several fields that allow users to write custom scripts. When a user writes a password into a custom script, the password is provided in cleartext form within system debug files, creating a serious security concern.
We do not recommend using custom scripting on TrueNAS, as it is a highly advanced feature for expert storage administrators and can lead to security breaches.
The Manage Configuration dropdown shows two options: one to download the system config file and the other to upload a system config file.
The option to reset system settings to the default configuration shows after uploading a configuration file.
Download File
Download File opens the Save Configuration dialog, where users can download the current system configuration to their local machine.
The Export Password Secret Seed option is selected by default.
It stores hashes of the passwords sufficient for authentication in the system, but does not store user passwords.
The secret seed is used to decrypt encrypted fields in the TrueNAS configuration database.
Various fields are encrypted because they might contain sensitive information such as cryptographic certificates, passwords (not user login passwords), or weak hashing algorithms (for example, NT hashes of SMB users).
When a config file is restored without the secret seed, encrypted fields are set to empty values.
This means various services can be broken due to the missing information. Examples are SMB via local accounts and apps.
Upload File
The Upload File option opens the Upload Config dialog, which allows users to choose a previously saved TrueNAS configuration to replace the current system configuration. This is useful when restoring system configuration settings after a clean install of a TrueNAS release.
Choose File opens a file browser window to locate the downloaded and saved configuration file.
After selecting the file, the Upload Config window opens.
Upload starts the upload of the selected configuration file.
All passwords are reset if the uploaded configuration file was saved without Export Password Secret Seed enabled.
Reset to Defaults
The Reset to Defaults option opens the Reset Configuration dialog.
Using Resetting to Defaults returns the system configuration to factory settings and restarts the system. Users must set a new login password.
Save the current system configuration with the Download File option before resetting the configuration to default settings.
Not saving the system configuration before resetting it can result in losing data that is not backed up and losing the ability to revert to the previous configuration.
Console Widget
The Console widget shows the current console settings for TrueNAS, which cover setting a password prompt for the text console, enabling/disabling the serial console, the current serial port number and speed, and any banner text entered in the MOTD Banner field.
Console settings configure how the Console Setup menu displays, the serial port it uses and the port speed, and the banner users see when accessing it.
Select to display the console without being prompted to enter a password. Leave cleared to add a login prompt to the system before showing the console menu. Selected by default.
Enable Serial Console
Select to enable the serial console. Selected by default. Clear this if the serial port is disabled.
Serial Port
Shows the default serial port. If using a port other than the default, enter the serial console port address.
Serial Speed
Shows the default serial port speed. If not using the default speed, select the speed (in bits per second) the serial port uses from the dropdown list. Options are 9600, 19200, 38400, 57600, or 115200.
MOTD Banner
Enter the message you want to display when a user logs in with SSH. The default banner message is Welcome to TrueNAS.
Syslog Widget
The Syslog widget displays the existing system logging settings that specify how and when the system sends log messages to system log (syslog) servers.
TrueNAS allows configuring an array of two syslog servers. Each server can have its own host, transport, and TSL certificate setting.
The Syslog settings specify the logging level the system uses to record system events to the boot device.
Sets whether to use a fully qualified domain name (FQDN) for logging, and if audit logs are included.
There is also an option to configure a remote syslog server for recording system events.
Select to include the fully qualified domain name (FQDN) in logs to identify systems with similar host names.
Syslog Level
Select the minimum log priority level to send to the remote syslog server. The system only sends logs at or above this level.
Syslog Server
Enter the remote syslog server DNS hostname or IP address. Add a colon and the port number to the hostname to use non-standard port numbers, like mysyslogserver:1928. Log entries are written to local logs and sent to the remote syslog server. Add Syslog Server shows a block of settings to configure a syslog server. Allows adding two servers.
Host
Syslog Server setting. Sets the remote syslog server DNS host name or IP address. Allows using non-standard port numbers by adding a colon and the port number to the host name, like mysyslogserver:1928. Log entries are written to local logs and sent to the remote syslog server.
Transport
Syslog Server setting. Sets the transport protocol for the remote system log server connection. Selecting Transport Layer Security (TLS) shows the TLS Certificate field. This setting requires pre-configuring the server system certificate if not using the Truenas_default certificate.
TLS Certificate
Syslog Server setting that shows after selecting TLS in Transport. Select the transport protocol for the remote system log server TLS certificate from the dropdown list. Select the default or import a certificate using the Credentials > Certificates screen, Certificates widget.
Include Audit Logs
Select to enable audit logging.
Audit Widget
The Audit widget displays the current audit storage and retention policy settings.
The public-facing TrueNAS API allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
Set to boot a debug kernel after the next system restart. This is intended for troubleshooting scenarios only and should typically remain disabled. Enabling this option disables any Nvidia drivers present on the system.
Cron Jobs Widget
The Cron Jobs widget displays No Cron Jobs configured until you add a cron job, and then it shows the information on the cron job(s) configured on the system.
Click on any job listed in the widget to open the Edit Cron Jobs configuration screen populated with the settings for that cron job.
Add or Edit Cron Job Configuration Screen
The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Cron Jobs lets users configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Enter the full path to the command or script to run. For example, to create a command string that generates a list of users on the system and writes that list to a file, enter cat /etc/passwd > users_$(date +%F).txt
Run As User
Select a user account to run the command. The user must have permissions allowing them to run the command or script.
Schedule
Select a schedule preset or choose Custom to open the advanced scheduler. Note that an in-progress cron task postpones any later scheduled instance of the same task until the running task is complete.
Hide Standard Output
Select to hide standard output (stdout) from the command. If left cleared, TrueNAS mails any standard output to the user account cron that ran the command.
Hide Standard Error
Select to hide error output (stderr) from the command. If left cleared, TrueNAS mails any error output to the user account cron that ran the command.
Enabled
Select to enable this cron job. Leave cleared to disable the cron job without deleting it.
Init/Shutdown Scripts Widget
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script; then the widget lists the scripts configured on the system.
Select Command for an executable or Script for an executable script.
Command
Enter the command with any options.
Script
Selects the script. Scripts run using dash(1) by default, or under the interpreter named in the shebang line of the script (for example, #!/bin/bash).
When
Select when the command or script runs from the dropdown list. Options are Pre Init for early in the boot process, after mounting file systems and starting networking. Post Init runs at the end of the boot process before Linux services start. Shutdown runs during the system power-off process. Scripts in the same category (for example, multiple Post Init scripts) run sequentially in the order in which the user added them.
Enabled
Select to enable this script. When left cleared, it disables the script without deleting it.
Timeout
Automatically stop the script or command after the specified number of seconds.
Sysctl Widget
The Sysctl widget displays either No Sysctl configured or the existing sysctl settings on the system.
Enter the name of the sysctl variable to configure. Sysctl tunables configure kernel parameters while the system runs and generally take effect immediately.
Value
Enter a sysctl value to use for the loader, sysctl variable.
Description
Enter a description for the tunable.
Enabled
Select to enable this tunable. Leave clear to disable this tunable without deleting it.
Adding NTP Servers
The NTP Servers widget allows users to add Network Time Protocol (NTP) servers.
These sync the local system time with an accurate external reference.
By default, new installations use several existing NTP servers. TrueNAS supports adding custom NTP servers.
The Add NTP Server screen shows Network Time Protocol (NTP) server settings that sync the local TrueNAS system with an accurate external reference.
By default, new installations use several existing NTP servers. TrueNAS supports adding custom NTP servers.
Add on the NTP Servers widget opens the Add NTP Server screen.
Sets the host name or IP address of the NTP server.
Burst
Enables using a non-public NTP server. Recommended when Max Poll is greater than 10. Only use on personal NTP servers or those under direct control. Do not enable it when using public NTP servers.
IBurst
Enables and speeds up the initial synchronization (seconds instead of minutes).
Prefer
Enable when using highly accurate NTP servers such as those with time monitoring hardware. Only use these highly accurate NTP servers.
Min Poll
Sets the minimum polling interval. Enter a numeric value in seconds, as a power of 2. For example, 6 means 2^6, or 64 seconds. The default is 6, and the minimum value is 4.
Max Poll
Sets the maximum polling interval. Enter a number in seconds, as a power of 2. For example, 10 means 2^10, or 1,024 seconds. The default is 10, and the maximum value is 17.
Force
Enable to force the addition of the NTP server, even if it is currently unreachable.
Storage Widget
Storage widget shows the pool configured as the system dataset pool, and allows users to select the storage pool they want to hold the system dataset.
The system dataset stores core files for debugging and keys for encrypted pools. It also stores Samba4 metadata, such as the user and group cache and share-level permissions.
System Dataset Pool shows all pool root datasets configured in the system.
If the system has one pool, TrueNAS configures that pool as the system dataset pool.
If your system has more than one pool, you can set the system dataset pool using the Select Pool dropdown.
Users can move the system dataset to an unencrypted pool or an encrypted pool without passphrases.
Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward.
You cannot move the system dataset to an encrypted pool with a passphrase set.
Run Reslivering At Higher Priority At Certain Times is not enabled by default. Selecting this option shows additional fields to set the time and date to resliver the system dataset pool disks.
Days of the Week shows a dropdown list of day options.
From and To set the time range in which a resliver can run.
Save implements setting changes.
Replication Widget
The Replication widget displays the number of replication tasks that can execute simultaneously on the system. It allows users to adjust the maximum number of replication tasks the system can perform simultaneously.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
Access Widget
The Access widget shows a list of all active sessions including the current logged-in user and the time it started.
The Session Timeout setting shows the number of minutes for the current session.
The Login Banner shows the custom text entered on the Access Settings screen. This text shows before the login screen.
When configured, users see the login banner and must click Continue to show the TrueNAS login splash screen.
Administrators can manage other active sessions and configure the session timeout for their accounts.
Terminate Other Sessions ends all sessions except the current session.
To end individual sessions, click the logout button next to that session.
You must check a confirmation box before the system allows you to end sessions.
The logout icon is inactive for the currently logged-in administrator session and active for any other current sessions.
It cannot be used to terminate the currently logged-in active administrator session.
Session Timeout shows the configured token duration for the current session (default is five minutes).
TrueNAS logs out user sessions that are inactive for longer than the configured token setting for the user.
New activity resets the token counter.
When the configured session timeout is exceeded, TrueNAS displays a Logout dialog with the exceeded ticket lifetime value and the time the session is scheduled to terminate.
If the configured session timeout is exceeded, TrueNAS displays a Logout dialog with the exceeded ticket lifetime value and the time the session is scheduled to terminate.
Select a value that fits your needs and security requirements.
Enter the value in seconds.
The default lifetime setting is 300 seconds or five minutes.
The maximum is 2147482 seconds or converting it to hours/minutes/seconds, 596 hours, 31 minutes, and 22 seconds.
If converting it to days/hours/minutes/seconds, 24 days, 20 hours, 31 minutes, and 22 seconds.
The Login Banner field allows specifying a text message that the system shows before the TrueNAS login splash screen displays.
Continue on the banner screen closes the screen, then shows the login splash screen.
The maximum length of the banner text is 4096 characters, including spaces. Long text wraps and banner text can use carriage returns to break up long messages to improve readability.
Leave Login Banner empty to show just the login screen without interruption by a banner screen.
TrueNAS Enterprise
Enterprise-licensed systems include the Allow Directory Service users to access WebUI option on the Access Settings screen.
After enabling this option, TrueNAS automatically creates a new entry, named as the domain admin group, in the Privileges screen table. For example, if the domain is ad03.mydomain.net, then you should see a group of that name listed as well as any of the groups AD creates on the system.
Allowed IP Addresses Widget
The Allowed IP Addresses widget displays IP addresses and networks added to the system that are allowed to use the API and UI.
If this list is empty, then all IP addresses are allowed to use the API and UI.
Configure opens the Allowed IP Addresses configuration screen.
Entering an IP address into the allowed IP address list denies access to the UI or API for all other IP addresses not listed.
Only use when limiting system access to a single or a limited number of IP addresses. Leave the list blank to allow all IP addresses.
Add, next to Allowed IP Addresses, adds an entry to the allowed IP Addresses list.
Ensure the first address and/or subnet includes your current client system.
Enter a specific IP address, for example, 192.168.1.1, for individual access, or use an IP address with a subnet mask, like 192.168.1.0/24, to define a range of addresses.
You can add as many addresses as needed.
Save retains setting changes and closes the screen..
A Restart Web Service dialog opens.
Confirm activates Continue. and Continue restarts the web UI and applies changes.
Self-Encrypting Drive Widget
TrueNAS Enterprise
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later).
SED configuration options are not visible in the TrueNAS Community Edition.
Community users wishing to implement SEDs can continue to do so using the command line sedutil-cli utility.
Note: Additional changes to SED management options in the TrueNAS UI ahead of the 25.04.0 release version, with documentation updates to follow.
The Self-Encrypting Drive (SED) widget shows when the system has self-encrypting drives, and shows the system ATA security user and password.
Configure opens the Isolated GPU PCI Ids screen, which allows users to isolate additional GPU devices.
Isolated GPU PCI IDs Configuration Screen
The Isolate GPU PCI IDs widget shows GPU devices added in TrueNAS.
Configure opens the configuration screen and allows you to isolate GPU devices for a virtual machine (VM).
To isolate a GPU, you must have at least two in your system; one allocated to the host system for system functions and/or applications, and the other available to isolate for use by a VM.
Select the GPU device ID from the dropdown list and click Save.
Isolated GPU devices are reserved for use by configured applications or a VM.
To allocate an isolated GPU device, select it while creating or editing the VM configuration.
When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM, and it becomes unavailable for any other allocations.
Global Two-Factor Authentication Widget
The Global Two Factor Authentication widget shows the status of global two-facator authentication, the tolerance window, and the status of two-factor authentication in SSH sessions. It provides access to the configuration screen that allows you to set up two-factor authentication (2FA) for your system.
Select to prompt users to set up 2FA for the system. When enabled, users without 2FA configured are prompted to set it up on their next login. Users can skip the initial setup if needed.
Window
Enter the number of valid authentication codes (tolerance window). Extends code validity beyond the current to the previous code(s) based on the number entered. For example, setting this to 1 means the current and previous codes are valid. If the previous code is a and the current code is b, then both codes are valid. If set to 2, the current code (c) and the two previous codes (a and b) are valid. Setting this to 3 works the same. Extending the window is useful in high-latency situations.
Enable Two-Factor Auth for SSH
Select to enable 2FA for system SSH access. Leave this disabled until you complete a successful test of 2FA with the UI.
System Security Widget
TrueNAS Enterprise
The System Security widget allows administrators of Enterprise-licensed systems to enable or disable FIPS 140-2 compliant algorithms, general-purpose OS STIG compliance, and other administrator account rules.
Changing FIPS or STIG settings requires a system restart to apply the setting changes.
High Availability (HA) systems restart the standby controller and then show a prompt to failover and restart the primary controller.
The Enable FIPS toggle enables or disables enforcement.
The Enable General Purpose OS STIG compatibility mode toggle enables or disables the STIG compliance implementation.
Requires two-factor authentication for an admin user with full permissions before enabling STIG compatibility.
Administrator Password settings
Name
Description
Min Password Age
Minimum number of days a password must be used before it can be changed.
Max Password Age
Maximum number of days a password can be used before it must be changed. TrueNAS warns users of password expiration seven days prior to the set expiration date.
Password Complexity Ruleset
Defines the required character types for administrator passwords. Choose between Upper, Lower, Number, and Special character type requirements.
Min Password Length
Define how many characters must be present in an administrator password. The default required minimum is 8 characters.
Password History Length
Define how many previously used passwords to remember. Prevents administrators from reusing passwords when updating credentials. Requires an integer between 1 and 10.
Failover Widget
TrueNAS Enterprise
The Failover widget shows only on Enterprise-licensed HA systems.
It shows the status of failover, the default controller, and the network timeout before TrueNAS initiates failover.
Configure opens the Failover configuration screen.
Failover Configuration Screen
The Failover screen shows settings used on TrueNAS Enterprise (HA) systems to turn the failover function on or off, sync the primary and standby controllers, and allow administrator users to configure failover. The main menu option and screen only display on Enterprise (HA) systems with the correct license applied.
Set the system to turn on failover. Leave clear to disable failover.
Default TrueNAS controller
Sets the current active controller to be the default controller when both TrueNAS controllers are online and HA is enabled. To change the default TrueNAS controller, leave unselected on the default TrueNAS controller and allow the system to fail over. This process briefly interrupts system services.
Network Timeout Before Initiating Failover
Sets the number in seconds to wait after a network failure before triggering a failover. The default value is 0, which means failover occurs immediately or after two seconds when the system is using a link aggregate.
Sync To Peer
Initiates a sync operation that copies over the primary controller configuration to the standby controller. Opens the Sync To Peer dialog to confirm the operation.
Sync From Peer
Initiates a sync operation that copies over the standby controller configuration to the primary controller.
Sync To or From Peer
Sync To Peer and Sync From Peer buttons each open a confirmation dialog before TrueNAS performs the operation requested.
Setting
Description
Reboot standby TrueNAS controller
Select to cause the standby controller to restart after the sync operation completes.
Confirm
Select to confirm you want to perform the sync-to-peer operation.
Proceed
Begins the sync operation.
Boot
The Boot Environment screen lists boot environments created by updates performed on the system.
It has options for monitoring and maintaining the TrueNAS install pool and disks, and includes managing OS restore points(called boot environments) for the TrueNAS system.
System updates create a new boot environment and carry forward core configuration, but other state changes do not carry forward to new environments. Switching between environments frequently creates configuration divergence and splits audit logs between environments.
Screen options shown at the top right of the screen are:
Stats/Settings - Opens the Stats/Settings window with the Boot pool Condition, Size and Used, and Last Scrub Run statistics for the operating system device, and provides the option to change the default duration between the operating system device scrubs from every seven days to a new duration in days.
Boot Pool Status - Opens the Boot Pool Status screen that displays the status of each device in the operating system device (boot pool), options for managing boot-pool devices, and lists any read, write, or checksum errors.
Scrub Boot Pool - Opens the Scrub dialog. Performs a manual data integrity check (scrub) of the operating system device.
Each boot environment listed in the table shows these columns:
Name - Shows the name of the boot entry as it appears in the boot menu.
Active - Indicates the environment that boots by default if a boot environment is not active. Activated environment displays Non/Reboot.
Date Created - Shows the creation date and time.
Used Space - Shows the amount of disk space the boot environment occupies.
Keep - Indicates TrueNAS can delete this boot environment when a system update does not have enough space to proceed.
Each boot environment row on the table shows icon buttons for available actions.
Setting
Description
ActivateActivate
Shows for environments not marked as active. Opens the Activate dialog. Changes the System Boot Environment screen table Active stated to Now after booting the system into this environment. Indicates the current boot environment.
CloneClone
Opens the Clone Boot Environment screen. Copies the selected boot environment into a new entry. Enter a new name using only alphanumeric characters and/or the allowed dashes (-), underscores (_), and periods (.) special characters.
DeleteDelete
Opens the Delete dialog. It does not display if the boot environment is activated. You cannot delete the default or activated boot environment. Removes the highlighted entry and removes that entry from the boot menu.
KeepKeep
Opens the Keep dialog, and toggles the boot environment action to Unkeep. Use to prevent the TrueNAS updater from automatically deleting the environment to make more space for a new environment when there is insufficient space to complete the update.
Boot Pool Status
The System > Boot > Boot Pool Status screen shows the status of the current boot pool.
It includes the current status, the path, and the number of read, write, and checksum errors.
The Attach window setting, accessed from the Boot Status screen, specifies a device as the disk member to attach to the boot environment, and how much of the device it can use.
Member Disk shows a dropdown list of devices to select.
Save makes the change and closes the window.
Clone Boot Environment Screen
Each time the system updates to a new software release, it creates a new boot environment. The CloneClone icon button opens the Clone Boot Environment screen where you can clone an existing boot environment to create an operating system restore point.
Name - The name of the new cloned boot environment. The name can use upper and lowercase alphanumeric and special characters dash (-), underscore (_), and periods (.).
Source shows the selected boot environment to be cloned.
Batch Operations
Select the checkbox to the left of each boot environment to show the Batch Operations option at the top of the screen. Currently only Delete is available as a batch operation.
System > Services displays each system component that runs continuously in the background. These typically control data-sharing or other external access to the system. Individual services have configuration screens, activation buttons, and you can set them to run automatically.
The Start Automatically toggle sets the service to start after the system restarts.
The Status column displays the service status with a badge (Stopped or Running) and a play_circle start or stop_circle stop button. The start button starts the service and the stop button stops it if it is running. It is recommended to stop services before changing configuration settings.
Contents
FTP Service Screen: Provides information on the FTP services screens and settings.
SSH Service Screen: Provides information on the SSH service screens and settings.
UPS Services Screen: Provides information on the UPS service screen settings.
FTP Service Screen
The File Transfer Protocol (FTP) is a simple option for data transfers.
The SSH options provide secure transfer methods for critical objects like configuration files, while the Trivial FTP options provide simple file transfer methods for non-critical files.
The FTP service has basic and advanced setting options.
Click the edit for FTP to open the Basic Settings configuration screen.
FTP Basic Settings
To configure FTP, go to System > Services and find FTP, then click edit.
Enter the maximum number of connections per IP address. 0 is unlimited.
Login Attempts
Enter the maximum attempts before the client disconnects. Increase if users are prone to misspellings or typos.
Notransfer Timeout
Enter the maximum number of seconds a client is allowed to spend connected, after authentication, without issuing a command which results in creating an active or passive data connection (sending/receiving a file or receiving a directory listing).
Timeout
Enter the maximum client idle time in seconds before disconnecting. The default value is 600 seconds.
FTP Advanced Settings
Advanced Settings include the General Options on the Basic Settings configuration screen and allow you to specify access permissions, TLS settings, bandwidth, and other settings to customize FTP access.
Access settings specify user login, file, and directory access permissions.
Settings
Description
Always Chroot
Only allows users to access their home directory if they are in the wheel group. This option increases security risk. To confine FTP sessions to a local user home directory, enable chroot and select Allow Local User Login.
Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Allow Anonymous Login
Select to allow anonymous FTP logins with access to the directory specified in Path. Selecting this displays the Path field. Enter or browse the location to populate the field.
Allow Local User Login
Select to allow any local user to log in. Only members of the ftp group may log in by default.
Require IDENT Authentication
Select to require IDENT authentication. Setting this option results in timeouts when IDENT is not running on the client.
File Permissions
Select the default permissions for newly created files.
Directory Permissions
Select the default permissions for newly created directories.
TLS settings specify the authentication methods, such as if you want to encrypt the data you transfer across the Internet.
Settings
Description
Enable TLS
Select to allow encrypted connections. Requires a certificate (created or imported using Credentials > Certificates).
Certificate
Select the SSL certificate for TLS FTP connections from the dropdown list. Click Manage Certificates to go to Credentials > Certificates.
TLS Policy
Select the policy from the dropdown list of options. Options are On, off, Data, !Data, Auth, Ctrl, Ctrl + Data, Ctrl +!Data, Auth + Data or Auth +!Data. Defines whether the control channel, data channel, both channels, or neither channel of an FTP session must occur over SSL/TLS. The policies are described here.
TLS Allow Client Renegotiations
Select to allow client renegotiation. We do not recommend this option. Setting this option breaks several security measures. See mod_tls for details.
TLS Allow Dot Login
TrueNAS checks the user home directory for a .tlslogin file containing one or more PEM-encoded certificates. If not found, the user must enter their password.
TLS Allow Per User
Select to allow sending a user password unencrypted.
TLS Common Name Required
Select to require the common name in the certificate to match the FQDN of the host.
TLS Enable Diagnostics
Select for more verbose logging, which is helpful when troubleshooting a connection.
TLS Export Certificate Data
Select to export the certificate environment variables.
TLS No Certificate Request
Select if the client cannot connect, likely because the client server is not correctly handling the server certificate request.
TLS No Empty Fragments
Not recommended. This option bypasses a security mechanism.
TLS No Session Reuse Required
This option reduces connection security. Only use it if the client does not understand reused SSL sessions.
TLS Export Standard Vars
Select to set several environment variables.
TLS DNS Name Required
Select to require the client DNS name to resolve to its IP address and the cert contain the same DNS name.
TLS IP Address Required
Select to require the client certificate IP address to match the client IP address.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Settings
Description
Minimum Passive Port
Enter a numeric value. Used by clients in PASV mode. A default of 0 means any port above 1023.
Maximum Passive Port
Enter a numeric value. Used by clients in PASV mode. A default of 0 means any port above 1023.
Enable FXP
Select to enable the File eXchange Protocol (FXP). We do not recommend FXP since it leaves the server vulnerable to FTP bounce attacks.
Allow Transfer Resumption
Select to allow FTP clients to resume interrupted transfers.
Perform Reverse DNS Lookups
Select to allow performing reverse DNS lookups on client IPs. This option causes long delays if you do not configure reverse DNS.
Masquerade Address
Enter a public IP address or host name. Use when FTP clients cannot connect through a NAT device.
Display Login
Enter a message that displays to local login users after authentication. Anonymous login users do not see this message.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
Settings
Description
Local User Upload Bandwidth: (Examples: 500 KiB, 500M, 2 TB)
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Local User Download Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Anonymous User Upload Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Anonymous User Download Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
iSCSI Services Screen
The iSCSI screen displays settings to configure iSCSI block shares.
About the Block (iSCSI) Sharing Protocol
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations.
IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack.
The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack.
Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance clould suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
OSI Layer Number
OSI Layer Name
Activity as it relates to iSCSI
7
Application
An application tells the CPU that it needs to write data to non-volatile storage.
6
Presentation
OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage.
5
Session
Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU).
4
Transport
OSI encapsulates the iSCSI PDU within a TCP segment.
3
Network
OSI encapsulates the TCP segment within an IP packet.
2
Data
OSI encapsulates the IP packet within the Ethernet frame.
1
Physical
The Ethernet frame transmits as bits (zeros and ones).
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing.
Block sharing provides the benefit of block-level access to data on the TrueNAS.
iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
iSCSI Terminology
Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively.
iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network.
The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes.
It also requires that each node is given a unique iSCSI name.
To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
dash (-)
dot (.)
colon (:)
lower case characters (a…z).
Upper-case characters must be mapped to their related lower-case counterparts.
digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN.
The result is an iSCSI connection that emulates a connection to a SCSI hard disk.
Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs.
When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size.
This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU).
A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways.
Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames.
Systems administrators should also account for the impact on host CPU utilization.
Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment.
Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.
TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system.
HA storage clusters can provide multiple paths to the same storage.
For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer.
The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage.
If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage.
When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.
iSCSI Configuration Methods
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores.
This is all managed through the vCenter web interface.
TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares.
This requires creating and populating zvol block devices with data, then setting up the iSCSI Share.
TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
iSCSI Configuration Screens
Target Global Configuration Screen
The Target Global Configuration displays configuration settings that apply to all iSCSI shares.
There are no add, edit, or delete options for this screen.
It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
Setting
Description
Base Name
Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
ISNS Servers
Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Pool Available Space Threshold (%)
Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port
The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators.
Asymmetric Logical Unit Access (ALUA)
Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server.
Portals Screens
Initiators Groups Screen
Authorized Access Screen
Targets Screen
Extents Screen
Associated Targets Screen
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user.
The Add and Edit screens display the same settings.
Setting
Description
Target
Required. Select an existing target.
LUN ID
Select the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID.
Extent
Required. Select an existing extent.
NFS Services Screen
The System > Services screen includes two options on the NFS service row:
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
NFS Service Screen
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
You can access it from System > Services screen.
Locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
Sets the IP addresses the share (SMB or NFS) listens on. Leaving empty listens on all available addresses. Must configure static IPs on the interface to show one the list.
Calculate number of threads dynamically
Automatically sets the number of threads used by the kernel NFS server.
Specify number of threads manually
Sets the optimal thread count for the kernel NFS server. Shows after disabling Calculate number of threads dynamically.
NFSv4 Settings
Setting
Description
Enabled Protocols
Sets the NFS service protocol to NFSv3, NFSv4, or both. When NFSv4 is selected, NFSv3 ownership model for NFSv4 clears, allowing you to select or leave it clear.
NFSv4 DNS Domain
Overrides the default DNS domain for NFSv4. Specifies the domain in idmapd.conf. Select to use a value to override the default DNS domain name for NFSv4. When AD is joined and healthy, NFSv4 is selected as an enabled protocol, setting this shows Add SPN to the right of Save.
NFSv3 ownership model for NFSv4
Enables NFSv4 ACL support without requiring the client and the server to sync users and groups. Becomes selectable after selecting NFSv4. Deactivates Manage Groups Server-side.
Require Kerberos for NFSv4
Forces NFS shares to fail if a Kerberos ticket is unavailable.
SPN Entry Settings
ADD SPN only shows on the NFS service screen when AD is joined and hhealty, NFSv4 is selected in Enabled Protocols, and Require Kerberos for NFSv4 is enabled.
After saving settings and reopening the NFS service screen, the Add SPN button becomes active. Clicking this opens the first Add Kerberos SPN Entry dialog. Clicking Yes in the fist dialog opens the second Add Kerberos SPN Entry dialog where you add the credentials.
Specifies the AD admin account credential name with the rights to create SPNs in the domain, commonly a domain admin for delegated account granted write servicePrincipalName permissions on the relevant computer object. This is not the TrueNAS administrator account name.
Password
Specifies crendtial password for the AD admin account as mentioned in Name.
Improves NFS performance and reduce CPU overhead. This setting requires an Enterprise licensed system with an RDMA capable NIC.
Allow non-root mount
Allows serving non-root mount requests. Only enable if required by the NFS client.
Manage Groups Server-side
Allows the server to determine group IDs via server-side lookups instead of client-provided information. Supports more than 16 groups and provides more accurate memberships. Equivalent to the --manage-gids flag for rpc.mountd.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
We recommend using the default NFS settings unless you require specific settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
SMB Service Screen
The System > Services screen includes three options on the SMB service row:
Click Save or Cancel to close the configuration screen and return to the Services screen.
Basic Settings
Setting
Description
NetBIOS Name
Enter the NetBIOS name for the TrueNAS system (maximum 15 characters). Cannot contain: `\ / : * ? " < >
NetBIOS Alias
Enter alias names (maximum 15 characters each). Cannot contain: `\ / : * ? " < >
Workgroup
Enter a name that matches the Windows workgroup name (maximum 15 characters). Cannot contain: `\ / : * ? " < >
Description
(Optional) Enter any notes or descriptive details about the service configuration.
Enable SMB1 support
Select to allow legacy SMB1 clients to connect to the server (see caution below). SMB audit logging does not work when using SMB1.
NTLMv1 Auth
Off by default. Select to allow smbd attempts to authenticate users with the insecure and vulnerable NTLMv1 encryption. This setting allows backward compatibility with older versions of Windows, but we do not recommend it. Do not use on untrusted networks.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
Select the character set to use internally from the dropdown list of options. UTF-8 is standard for most systems as it supports all characters in all languages.
Transport Encryption Behavior
Select the option for the level of transport encryption to implement. Options and behaviors:
Default - follow upstream/TrueNAS default
Negotiate - only encrypt transport if explicitly requested by the SMB client
Desired - encrypt transport if supported by client during session negotiation
Required - always encrypt transport (rejecting access if client does not support encryption - incompatible with SMB1 server enable_smb1)
the TrueNAS and Samba default behavior allows SMB clients to negotiate different encryption levels for SMB shares. When set to Default, there is no technical limitation preventing an SMB client from negotiating an encrypted session if it is required. Default enables negotiating encryption but does not turn on data encryption globally per share. For more information on SMB1 and SMB2 session or per-share encryption, see Samba Server SMB Encrypt(s). For more information on using Windows client-side SMB signing, see Windows SMB Signing Policies.
Use Debug
Select to log more detailed information about SMB. By default, TrueNAS logs error and warning-level messages. We do not recommend enabling debug logging for production servers as it can generate large log files and impact performance.
Use Syslog Only
Select to log authentication failures in /var/log/messages instead of the default /var/log/samba4/log.smbd.
Local Master
Selected by default and determines if the system participates in a browser election. Leave cleared when the network contains an Active Directory server or when Vista or Windows 7 machines are present.
Enable Apple SMB2/3 Protocol Extensions
Select to allow MacOS to use these protocol extensions to improve the performance and behavioral characteristics of SMB shares. TrueNAS requires Apple SMB2/3 protocol extensions for Time Machine support and Final Cut Pro Storage Share workflows. You must enable this setting before creating shares with the Time Machine Share or Final Cut Pro Storage Share purpose options.
Multichannel
SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance. SMB multichannel does not function if you combine NICs into a LAGG.
Enter or select members from the dropdown list. Members of this group are local administrators and automatically have privileges to take ownership of any file in an SMB share, reset permissions, and administer the SMB server through the Computer Management MMC snap-in.
Guest Account
Select the account for guest access from the dropdown list. The default is nobody. The selected account must have permission for the shared pool or dataset. To adjust permissions, edit the dataset Access Control List (ACL), add a new entry for the chosen guest account, and configure the permissions in that entry. If you delete the selected Guest Account, the field resets to nobody.
File Mask
Overrides default 0664 file creation mask, which creates files with read and write access for everybody.
Directory Mask
Overrides default directory creation mask of 0775, which grants everyone directory read, write, and execute access.
Bind IP Addresses
Click Add to specify static IP addresses that SMB listens on for connections. Select an IP address from the dropdown list for each entry. Leaving this empty defaults to listening on all active interfaces.
SNMP Service Screen
The Service > SNMP screen settings configure SNMP (Simple Network Management Protocol) that monitors network-attached devices for conditions that warrant administrative attention.
Click the edit to open the Services > SNMP configuration screen.
General Options
SNMP v3 Options
Setting
Description
Location
Enter the location of the system.
Contact
Enter the email address to receive SNMP service messages.
Community
Enter a community other than the default public to increase system security. Value can only contain alphanumeric characters, underscores (_), dashes (-), periods (.), and spaces. Not required and can leave this empty for SNMPv3 networks.
SNMP v3 Support Options
Setting
Description
SNMP v3 Support
Select to to enable support for SNMP version 3 and display the SNMP v3 setting fields. See snmpd.conf(5) for configuration details.
Username
Enter a user name to register with this service.
Authentication Type
Select an authentication method: — for none, SHA, or MD5 from the dropdown list.
Password
Enter a password of at least eight characters.
Privacy Protocol
Select a privacy protocol: — for none, AES, or DES from the dropdown list.
Privacy Passphrase
Enter a separate privacy passphrase. Password is used when this is left empty.
Other Options
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Setting
Description
Auxiliary Parameters
Enter any additional snmpd.conf options. Add one option for each line.
Expose zilstat via SNMP
Select to enable. If enabled this option might have performance implications on your pools.
Log Level
Select how many log entries to create. Dropdown list options are Emergency, Alert, Critical, Error, Warning, Notice, Info and Debug.
SSH Service Screen
The System > Services > SSH screen allows you to set up SSH service on TrueNAS.
Click edit to open the Services > SSH configuration screen.
Allowing external connections to TrueNAS is a security vulnerability!
Do not enable SSH unless you require external connections.
See Security Recommendations for more security considerations when using SSH.
You must also configure SSH backup credentials to allow SSH access. See SSH Screens for more information.
SSH Basic Settings Options
The Basic Settings options display by default when you edit the SSH service.
Enter the port number for SSH connection requests.
Password Login Groups
List of TrueNAS account groups allowed to use a password for logging in to the system with SSH. Click in the field to see a list of current account groups. Begin typing in the field to filter the groups list. Left click a list item to add it to the field. Click the for an entry to remove it from the field.
Allow Password Authentication
Select to enable and allow using a password to authenticate the SSH login. If disabled (not selected), authentication changes to require SSH keys for all users. This requires additional setup for both the SSH client and server. Warning: when directory services are enabled, this setting grants access to all users the directory service imported.
Allow Kerberos Authentication
Select to allow Kerberos authentication. Ensure valid entries exist in Directory Services > Kerberos Realms and Directory Services > Kerberos Keytabs and the system can communicate with the Kerberos domain controller before enabling this option.
Allow TCP Port Forwarding
Select to allow users to bypass firewall restrictions using SSH port forwarding. For best security, leave disabled and deny shell access to users.
SSH Advanced Settings Options
Advanced Settings include the General Options settings. Advanced settings specify bind interfaces, SFTP settings, ciphers and any additional parameters you want to use.
Select the network interface configured on your system for SSH to listen on from the dropdown list. Leave all options unselected for SSH to listen on all interfaces.
Compress Connections
Select to attempt to reduce latency over slow networks.
SFTP Log Level
Select the syslog(3) level of the SFTP server from the dropdown list. Options are Quiet, Fatal, Error, Info, Verbose, Debug, Debug2 or Debug3.
SFTP Log Facility
Select the syslog(3) facility of the SFTP server option from the dropdown list. Options are Daemon, User, Auth and Local 0 through Local7.
Weak Ciphers
Select a cipher from the dropdown list. Options are None or AES128-CBC. To allow more ciphers for sshd(8) in addition to the defaults in sshd_config(5). Use None to allow unencrypted SSH connections. Use AES128-CBC to allow the 128-bit Advanced Encryption Standard. WARNING: These ciphers are security vulnerabilities. Only allow them in a secure network environment.
Auxiliary Parameters
Enter any sshd_config(5) options not covered in this screen. Enter one option per line. Parameters added are case-sensitive.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
SSH auxiliary parameters are unsupported.
Certain configurations can prevent the SSH service from starting.
UPS Services Screen
The Services > UPS screen settings specify connection, shutdown and other settings to configure UPS service for servers running TrueNAS.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support.
For supported device and driver information, see their hardware compatibility list.
Further device-specific compatibility information is available from the NUT Devices Dumps Library.
Required. Type a description for the UPS device. You can use alphanumeric, period (.), comma (,), hyphen (-), and underscore (_) characters.
UPS Mode
Select the either Master or Slave mode from the dropdown list. Select Master if the UPS is plugged directly into the system serial port, or Slave to shut down this system before the master system. Slave displays the Remote Hostname and Remote Port fields, and removes the Driver field. The UPS remains the last item to shut down. See the Network UPS Tools Overview.
Remote Host
Required. Enter a valid IP address for the remote UPS master system. This field displays only when UPS Mode is set to Slave.
Remote Port
Required. Enter the open network port number of the UPS master system. The default port is 3493. This field displays only when UPS Mode is set to Slave.
Driver
Required. Enter or select the device driver from the dropdown list. See the Network UPS Tools compatibility list for a list of supported UPS devices. This field displays only when UPS Mode is set to Master.
Port or Hostname
Required. Enter or select the serial or USB port connected to the UPS from the dropdown list. Options include a list of port on your system and auto. Select auto to automatically detect and manage the USB port settings. When selecting an SNMP driver, enter the IP address or host name of the SNMP UPS device.
Monitor Settings
Monitor settings specify the primary username and password, other users that have administrative access to the UPS service, and whether the default configuration listens on all interfaces.
Setting
Description
Monitor User
Enter a user to associate with this service. Keeping the default is recommended.
Monitor Password
Change the default password to improve system security. The new password cannot include a space or #.
Extra Users
Enter accounts that have administrative access. See upsd.users(5) for examples.
Remote Monitor
Select to have the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.
Shutdown Settings
Shutdown settings specify the UPS shutdown mode, command, and timer for the UPS service.
Select the battery option to used when the UPS initiates shutdown from the dropdown list. Options are UPS reaches low battery or UPS goes on battery.
Shutdown Timer
Enter a value in seconds for the UPS to wait before initiating shutdown. Shutdown does not occur if power is restored while the timer is counting down. This value only applies when Shutdown Mode is set to UPS goes on battery.
Shutdown Command
Enter a command to shut down the system when either battery power is low or the shutdown timer ends.
Power off UPS
Select to power off the UPS after shutting down the system.
Other Options Settings
Other Options settings specify warning and host sync times, a description for the UPS, and any additional parameters you want to apply to the UPS service.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Setting
Description
No Communication Warning Time
Enter the number of seconds to wait before alerting that the service cannot reach any UPS. Warnings continue until the situation is fixed.
Host Sync
Upsmon waits up to this many seconds in master mode for the slaves to disconnect during a shutdown situation.
TrueNAS System > Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information.
When the user Shell setting is set to TrueNAS Console, the Shell screen opens and shows the TrueNAS Console Setup menu.
The Font Sizeremove and add buttons adjust the displayed text size in the Shell.
The shell window stores the command history for the current session.
Leaving the Shell screen clears the command history.
Alert Settings Screen
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies.
To access this screen, click the notifications icon, then click the settings icon and select Alert Settings on the dropdown list.
Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
Add/Edit Alert Service Screen
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default.
To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the more_vert icon for the service, and then click Edit to display the Edit Alert Service screen.
Name and Type Settings
Setting
Description
Name
Enter a name for the new alert service.
Enabled
Clear the checkmark to disable this service without deleting it.
Type
Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS.
Level
Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. TrueNAS sends alert notifications for all warnings matching and above the selected level. For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Alert Service Types
AWS SNS
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
Authentication Settings
Setting
Description
API Key
Enter the API key. Find the API key by signing into the OpsGenie web interface and going to Integrations/Configured Integrations. Click the desired integration, Settings, and read the API Key field.
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
Authentication Settings
Setting
Description
Hostname
Enter the hostname or IP address of the system to receive SNMP trap notifications.
Port
Enter the UDP port number on the system receiving SNMP trap notifications. The default is 162.
SNMPv3 Security Model
Select to enable the SNMPv3 security model.
SNMP Community
Enter the network community string. The community string acts like a user ID or password. A user with the correct community string can access network information. The default is public. For more information, see What is an SNMP Community String?.
Telegram
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Enter a list of chat IDs separated by a space ( ), comma (,), or semicolon (;). To find your chat ID, send a message to the bot, group, or channel and visit https://core.telegram.org/bots/api#getting-updates.
VictorOPS
Click here for more information
Select VictorOps from the Type dropdown list to display VictorOps authentication settings.
Use the Category dropdown list to display alert settings for each category.
Applications
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Click here for more information
You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.
Certificates
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Click here for more information
You can customize alert settings for when a certificate expires, a certificate parsing fails, a certificate revokes, and the web UI HTTPS certificate setup fails.
Directory Service
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
Click here for more information
You can customize alert settings for when the Active Directory bind is unhealthy, Active Directory domain validation fails, the domain is offline, and the LDAP bind bind is unhealthy.
High Availability Settings
TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only displays on the list of alerts for dual-controller High-Availability systems with an Enterprise license applied.
Click here for more information
You can customize alert settings for when an automatic sync to peer fails, disks are missing on the active and/or standby controller, the system fails to check failover status with the other controller, syncing operations fail such as encryption keys to peer and KMIP keys to peer, the failover interface is not found, and when a failover action fails.
Hardware
Hardware alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.
Click here for more information
You can customize alert settings for when disk temperature is too hot, disk(s) format with the data integrity feature, a selftest fails, erase cycle count is high, IPMI has system events, the IPMI system event log space is low, JBOF removal requires reboot, spare block reserve is low, and uncorrected errors are detected.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Key Management Interoperability Protocol (KMIP)
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Click here for more information
You can customize alert settings for when the system fails to communicate, sync the SED global password, and sync keys with the KMIP server.
Network
Network alert settings apply to network interfaces configured on your TrueNAS.
Click here for more information
You can customize alert settings for when ports are not active on the LAGG interface and when the LAGG interface has no active ports.
Reporting
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Click here for more information
You can customize alert settings for when netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.
Sharing
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Click here for more information
You can customize alert settings for when a deprecated service is running, IP addresses bound to an iSCSI portal are not found, NFS services cannot bind to specific IP addresses using 0.0.0.0, and the system cannot resolve NFS share references hosts.
You can also customize alerts for when NTLMv1 attempts authentication in the last 24 hours, SMB1 connections to TrueNAS server are performed in the last 24 hours, and a share is unavailable because it uses a locked dataset.
Storage
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
Click here for more information
You can customize alert settings for when a dataset exceeds standard and critical quotas, a pool has new available feature flags, pool space usage exceeds 70, 80, or 90 percent, and pool status is not healthy.
You can change alert settings for when a pool consumes USB disks, a scrub pauses, and too many snapshots exist.
System
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.
Click here for more information
You can customize alert settings for when the admin user is overridden, the boot pool is unhealthy, the system dataset has core files, a device slows down pool I/O, NTP health checks fail, and TrueCommand API keys are disabled or need confirmation.
You can also change alert settings for when SSH logins fail, the system is not ready for Kdump, the web UI cannot bind to a configured address, TrueCommand fails health checks, the system restarts off schedule, and update are available, failed, or not applied.
Tasks
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
Click here for more information
You can customize alert settings for when cloud sync tasks, VMWare snapshot creation, login, and deletion, replication, rsync tasks, scrubs, and snapshot tasks fail in general or due to locked datasets.
You can also change alert settings for when replication, rsync tasks, and scrubs succeed.
UPS
UPS alert settings apply to a UPS connected to your TrueNAS.
Click here for more information
You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.
Alert Warning Levels
Use the Set Warning Level dropdown list to customize alert importance.
Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
TrueNAS sends alert notifications for all warnings matching and above the selected level
For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Level
Icon
Alert Notification?
INFO
No
NOTICE
Yes
WARNING
Yes
ERROR
Yes
CRITICAL
Yes
ALERT
Yes
EMERGENCY
Yes
Alert Frequency
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
View Enclosure Screen (TrueNAS Systems Only)
The View Enclosure screen only displays on compatible TrueNAS hardware.
The UI options to select System > Enclosure is not present on incompatible systems.
The System Information widget on the main Dashboard displays an image of the host TrueNAS system.
Hover the mouse over the image to see the View Enclosure label.
Click anywhere on the system image to open the View Enclosure screen.
The View Enclosure screen displays an image of the TrueNAS platform.
Additional information about storage pools, drives, and other hardware components is available through a variety of elements and buttons.
The Elements button at the top right of the View Enclosure screen displays a dropdown list of options to view information about the system or expansion shelf.
The options vary by TrueNAS platform, if the system is connected to expansion shelves, and if you have an expansion shelf image selected instead of the main system.
All TrueNAS systems include the Disks option. TrueNAS systems with expansion shelves include the Temperature, Power Supply, and Voltage options.
The expansion shelf includes the Disks, Cooling, Services, Power Supply, SAS, Temperature, and Voltage options.
Each option displays a table with readings from the system’s internal components taken over a period of time.
Change Enclosure Label
Edit Label displays for the main system (except TrueNAS Minis) and expansion shelves.
Edit Label opens the Change Enclosure Label window.
Type a name or description for the system and click Save to apply the label.
To simplify system maintenance, use labels that help identify the physical location of the system, such as ES102 Rack D5 U20.
Reset to Default restores the default name for the system.
System Image Screens
System images display the front view of the system by default.
System image screens include options to change the information on the screen:
Show Pools shows disks highlighted in pools on the system image.
Show Status shows healthy or failed disks in the system and a status indicator color legend.
Show Expander Status shows a SAS expander status indicator for systems with one or more expander.
TrueNAS Mini Enclosure Screens
TrueNAS Mini systems display the front view of the system chassis.
Pool information displays at the top of the screen.
The drive bay number and disk label displays to the left of the image and the status to the right of the image.
The Disk Overview section provides general details about the system drive hardware and capacity.
Drive Temperatures displays current readings for each drive in the system.
The right side of the screen includes smaller thumbnail images of both the main system and any expansion shelves connected to the system.
A blue vertical line to the left of the thumbnail image indicates the selected enclosure.
Both the system and expansion shelf images show installed disk locations.
Click on a drive image in the system or expansion shelf to display a drive information screen for that drive.
Disk drive information includes the system pool, disk status, hardware details, and stats for the drive.
Identify on disk detail screens turns on the LED indicator located on a physical drive bay in the system server.
This helps to identify the physical drive bay that corresponds to the TrueNAS identification number for that drive.
Select the drive on the image and then click Identify.
Go to the location of the system server to locate the drive bay with the LED indication turned on, then check the drive location on the View Enclosure screen.
TrueNAS Mini and R30 systems do not include the IDENTIFY function.
The expansion shelf image varies based on the type of expansion shelf installed.
The disk information displayed is the same as for disks in the main system chassis.
The Audit screen lists log entries in a table that shows:
Service - The service performing the operation (e.g. Middleware).
User - Name of the user (login or internal process user (e.g. admin, UNAUTHENTICATED, etc.)).
Timestamp - Date and time the event occurred.
Event - Name of the process (e.g. Authentication, Method Call, etc.).
Event Data - A short description of the operation (e.g. Credentials: Password Login, System advanced update, etc.).
The Service dropdown at the top of the screen filters audit entries by service type. Options include SMB, Middleware, Sudo, and System. Select a specific service to view only entries for that service. When no service is selected, the screen displays entries from all services.
Audit Settings opens the System > Advanced Settings screen showing the Audit widget.
For more information on configuring audit settings, see Advanced Settings Screen.
The Search field shows the Switch to Advanced option that replaces the default basic search with the advanced search option.
The advanced search option allows entering filter parameters to narrow results to a specific type of record.
Click in the Search field to see the advanced filter options in advanced search mode.
Switch to Advanced toggles to Switch to Basic that reverts the search operation to the default simple word search method.
Clicking in the Search field does not show search filter options in basic search mode.
Search starts the search operation based on the search parameters entered.
Export dropdown exports audit log records in multiple formats. Select CSV, JSON, or YAML to generate a compressed file (tar.gz format) that downloads to your browser’s default download location. The export includes all audit entries that match the current filter settings.
Audit Screen Log Details Widgets
The Audit screen shows two widgets for a selected record in the audit table:
Metadata - Shows the selected audit record properties Audit ID, Version, and Session ID.
Event Data - Shows the selected audit record method, a description of the recorded event, authentication status, and authorization information.
The data varies based on the type of event.
The Copy to Clipboard icon on the Event Data widget copies the fields listed on the Event Data widget formatted as straight text or a JSON file record that you can paste into any text editor.
API Reference
The TrueNAS REST API is removed in TrueNAS 27.
Systems still using the REST API must migrate to the WebSocket API before upgrading.
Starting with TrueNAS 25.10.1, the system displays alerts when deprecated REST API endpoints are accessed to help identify integrations that require migration to the JSON-RPC 2.0 over WebSocket API.
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.
API Documentation
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 midclt and 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.
Viewing API Documentation
There are several ways to view TrueNAS API documentation:
In the web interface, click laptopMy API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen.
Click API Docs on the User API Keys or User screen to access the TrueNAS API documentation built into the system.
A new browser window opens, showing the API documentation Table of Contents.
Append /api/docs/ to your TrueNAS host name or IP address in a browser to access the API documentation.
Go to the API Docs website and use the dropdown to view documentation for a specific TrueNAS (and API) version.
API Access
User-linked API access keys allow 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.