Back to Docs Hub
TrueNAS 27 (Early)
Nightly Development - TrueNAS 27
TrueNAS 27 is currently in active development to bring many new features and improvements to the TrueNAS experience.
Check back for more information.
Back to Docs Hub
Getting Started
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.
TrueNAS 27 Development Notes
This page tracks the latest development roadmap and notes for TrueNAS 27, the next major version of TrueNAS. Nightly builds are early-stage development software intended for testing and feedback — not production use. See the Software Development Life Cycle for an overview of TrueNAS release stages and versioning.
See the stable 25.10 (Goldeye) or pre-release TrueNAS 26 release notes for information relating to those versions.
Feature Deprecations
As part of security hardening and improving feature maintainability, there are occasions when TrueNAS SCALE features must be deprecated and removed.
This page tracks features removed in 27 and features deprecated in 27 for removal in future versions. Begin planning migrations from these features immediately and note the TrueNAS upgrade paths required when a deprecated feature is in use.
This section tracks features removed in 27 and features deprecated in 27 for future removal. Plan migrations immediately to avoid disruptions during upgrades.
No features are currently removed in this version.
No features are currently deprecated for future removal.
- See the 27 Version Notes for complete release information and known issues
- See the Software Development Life Cycle for an overview of the TrueNAS release process and versioning scheme
TrueNAS Hardware Guide
TrueNAS Enterprise systems use components that are qualified and tested by the TrueNAS team to offer the best storage and performance with TrueNAS Enterprise Edition.
This guide will go over the minimum hardware requirements and offer suggestions for TrueNAS Community Edition users.
| Processor | Memory | Boot Device | Storage |
|---|---|---|---|
| Any x86_64 compatible (Intel or AMD) processor | 8 GB memory | 20 GB SSD boot device | Two identically-sized devices for a single storage pool |
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.
TrueNAS can manage many storage devices as part of a single storage array. With more enterprise-level tuning, TrueNAS can manage up to 1,250 drives in a single storage array.
Choosing storage media is the first step in designing the storage system to meet immediate objectives and prepare for future capacity expansion.
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.
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 can now consider: 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.
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 -wSfor FreeBSD-based oriostatorfiofor Linux-based TrueNAS systems) Unformatted drives only! - Check HDD and SSD hours (
smartctl -a /dev/ | grep Power_On_Hours) - Check NVMe percentage used (
nvmecontrol logpage -p 2 nvme0 | grep “Percentage used”)
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.
The most widely used storage controllers 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 well-known 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 9400/9500 series give 12 Gbps SAS capabilities and even NVMe to SAS translation abilities.
TrueNAS includes the sas2flash, sas3flash, and storcli commands to flash or perform re-flashing operations on 9200, 9300, 9400, and 9500 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 is functional when necessary. 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)
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, SAS disks are the best choice 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.
The average temperature that a well-cooled spinning hard disk reaches in production is around 82 °F (28 °C), and one study found that disks experience twice the number of failures for every 12 °C increase in temperature. Pay close attention to drive temperature in any chassis that supports 16 or more drives, especially if they are high-density designs.
Every chassis has certain areas that are warmer. 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.
TrueNAS has higher memory requirements than other NAS solutions for good reason: it shares dynamic random-access memory (DRAM or simply RAM) between sharing services, apps, virtual machines, and sophisticated read caching. RAM rarely goes unused on a TrueNAS system, and enough RAM is vital to maintain peak performance. You should have at least 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.
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.
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.
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.
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 instead of 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.
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.
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 frames MTU 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.
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.
Finally, a key 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, it is not safe 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
The installation process covers installing TrueNAS using an
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.
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.
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.
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.
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.
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.
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.
Preparing for TrueNAS UI Configuration (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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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!
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.
You need an OpenPGP encryption application for this method of ISO 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.
You can install TrueNAS on either physical hardware or a virtual machine.
Before starting the update process, confirm that the system storage has enough space to handle the update. The update stops if there is insufficient space to complete.
TrueNAS is flexible and can run on any x86_64 compatible (Intel or AMD) processor. TrueNAS requires at least 8GB of RAM (more is better) and a 20GB Boot Device.
Physical hardware requires burning the TrueNAS installer to a device, typically a CD or removable USB device. This device is temporarily attached to the system to install TrueNAS to the system permanent boot device.
TrueNAS allows using other methods to create boot media such as:
- Ventoy for Windows and Linux operating systems
- TINU for MacOS Operating systems
- DiskMaker X for MacOS
- Rufus for Windows and Linux operating systems, or by creating a Windows VM in your Mac
- Universal USB Installer (UUI) similar to Rufus
- Your Universal Multiboot Installer (YUMI) for multiple operating systems
- MultiBootUSB for Windows, Linux operating systems
The following sections provide more information on a few of these options.
Before you begin:
- Locate the hotkey defined by the manufacturer of your motherboard to use in this process.
- Disable SecureBoot if your system supports it or set it to Other OS, so you can boot to the install media.
With the installer added to a device (CD or USB), 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 in UEFI mode or legacy CSM/BIOS mode. When installing TrueNAS, make the matching choice for the installation. For Intel chipsets manufactured in 2020 or later, UEFI is likely the only option.
If your system supports SecureBoot, 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 device as the boot drive, exit, and restart the system. If the USB stick is not shown as a boot option, try a different USB slot. Slots available for boot differ by hardware.
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.
TrueNAS Installer Instructions
Select Install/Upgrade.
Select the desired install drive.
Select Yes to proceed with a clean installation of TrueNAS from the
.iso . This erases the contents of the selected drive!Select option 1 Administrative user (truenas_admin) then OK to install TrueNAS and create the truenas_admin user account and password. 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.
Set a strong password and protect it.
Next, enter a password for the new truenas_admin user.
Select Yes at the Legacy Boot prompt to allow the system to boot via UEFI, or select No if your system hardware requires legacy BIOS boot. 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.
Because TrueNAS is built and provided as an .iso file, it works on all virtual machine solutions (Proxmox, VMware, VirtualBox, Citrix Hypervisor, etc). This section describes installing on a VM using VMware Workstation Player on Windows.
Regardless of the virtualization application, use these minimum settings:
- RAM: at least 8192MB (8GB)
- DISKS: two virtual disks with at least 16GB, one for the operating system and boot environments, and at least one additional virtual disk for data storage.
- NETWORK: Use NAT, bridged, or host-only depending on your host network configuration.
When installing TrueNAS in a VMWare VM, double-check the virtual switch and VMWare port group. A misconfigured virtual switch or VMWare port group can cause network connection errors for TrueNAS systems with additional applications installed inside the TrueNAS VM. Enable MAC spoofing and promiscuous mode on the switch first, and then the port group the VM is using.
If not using static IP addresses, configure your VM to use DHCP to assign IP addresses for seamless network connectivity.
Jail Networking
If you have installed TrueNAS in VMware, you need functional networking to create a jail.
For the jail to have functional networking, you have to change the VMware settings to allow Promiscuous, MAC address changes, and Forged Transmits.
| Setting | Description |
|---|---|
| Promiscuous Mode | When enabled at the virtual switch level, objects defined within all portgroups can receive all incoming traffic on the vSwitch. |
| MAC Address Changes | When set to Accept, ESXi accepts requests to change the effective MAC address to a different address than the initial MAC address. |
| Forged Transmits | When set to Accept, ESXi does not compare source and effective MAC addresses. |
The procedure for creating a TrueNAS VM is the same for most hypervisors.
This example describes installing TrueNAS using VMWare Player 15.5.
After installing TrueNAS on a virtual machine (VM), add virtual disks to the VM. You need a minimum of two disks, 16 GB each. One disk is for the boot environment the other for data storage.
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
Select the virtual machine from the list and click Play virtual machine. The machine starts and boots into the TrueNAS installer.
Select Install/Upgrade.
Select the desired install drive.
Select Yes to proceed with a clean installation of TrueNAS from the
.iso . This erases the contents of the selected drive!Select option 1 Administrative user (truenas_admin) then OK to install TrueNAS and create the truenas_admin user account and password. 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.
Set a strong password and protect it.
Next, enter a password for the new truenas_admin user.
Select Yes at the Legacy Boot prompt to allow the system to boot via UEFI, or select No if your system hardware requires legacy BIOS boot. 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, reboot 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)
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.
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.
This article outlines a procedure to do a clean install of a TrueNAS Enterprise High Availability (HA) systems using an
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.
For a list of TrueNAS Enterprise (HA) preparation information, see Preparing for TrueNAS UI Configuration (Enterprise).
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.
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.
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.
Download the
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
Use this process to install the
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.
TrueNAS Installer Steps
Select Install/Upgrade.
Select the desired install drive.
Select Yes to proceed with a clean installation of TrueNAS from the
.iso . This erases the contents of the selected drive!Select option 1 Administrative user (truenas_admin) then OK to install TrueNAS and create the truenas_admin user account and password. 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.
Set a strong password and protect it.
Next, enter a password for the new truenas_admin user.
Select Yes at the Legacy Boot prompt to allow the system to boot via UEFI, or select No if your system hardware requires legacy BIOS boot. 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.
TrueNAS is now installed on controller 1 and repeated for controller 2 starting with Using IPMI to Install the ISO on a Controller.
After installing the
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:
Type 1 and then press Enter to open the Network Interfaces screen.
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.
Use either Tab or the arrow keys to select each field. Type the value for each field listed below. Press Enter after each value.
Field Description/Example hostname The host name you assign to controller 1. For example m50-123-1. domain The domain name for the nework controller 1. For example my.companyname.net ipv4gateway The default gateway IP address for your network. nameserver1
nameserver2The IP addresses for your network DNS servers. Use either Tab or the arrow keys to select Save, then type q to return to the main Console setup menu.
This section only applies to controller 1. Do not configure settings on controller 2.
Use the TrueNAS UI to:
- Apply the HA license.
- Complete the network settings.
- Add the first storage pool.
- Sync controller 1 with controller 2.
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.
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.
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 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 Save
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.
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
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:
/usr/bin/cli --menu
The menu provides several options:
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](/scale/credentials/adminroles/) 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.
After 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](/scale/systemsettings/shell/usescaleshell/)**. 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).
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 aggregation (bond) 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.
Enter 3 to display the Static Route Settings screen to set up static routes. You can also add static routes in 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.
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.For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.
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
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)
- Use 1.1.1.1 for Cloudflare
- Use 9.9.9.9 for Quad9
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
Changing an admin user (or root if you have not created the admin user) password disables 2FA (Two-Factor Authentication) and removes the 2FA secret for that user.
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.
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.
After setting up network requirements, log into the web UI to complete your system setup by:
- [Completing network configuration] (/scale/network/) if not already set up using the Console Setup menu.
- Setting up storage
- Setting up sharing
- Backing Up your configuration
Migrating from CORE
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
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.
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
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to 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.
netcliutility. 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.
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.
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.
Deprecated services - Record the settings for services deprecated in newer TrueNAS versions.
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.
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.
SSH rsync tasks do not transfer from TrueNAS CORE to TrueNAS SCALE. After migrating, go to Data Protection > Rsync Tasks and configure a new rsync task using the settings recorded from the CORE system.
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.
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.
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.
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.
See Bluefin Deprecated Services for more information.
Community Migrations
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 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.
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.
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
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.
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
After logging in to the TrueNAS UI, use the system configuration file downloaded in Migration Preparation to restore system settings and import data storage pools.
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.
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.
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.
Download the TrueNAS manual update file. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.
Click CHECK FOR UPDATES in the System Information card on the Dashboard or go to System > Update.
Click INSTALL MANUAL UPDATE FILE.
Click SAVE CONFIGURATION to download a backup file that can restore the system configuration in the event something goes wrong with the migration.
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.
Then click APPLY UPDATE.
After the update completes, restart the system if it does not restart automatically.
After TrueNAS reboots, you might need to use the Console Setup menu to configure the primary networking interfaces to enable GUI accessibility.
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 Description igb0 is retained. This difference is purely cosmetic and does not affect functionality.
See Component Naming for more information.
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.
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.
Enterprise Migrations
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.
Review the Migration Preparation article to see detailed notes and caveats about the migration process.
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 Customer Support | |
|---|---|
| Support Portal | https://support.ixsystems.com |
| support@ixsystems.com | |
| Telephone and Other Resources | https://www.ixsystems.com/support/ |
Component Naming
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 Description igb0 is retained. This difference is purely cosmetic and does not affect functionality.
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.
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.
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.
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.
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.
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.
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.
Select Migration Mode to set additional mount options, which ensure proper transfer of metadata and ensure the remote SMB share is mounted read-only.
Enter the IP address or fully qualified domain name (FQDN) for the remote source in Server.
Enter the share name configured on the remote source in Share.
If needed, enter the domain name for the remote source in Domain (Optional).
Enter the user name and password for the SMB user on the external source.
Enter a Size larger than the SMB share on the remote source, with overhead.
g. Click Install.
Access the Syncthing UI for the first instance and configure it as needed.
a. Delete the Default Folder created by Syncthing during installation.
b. Create GUI credentials for increased security. Go to Settings > GUI and enter a user name and password.
c. Add a new remote SMB folder.
Click Add Folder.
Enter a Folder Label, such as ingest. Enter in Folder Path the mount path configured during app setup, /data1 by default.
Click Save.
d. Configure the device name.
Click Actions in the top toolbar and select Settings.
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.
Click Advanced Options and set ACL Type to SMB/NFSv4. Set ACL Mode to Restricted.
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.
g. Click Install.
The Installed Applications screen displays both Syncthing instances.
Access the Syncthing UI for the second instance and configure it as needed.
a. Delete the Default Folder created by Syncthing during installation.
b. Create GUI credentials for increased security. Go to Settings > GUI and enter a user name and password.
c. Configure the device name.
Click Actions in the top toolbar and select Settings.
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.
See How do I serve a folder from a read-only filesystem? from Syncthing for more information.
Connect the two Syncthing instances.
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.Click Save.
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.
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
Logging In for the First Time
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.
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 (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.
Refer to the Preparing for TrueNAS UI Configuration (Enterprise) and Installing TrueNAS Enterprise (HA) for information on installing HA system and configuring networking.
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.
Migrating/Upgrading from FreeBSD- to Linux-based TrueNAS Versions
For non-HA systems, there are two possible scenarios when migrating: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.
- 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
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.
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.
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.
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.
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.
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.
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.
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.
Click the Search UI bar or type Ctrl + / to select the UI global search.
Enter a keyword to search for elements within the TrueNAS UI. For example, enter SMB to search for results relating to SMB shares and the SMB service.
Global search returns UI screens, widgets, and button names matching the entered query. Click View More to view additional results, if needed.
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.
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.
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.
Issue Reporting Example
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.
Bug reports are created in the publicly visible TrueNAS Jira project.
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.
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.
Status of TrueCommand
The Status of TrueCommand icon lets users sign up with and connect to TrueCommand Cloud.
Clicking Signup opens the TrueCommand sign-up page in a new tab.
After users sign up, they can click the Connect button and enter their API key to connect TrueNAS to TrueCommand Cloud.
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.
Click Get Connected to open the TrueNAS Connect sign-in screen.
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_off Disable Service to disconnect the system from TrueNAS Connect.
See connect.truenas.com for more information.
Directory Services Monitor
When configured, the Directory Services Monitor icon button displays the status of Active Directory and LDAP services.
Click on either service to go to its configuration screen.
Jobs
The Running Jobs 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.
For more information, see Jobs Screens.
Alerts
The Alerts 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. You can also select the All Alerts, Critical, Warnings, Info, or Dismissed alert type tabs to filter alerts by type.
Use the 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.
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.
Each screen in TrueNAS displays relevant alerts with an admonition box.
Click Learn More on an admonition to view documentation related to the issue, or click close to dismiss the alert.
Settings
The Settings 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 Password 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 icon to display entered passwords. To stop displaying the password, click on the icon.
Power Options
Click the Power 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.
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.
To monitor and manage all active sessions, go to System > Advanced Settings and locate the Access widget.
With access to the TrueNAS web interface and all the management options, you can begin configuring your system!
Configuring TrueNAS Using the UI
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.
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).
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.
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.
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.For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.
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.
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.
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 aggregation (bond), or virtual LAN (VLAN) interface.
You can use the Console Setup menu or TrueNAS UI to configure network interfaces. We recommend using the web UI Network screen to add or change network interfaces or aliases, set up virtual interfaces such as a link aggregation or virtual LAN VLAN, and change or configure global network settings.
Static IP addresses and aliases provide support for various network applications.
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.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.
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.
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.
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:
| Share Type | Purpose |
|---|---|
| SMB shares | For Windows shares and setting up deprecated AFP sharing. |
| NFS shares | For Linux-based shares. |
| iSCSI shares | For block shares. |
Configure and enable the services based on what is deployed on your TrueNAS system.
TrueNAS Enterprise HA systems should enable and configure the failover service.
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.
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 the system configuration file.
- 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.
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.
The Save Configuration dialog opens.
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.
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.
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.
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.
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.
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 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.
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.
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.
You can update your system with an
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!
You can read more about these options in Creating Storage Pools. You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.
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.
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.
Click Create Pool to open the Pool Creation Wizard.
Enter a name of up to 50 lowercase alpha-numeric characters. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters. Use only the permitted special characters that conform to ZFS naming conventions. Names can have upper or lowercase alphanumeric characters, but use lower-case alpha characters to avoid potential problems with sharing protocols. Names can have special characters such as underscore (_), hyphen (-), colon (:), or a period (.), but do not begin a pool name with a special character.
You cannot change the pool name after creation.Select the encryption option for the pool. Select None to create an unencrypted pool. We recommend not encrypting the pool root dataset or the system dataset. If creating a second pool on your system and you want to encrypt this pool, select Software Encryption (ZFS). All datasets created with this option selected are also encrypted by default.
TrueNAS EnterpriseIf your Enterprise system is licensed for and has SED drives, you can select Self-Encrypting Drives (SED) to create a pool with SED drives and encryption. You may only select SEDs when using Self-Encrypting Drives (SED) encryption.
Enter and confirm the global SED password. This applies to all SED drives in the system.
(Enterprise systems only) Select the Enclosure Option to apply the dispersal strategy of your choice.
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.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.
Create the required data VDEV.
Pool Creation Wizard 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.
The Layouts field shows the following options:
Stripe
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.
<!-- comment out the setting automation tag {id="pool_create_auto-select"} -->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. 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. 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 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. 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.
See vdev_draid.c for more information.
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.
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.
Enter a value in 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).
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.
See Adding or Managing Datasets for more information on configuring datasets, or Adding or Managing Zvols for more information on zvols.
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 Adding and Managing SMB Shares or Manage NFS Shares for more information on adding and managing SMB or NFS shares.
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.
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.
Share users have permissions to access the share. You can create the user before or after you create the share.
Administrators can provision share users using a directory server such as Active Directory or 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.
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.
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.
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 Edit 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 Edit 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.
c. Begin browsing the dataset.
For more information on creating NFS shares, see Adding NFS Shares.
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-commonto 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.
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,
cdinto the local directory and view or modify the files as needed.
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.
You should also:
- Download and save your system configuration file to protect your system configuration information.
- Download a debug file.
- Create a boot environment to use as a restore point.
- Backup Stored Data
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.
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.
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.
The Save Configuration dialog opens.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
SMB Shares Screens and Setting Up SMB Home Shares provide a good introduction as to how TrueNAS handles SMB shares.
See Adding NFS Shares for information on creating a basic NFS share. Adjust access permissions using the advanced options.
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.
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 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.
See Virtual Machines for VM setup and management information.
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.
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.
Use Discover Apps to view available applications. See TrueNAS Apps Market and Apps reference guide for more information.
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
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.
The TrueNAS UI has a Support widget where users can report issues to the TrueNAS team.
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.
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.
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.
We encourage new users to briefly review the forum rules and helpful tips before posting.
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!
You are always welcome to network with other TrueNAS users using the various social media platforms!
Providing Feedback in TrueNAS
We encourage TrueNAS users to report bugs and to vote for or suggest new TrueNAS features in the project Jira instance. You must have a Jira account to create a bug ticket.
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.
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.
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.
Issue Reporting Example
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.
Bug reports are created in the publicly visible TrueNAS Jira project.
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.
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.
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.
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.
To vote for a feature request, open that thread then click Vote at the top left corner, next to the title.
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.
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.
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).
User Agreements
- TrueNAS Enterprise EULA: TrueNAS Enterprise End User License Agreement.
- Software Development Life Cycle: Notice about the typical development timeframe and end of life expectations for TrueNAS major versions.
- TrueNAS Data Collection Statement: TrueNAS team statement about non-sensitive anonymous data collection.
TrueNAS Enterprise EULA
TrueNAS Enterprise Terms of Service Important - Please Read This EULA Carefully
PLEASE CAREFULLY READ THIS END USER LICENSE AGREEMENT (EULA) BEFORE CLICKING THE AGREE OR DOWNLOAD BUTTON. THIS AGREEMENT IS A LEGALLY BINDING DOCUMENT BETWEEN YOU AND IXSYSTEMS, INC. DBA TRUENAS. BY CLICKING AGREE OR THE “DOWNLOAD” BUTTON, DOWNLOADING, INSTALLING, ACTIVATING, OR USING THE TRUENAS ENTERPRISE 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 INSTALL, ACTIVATE, OR USE THE TRUENAS ENTERPRISE SOFTWARE.
- Escalation. Before initiating arbitration, the parties shall attempt to resolve any dispute arising out of or relating to this Agreement through the following escalation process:
- Level 1 (Days 1-15): The aggrieved party shall provide written notice of the dispute to the other party. The parties shall engage in good-faith negotiation at the operational level to resolve the dispute.
- Level 2 (Days 16-30): If unresolved, the dispute shall be escalated to executive-level representatives (Vice President or above) of each party for resolution.
- Level 3 (Days 31-45): If still unresolved, either party may initiate non-binding mediation under the Commercial Mediation Procedures of the American Arbitration Association (the “AAA”).
- Binding Arbitration. If the dispute remains unresolved after the escalation process in subsection (a), either party may initiate confidential binding arbitration administered by the American Arbitration Association in accordance with its Commercial Arbitration Rules (the “AAA Rules”) seated in Wilmington, Delaware. The arbitration shall be conducted by a single arbitrator, and a decision shall be rendered within six (6) months of the commencement of arbitration proceedings.
- Injunctive Relief. Notwithstanding the foregoing, either party may seek preliminary injunctive or other equitable relief in the state or federal courts located in Wilmington, Delaware to protect its intellectual property rights, trade secrets, confidential information, or data access rights under this Agreement, without first completing the escalation process in subsection (a).
- Cost Allocation. Each party shall bear its own costs and attorneys’ fees in connection with the escalation process and arbitration, except that the prevailing party in arbitration shall be entitled to recover reasonable attorneys’ fees and costs from the non-prevailing party. TrueNAS shall bear AAA administrative fees that exceed the equivalent court filing fees.
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 exclusive jurisdiction of the United States District Court for the District of Delaware and the state courts of the State of Delaware, with venue lying in Wilmington, Delaware. 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 Delaware without regard to conflict of law principles.
EACH PARTY HEREBY KNOWINGLY, VOLUNTARILY, AND IRREVOCABLY WAIVES ANY RIGHT TO A TRIAL BY JURY IN ANY ACTION, PROCEEDING, OR CLAIM ARISING OUT OF OR RELATING TO THIS AGREEMENT OR THE TRANSACTIONS CONTEMPLATED HEREBY.
1.1 “Company,” “iXsystems,” or “TrueNAS” refers to iXsystems, Inc., d/b/a TrueNAS (“TrueNAS”), including its subsidiaries and affiliates under common control.
1.2 “TrueNAS Enterprise Software” refers to the TrueNAS Enterprise storage management software.
1.3 “TrueNAS Device” means the TrueNAS hardware storage appliances and peripheral equipment, whether provided by TrueNAS or a third party.
1.4 “Product” means, individually and collectively, the TrueNAS Enterprise Software and the TrueNAS Device provided by TrueNAS.
1.5 “Open Source Software Components” 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,” or “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 Enterprise End User License Agreement.
1.8 “Authorized Users” means employees and contractors of Licensee who are authorized by Licensee to access and use the Product for Internal Business Purposes under the rights granted to Licensee pursuant to this Agreement.
1.9 “Internal Business Purposes” means any use of the TrueNAS Enterprise Software by Licensee or its Authorized Users in connection with Licensee’s business operations, including the use of TrueNAS Devices to host, store, or deliver managed services or data services to Licensee’s own customers. Internal Business Purposes excludes the resale, sublicense, or redistribution of the TrueNAS Enterprise Software itself.
1.10 “Confidential Information” means all non-public information disclosed by one party to the other, whether orally, in writing, or by inspection, including but not limited to software architecture, source code, algorithms, APIs, product roadmaps, customer lists, pricing, deployment configurations, and usage patterns. Confidential Information does not include information that: (a) is or becomes publicly available without breach of this Agreement; (b) was known to the receiving party prior to disclosure; (c) is independently developed without reference to the disclosing party’s Confidential Information; or (d) is rightfully received from a third party without restriction. For the avoidance of doubt, benchmark results published in accordance with Section 3.0 shall not constitute Confidential Information.
1.11 “Material Breach” means any breach of this Agreement that substantially impairs the value of this Agreement to the non-breaching party and that is not cured within the applicable cure period set forth in Section 4.10.
1.12 “Authorized Purchase” means the purchase of a Product directly from TrueNAS or through a TrueNAS-authorized reseller, as evidenced by an invoice, purchase order, or similar documentation.
Subject to the terms set forth in this Agreement, TrueNAS grants You a non-exclusive, non-transferable, perpetual, limited license without the option to sublicense, to use the TrueNAS Enterprise Software on Your TrueNAS Device(s) in accordance with Your Authorized Purchase and use of a TrueNAS Device(s) for Your Internal Business Purposes. This use includes but is not limited to using or viewing the instructions, specifications, and documentation provided with the Product.
Licensee shall:
- Use TrueNAS Enterprise Software in compliance with all applicable laws, including export control (Section 5.0), data protection (Section 6.0), and applicable sanctions laws;
- Maintain the confidentiality of license keys, credentials, and administrative access, and implement reasonable physical and logical access controls;
- Promptly apply all critical security patches and updates released by TrueNAS within ninety (90) days of release, unless TrueNAS specifies a different timeline;
- Maintain current backups of all data stored on TrueNAS Devices in accordance with industry best practices;
- Implement and maintain appropriate cybersecurity measures (including encryption, access controls, and network segmentation) consistent with industry best practices for enterprise storage systems;
- Ensure that appropriate internal incident response procedures are in place to detect, investigate, and respond to any suspected security breach, unauthorized access, or misuse of the TrueNAS Enterprise Software;
- Ensure that all Authorized Users comply with the terms of this Agreement.
The perpetual license granted in Section 2.0 permits continued use of the TrueNAS Enterprise Software version installed at the time of license grant. Access to software updates, patches, and new versions is available during the applicable Support Term only, as described in Section 4.8. Continued use of the TrueNAS Enterprise Software after expiration of the Support Term is permitted, but without access to updates or support services.
TrueNAS Enterprise Software is authorized for use only with a TrueNAS Device identified by a specific serial number, approved by TrueNAS, and linked to a valid digital license key installed on the TrueNAS Device. The license is not transferable to another TrueNAS Device without written approval from TrueNAS. The TrueNAS Enterprise Software is protected by copyright laws and international treaties, as well as other intellectual property laws, statutes, and treaties. The TrueNAS Enterprise Software is licensed, not sold to You, the end user. You do not acquire any ownership interest in the TrueNAS Enterprise Software, or any other rights to the TrueNAS Enterprise Software, other than to use the TrueNAS Enterprise Software in accordance with the license granted under this Agreement, subject to all terms, conditions, and restrictions. TrueNAS reserves and shall retain its entire right, title, and interest in and to the TrueNAS Enterprise Software, and all intellectual property rights arising out of or relating to the TrueNAS Enterprise Software, subject to the license expressly granted to You in this Agreement.
The TrueNAS Enterprise Software may contain TrueNAS’ proprietary trademarks, trade secrets, and collateral. TrueNAS strictly prohibits the acts of decompiling, reverse engineering, or disassembly of the TrueNAS Enterprise Software, except as expressly permitted below. You agree to use commercially reasonable efforts to safeguard TrueNAS’ intellectual property, trade secrets, or other proprietary information You may have access to, from infringement, misappropriation, theft, misuse, or unauthorized access. You will promptly notify TrueNAS if You become aware of any infringement of the TrueNAS Enterprise Software and cooperate with TrueNAS in any legal action taken by TrueNAS to enforce its intellectual property rights.
Notwithstanding the foregoing prohibition on reverse engineering, Licensee may: (i) reverse engineer, decompile, or disassemble the TrueNAS Enterprise Software to the extent required by applicable law for interoperability purposes; (ii) exercise rights granted by applicable Open Source Software Component licenses (e.g., GPL, LGPL, AGPL) with respect to those Open Source Software Components; and (iii) conduct security research on the TrueNAS Enterprise Software for the purpose of identifying vulnerabilities, provided that Licensee first notifies TrueNAS and coordinates responsible disclosure. If TrueNAS does not acknowledge the reported vulnerability within fourteen (14) days of notification, or does not release a patch or provide a remediation timeline within ninety (90) days of notification, Licensee may publicly disclose the vulnerability.
By accepting this Agreement, You agree not to disclose, copy, transfer, or publish benchmark results relating to the Product without first providing TrueNAS at least five (5) business days’ advance written notice and a reasonable opportunity to verify the accuracy of the benchmark methodology and results. TrueNAS may, at its option, publish a response to any benchmark results disclosed by Licensee.
You agree not to use, or permit others to use, the TrueNAS Enterprise Software beyond the scope of the license granted under Section 2, unless otherwise permitted by TrueNAS, or in violation of any law, regulation or rule, and you will not modify, adapt, or otherwise create derivative works or improvements of the TrueNAS Enterprise Software. By accepting this Agreement, You are responsible and liable for all uses of the Product through access thereto provided by You, directly or indirectly.
Notwithstanding anything to the contrary in this EULA, TrueNAS may temporarily suspend Your license to any portion or all of the TrueNAS Enterprise Software if TrueNAS reasonably determines that:
- There is a threat or attack on any of the TrueNAS intellectual property rights, the TrueNAS Software, or applicable support services;
- You or any of Your Authorized Users’ use of the TrueNAS intellectual property rights, the TrueNAS Software, or support services disrupts or poses a security risk to the TrueNAS intellectual property rights, the TrueNAS Software, support services, or to any other customer or vendor of TrueNAS;
- You, or any of Your Authorized Users, are using the TrueNAS intellectual property rights, the Software, or services for fraudulent or illegal activities;
- TrueNAS’ provision of the TrueNAS Enterprise Software to You or any of Your Authorized Users is prohibited by applicable law.
Reversion of License and Data Control Upon Revocation
Notwithstanding any other provision in this Agreement, upon the permanent revocation of the TrueNAS Enterprise Software license, the functionality of the software installed on Your TrueNAS Device(s) will automatically revert to the terms and conditions of the then-current TrueNAS Community Edition License. In all cases of license revocation, Licensee shall retain full read and write access to all data stored on the TrueNAS Device(s). TrueNAS shall have no obligation to provide maintenance, support, or updates for the reverted Community Edition. Any features or functionality exclusive to the TrueNAS Enterprise Software, including but not limited to high-availability data protection and certain specialized support services, will cease to operate upon reversion.
For the avoidance of doubt, reversion to Community Edition shall not affect Licensee’s ability to access, read, write, export, or migrate data stored on the TrueNAS Device(s) using standard Community Edition storage protocols. All storage pools, datasets, and file systems shall remain fully accessible.
TrueNAS may request reasonable information from Licensee to confirm compliance with the scope of the license granted under this Agreement. Licensee shall cooperate in good faith with such requests.
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 TrueNAS for use of the TrueNAS Enterprise 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 TrueNAS.
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.
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.
For any TrueNAS Enterprise 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.
You agree to comply with all applicable anti-corruption and anti-bribery laws, including the U.S. Foreign Corrupt Practices Act (FCPA). You will not make any improper payments or offer anything of value to obtain an unfair business advantage. You will indemnify and hold harmless Company from any breach of this provision.
TrueNAS retains all rights, titles, and interests in the TrueNAS Enterprise Software and in 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.
If You have any questions about this Agreement, or if You want to contact TrueNAS for any reason, please email legal@truenas.com.
You may be entitled to support services from TrueNAS after purchasing a Product or a support contract. TrueNAS will provide these support services based on the length of time outlined in the purchased support contract. This maintenance and support is only valid for the length of time that You have purchased with Your Product. TrueNAS 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.truenas.com/support.
TrueNAS 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 TrueNAS’ reasonable control.
TrueNAS may terminate this Agreement upon thirty (30) days’ written notice if Licensee commits a Material Breach that remains uncured after the applicable cure period. TrueNAS may terminate immediately upon written notice if Licensee commits a breach under Section 3.0(C) (fraudulent or illegal activities) or Section 3.0(E) (legal prohibition). Upon termination, rights to use the TrueNAS Enterprise Software will immediately cease, subject to the data access rights in Section 3.0. The following Sections shall survive termination or expiration of this Agreement: Dispute Resolution, 1.0 (Definitions), 3.0 (License Restrictions, including Reversion and data access provisions), 4.3 (Severability), 4.6 (Title), 4.13 (Notice Provisions), 4.14 (Limitation Period), 6.0 (Data Collection and Privacy), 8.0 (Limitation of Liability), 9.0 (Indemnification), and 10.0 (Confidentiality).
TrueNAS uses Open Source Software Components in the development of the TrueNAS Enterprise Software. Open Source Software Components that are used in the TrueNAS Enterprise Software are composed of separate components each having its own trademarks, copyrights, and license conditions. To the extent any Open Source Software Component license terms conflict with this EULA, the Open Source Software Component license terms shall control solely with respect to those Open Source Software Components. TrueNAS shall maintain and make available upon request a current Software Bill of Materials (SBOM) listing all Open Source Software Components included in the TrueNAS Enterprise Software, including component name, version, and applicable license. TrueNAS represents and warrants that, as of the date of delivery of each Software release, it complies with all applicable Open Source Software Component license obligations, including providing complete source code, license texts, and attribution notices as required by the applicable licenses.
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 TrueNAS’ 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. TrueNAS 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 ensures to the benefit of, the parties hereto and their respective permitted successors and assigns.
All notices required or permitted under this Agreement shall be in writing and shall be deemed received: (a) upon delivery, if delivered personally; (b) upon confirmation of receipt, if sent by email to the addresses specified below; (c) one (1) business day after deposit with a nationally recognized overnight courier; or (d) three (3) business days after deposit in the U.S. mail, postage prepaid, certified or registered, return receipt requested. Notices to TrueNAS shall be sent to: iXsystems, Inc., Attn: Legal Department, legal@truenas.com. Notices to Licensee shall be sent to the address or email provided in the applicable purchase order or registration.
Any claim or cause of action arising out of or relating to this Agreement must be commenced within two (2) years after the cause of action accrues, or such claim shall be permanently barred.
Licensee acknowledges that the Product is subject to U.S. and international export control laws and regulations, including trade sanctions and export restrictions. TrueNAS makes no representation or warranty that the Product may be lawfully exported, re-exported, or imported to Licensee’s jurisdiction, and Licensee is solely responsible for determining that its use of the Product does not violate any such laws or regulations. TrueNAS shall have no liability to Licensee for any failure to comply with any export control laws.
TrueNAS Enterprise Software may collect non-sensitive technical and operational system information relating to Your use of the Product, including hardware model identifiers, software version numbers, pool topology, storage capacity utilization, feature usage flags, and system health metrics, which may be provided directly or indirectly through automated means. Usage of TrueNAS Enterprise Software, device status and system configuration are allowed according to TrueNAS’ privacy policy, available at https://www.truenas.com/privacy-policy/.
TrueNAS Enterprise Software will not collect and share sensitive User information including email addresses, names of systems, pools, datasets, folders, files, credentials, IP addresses, hostnames, or any other information that directly or indirectly identifies a natural person.
By accepting this Agreement and continuing to use the Product, you agree that TrueNAS 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, support, security, update delivery, and product improvement.
Licensee may opt out of automated data collection at any time through the TrueNAS Enterprise Software system settings. Licensee may separately opt out of the use of collected information for marketing purposes by contacting privacy@truenas.com.
The data collected under Section 6.1 is limited to anonymous, aggregated, technical and operational telemetry that does not contain personal data as defined under applicable data protection laws (including GDPR Article 4(1) and similar frameworks). TrueNAS has designed its telemetry systems specifically to exclude identifiers that could directly or indirectly identify a natural person. Accordingly, the TrueNAS Enterprise Software operates without collecting, transmitting, or otherwise processing personal data, no cross-border transfers of personal data occur through the Software, and the terms of this EULA do not constitute a Data Processing Agreement.
If You voluntarily provide personal data to TrueNAS (for example, through optional support requests or feedback submissions), such data will be processed only for the purpose of responding to Your inquiry, in accordance with applicable data protection laws and the TrueNAS Privacy Policy.
TrueNAS hereby represents and warrants that, during the term of this Agreement, TrueNAS owns or is otherwise authorized to use and provide any Intellectual Property Rights provided by TrueNAS to You under this EULA.
TrueNAS further warrants that, for a period of ninety (90) days following initial delivery of the TrueNAS Enterprise Software (“Warranty Period”), the TrueNAS Enterprise Software will substantially conform to its published documentation. If during the Warranty Period the TrueNAS Enterprise Software fails to substantially conform to its documentation, TrueNAS shall, at its option, (a) repair or replace the non-conforming Software, or (b) refund the fees paid for the non-conforming Software, or (c) with Your agreement, improve the published documentation. This warranty does not apply to defects caused by: (i) modifications not made by TrueNAS; (ii) use outside the scope of the documentation; or (iii) combination with products not approved by TrueNAS. For avoidance of doubt, any hardware components (including TrueNAS Devices) are provided subject solely to the limited hardware warranty accompanying such hardware purchase. Except as expressly set forth in such hardware warranty documentation, TrueNAS disclaims all warranties relating to hardware.
TrueNAS does not make any representations or guarantees regarding uptime or availability of the services except as set forth in any applicable Maintenance and Support contract purchased by You. THE FOREGOING WARRANTY DOES NOT APPLY, AND TRUENAS STRICTLY DISCLAIMS ALL WARRANTIES, WITH RESPECT TO ANY THIRD PARTY PRODUCTS OR SOFTWARE, INCLUDING OPEN-SOURCE SOFTWARE THAT MAY BE INCORPORATED AS PART OF THE SOFTWARE AND SERVICES PROVIDED HEREUNDER.
EXCEPT FOR THE LIMITED WARRANTY SET FORTH HEREIN, 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, TRUENAS, 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, TRUENAS 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 TRUENAS 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 TRUENAS WAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES; (B) IN NO EVENT WILL TRUENAS 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 GREATER OF: (I) THE TOTAL AMOUNT PAID BY LICENSEE TO TRUENAS FOR THE SPECIFIC PRODUCT GIVING RISE TO THE CLAIM; OR (II) THE TOTAL SUPPORT FEES PAID BY LICENSEE TO TRUENAS IN THE TWELVE (12) MONTHS PRECEDING THE EVENT GIVING RISE TO 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.
(D) NOTWITHSTANDING THE FOREGOING, THE LIMITATIONS IN SUBSECTIONS (A) AND (B) SHALL NOT APPLY TO: (I) EITHER PARTY’S INDEMNIFICATION OBLIGATIONS UNDER SECTION 9.0; (II) EITHER PARTY’S WILLFUL BREACH OF CONFIDENTIALITY OBLIGATIONS UNDER SECTION 10.0; (III) EITHER PARTY’S INFRINGEMENT OF THE OTHER PARTY’S INTELLECTUAL PROPERTY RIGHTS; (IV) LIABILITY FOR DEATH OR PERSONAL INJURY CAUSED BY NEGLIGENCE; (V) LIABILITY ARISING FROM WILLFUL MISCONDUCT OR GROSS NEGLIGENCE; OR (VI) EITHER PARTY’S BREACH OF DATA PROTECTION OBLIGATIONS UNDER SECTION 6.0.
TrueNAS shall defend, indemnify, and hold harmless Licensee from and against any third-party claims, damages, and costs (including reasonable attorneys’ fees) arising from allegations that the Product, as delivered by TrueNAS, infringes any patent, copyright, trademark, or trade secret right of a third party, provided that Licensee: (a) promptly notifies TrueNAS in writing of such claim; (b) grants TrueNAS sole control of the defense and settlement of such claim; and (c) provides reasonable cooperation at TrueNAS’ expense.
If the TrueNAS Enterprise Software becomes, or in TrueNAS’ reasonable opinion is likely to become, the subject of an infringement claim, TrueNAS may, at its option and expense: (i) obtain the right for Licensee to continue using the TrueNAS Enterprise Software; (ii) modify the TrueNAS Enterprise Software to make it non-infringing while maintaining substantially equivalent functionality; or (iii) if options (i) and (ii) are not commercially feasible, terminate this Agreement.
TrueNAS’ indemnification obligations under this Section shall not apply to claims arising from: (a) modifications to the TrueNAS Enterprise Software not made or authorized by TrueNAS; (b) combination of the TrueNAS Enterprise Software with products, software, or data not provided by TrueNAS, where the infringement would not have occurred absent such combination; or (c) Licensee’s use of the TrueNAS Enterprise Software in violation of this Agreement.
Licensee shall defend, indemnify, and hold harmless TrueNAS from and against any third-party claims, damages, and costs (including reasonable attorneys’ fees) arising from: (a) Licensee’s use of the TrueNAS Enterprise Software in violation of this Agreement or applicable law; (b) Licensee’s unauthorized modifications to the TrueNAS Enterprise Software; (c) Licensee’s combination of the TrueNAS Enterprise Software with products, software, or data not provided by TrueNAS; or (d) Licensee’s negligence or willful misconduct in connection with its use of the Product.
The indemnified party shall: (a) promptly notify the indemnifying party in writing of any claim; (b) grant the indemnifying party sole control of the defense and settlement (provided that the indemnifying party shall not settle any claim in a manner that imposes obligations on the indemnified party without its prior written consent); and (c) provide reasonable cooperation at the indemnifying party’s expense. The indemnified party may participate in the defense at its own expense.
For the avoidance of doubt, each party’s indemnification obligations under this Section 9.0 are subject to the carve-outs set forth in Section 8.0(D)(I) and are not subject to the aggregate liability cap in Section 8.0(B), except that TrueNAS’ total indemnification liability shall not exceed three (3) times the aggregate fees paid by Licensee to TrueNAS under this Agreement.
During the term of this Agreement and for five (5) years thereafter, each party (the “Receiving Party”) shall: (a) maintain in confidence and not disclose the other party’s (the “Disclosing Party’s”) Confidential Information to any third party, except to employees, contractors, and advisors with a need to know who are bound by obligations of confidentiality at least as protective as those in this Section; and (b) use the Disclosing Party’s Confidential Information solely to exercise its rights and perform its obligations under this Agreement.
If the Receiving Party is compelled by law, regulation, or legal process to disclose the Disclosing Party’s Confidential Information, the Receiving Party shall: (a) provide the Disclosing Party with prompt written notice (to the extent legally permitted) to allow the Disclosing Party to seek a protective order or other appropriate remedy; and (b) disclose only the minimum Confidential Information required by such legal obligation.
Upon termination or expiration of this Agreement, or upon the Disclosing Party’s written request, the Receiving Party shall promptly return or destroy all Confidential Information of the Disclosing Party in its possession or control, and certify such return or destruction in writing. This obligation shall not apply to Confidential Information retained in routine backup systems, provided that such information remains subject to the confidentiality obligations of this Section and such backups are destroyed in the ordinary course of the Receiving Party’s backup retention schedule, not to exceed twelve (12) months.
The obligations of confidentiality under this Section 10.0 shall survive termination or expiration of this Agreement for a period of five (5) years.
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) covers how the TrueNAS team plans, develops, tests, deploys, and maintains TrueNAS releases. TrueNAS uses an open-core model. Community and Enterprise systems run the same software from the same installation image, with Enterprise features unlocked through licensing. Community members play an important role in testing pre-release builds, with participation guided by the TrueNAS Software Status page and the update profile configured on each system.
The TrueNAS team defines the objectives, scope, and direction of future TrueNAS versions. This involves gathering feedback from both Enterprise and Community users, identifying existing problems, and evaluating potential solutions. Enterprise customer requirements and use cases are a key input to the planning process. Community members can also submit and vote on ideas through the Feature Requests section of the TrueNAS forums. The output is a prioritized list of improvements targeted for an upcoming release.
Engineers investigate planned changes in detail and define implementation steps. Peers review proposed changes for completeness, correctness, and coding standards before development begins. TrueNAS developers then implement the approved changes.
TrueNAS teams integrate changes into the codebase and test builds across multiple stages of development, with Community members contributing additional coverage by running early development versions. Nightly builds undergo regression testing throughout the development cycle, with more intensive validation following code freeze and before each release. Engineers rework any features or changes that fall short of requirements before release.
The documentation team evaluates pre-release builds in parallel and writes public-facing content describing changes in the new version.
TrueNAS also conducts a security review of the codebase during this stage, addressing any findings before release and publishing relevant security notices, errata, and best practices to the TrueNAS Security website.
Each release enters an ongoing maintenance phase covering bug fixes, security patches, and further development needs. Maintenance releases are published as issues are resolved, with user feedback continuing to inform planning for future versions.
Starting with TrueNAS 26, TrueNAS follows an annual release cadence with one major version per year. The major version number reflects the release year: TrueNAS 26 in 2026, TrueNAS 27 in 2027, and so on.
Version numbers follow a YY.MINOR.PATCH format:
- YY — the release year (26, 27, etc.)
- MINOR — increments for significant updates within a release year (e.g.,
26.1.0) - PATCH — increments for minor point releases and bug fixes (e.g.,
26.0.1)
Each major release progresses through the following stages before and after general availability:
| Stage | Version Format | Description |
|---|---|---|
| Nightly | 26.0.0-MASTER+YYYYMMDD-HHMMSS | Automated daily builds from active development, available for early testing and feedback |
| BETA | 26.0.0-BETA.# | Feature-complete builds for broader Community testing |
| RC | 26.0.0-RC.# | Release candidates with final stabilization fixes |
| Release | 26.0.0 | General availability |
| Maintenance | 26.0.# / 26.#.0 | Point releases for bug fixes and larger mid-year updates |
TrueNAS does not define a fixed End of Life (EoL) date for its releases. In practice, a version reaches end of life when the TrueNAS team no longer recommends it for any user type. At that point, its documentation moves to the Documentation Archive and receives no further updates.
The TrueNAS Software Status page is the authoritative source for current version recommendations, covering user types from Developer to Mission Critical. Check this page when deciding whether to upgrade or stay on your current version.
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 |
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.
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.
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.
Click the Search UI bar or type Ctrl + / to select the UI global search.
Enter a keyword to search for elements within the TrueNAS UI. For example, enter SMB to search for results relating to SMB shares and the SMB service.
Global search returns UI screens, widgets, and button names matching the entered query. Click View More to view additional results, if needed.
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.
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.
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.
Issue Reporting Example
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.
Bug reports are created in the publicly visible TrueNAS Jira project.
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.
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.
Status of TrueCommand
The Status of TrueCommand icon lets users sign up with and connect to TrueCommand Cloud.
Clicking Signup opens the TrueCommand sign-up page in a new tab.
After users sign up, they can click the Connect button and enter their API key to connect TrueNAS to TrueCommand Cloud.
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.
Click Get Connected to open the TrueNAS Connect sign-in screen.
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_off Disable Service to disconnect the system from TrueNAS Connect.
See connect.truenas.com for more information.
Directory Services Monitor
When configured, the Directory Services Monitor icon button displays the status of Active Directory and LDAP services.
Click on either service to go to its configuration screen.
Jobs
The Running Jobs 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.
For more information, see Jobs Screens.
Alerts
The Alerts 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. You can also select the All Alerts, Critical, Warnings, Info, or Dismissed alert type tabs to filter alerts by type.
Use the 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.
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.
Each screen in TrueNAS displays relevant alerts with an admonition box.
Click Learn More on an admonition to view documentation related to the issue, or click close to dismiss the alert.
Settings
The Settings 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 Password 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 icon to display entered passwords. To stop displaying the password, click on the icon.
Power Options
Click the Power 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.
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.
Alerts
The Alerts 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. You can also select the All Alerts, Critical, Warnings, Info, or Dismissed alert type tabs to filter alerts by type.
Use the 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.
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.
Each screen in TrueNAS displays relevant alerts with an admonition box.
Click Learn More on an admonition to view documentation related to the issue, or click close to dismiss the alert.
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 icon, then click the 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.
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.
| 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 Splunk On-Call. |
| 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.
Use the Edit Alert Service screen to modify settings for a service. Select the icon for the service to display the Edit Alert Service screen.
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Settings
| Setting | Description |
|---|---|
| AWS Region | Enter the AWS account region. |
| ARN | Topic Amazon Resource Name (ARN) for publishing. For example, arn:aws:sns:us-west-2:111122223333:MyTopic. |
| Key ID | Enter the access key ID for the linked AWS account. |
| Secret Key | Secret access key for the linked AWS account. |
Click here for more information
Select E-Mail from the Type dropdown list to display email authentication settings.
Settings
| Setting | Description |
|---|---|
| Override Admin Email | Sets an email address to override the default email address for the admin account. When left blank, the email address for the admin account is used. |
Click here for more information
Select InfluxDB from the Type dropdown list to display InfluxDB authentication settings.
Settings
| Setting | Description |
|---|---|
| Host | Enter the InfluxDB host name. |
| Username | Enter the user name for this service. |
| Password | Enter the password for the user on this service |
| Database | Enter the name of the InfluxDB database. |
| Series | Enter the InfluxDB time series name for collected points. |
Click here for more information
Select Mattermost from the Type dropdown list to display Mattermost authentication settings.
Settings
| Setting | Description |
|---|---|
| Webhook URL | Enter or past the incoming webhook URL associated with this service. |
| Username | Enter the Mattermost user name. |
| Channel | Enter the name of the channel to receive notifications. Entering a channel overrides the default channel in the incoming webhook settings. |
| Icon URL | Enter the icon file to use as the profile picture for new messages. For example, https://mattermost.org/wp-content/uploads/2016/04/icon.png. Requires configuring Mattermost to override profile picture icons. |
Click here for more information
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
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. |
| API URL | Leave empty for default (OpsGenie API). |
Click here for more information
Select PagerDuty from the Type dropdown list to display PagerDuty authentication settings.
Settings
| Setting | Description |
|---|---|
| Service Key | Enter or paste the integration/service key for this system to access the PagerDuty API. |
| Client Name | Enter the PagerDuty client name. |
Click here for more information
Select Slack from the Type dropdown list to display Slack authentication settings.
Settings
| Setting | Description |
|---|---|
| Webhook URL | Paste the incoming webhook URL associated with this service. |
Click here for more information
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
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?. |
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Settings
| Setting | Description |
|---|---|
| Bot API Token | Enter the Telegram Bot API Token How to create a Telegram Bot. |
| List of chat IDs | 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. |
Click here for more information
Select Splunk On-Call from the Type dropdown list to display Splunk On-Call authentication settings.
Settings
| Setting | Description |
|---|---|
| API Key | Enter or paste the Splunk On-Call API key. |
| Routing Key | Enter or past the Splunk On-Call routing key. |
Use the Category dropdown list to display alert settings for each category.
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Audit alert settings apply to the audit and verification services on your TrueNAS system.
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Directory Service alert settings apply to the directory services configured on your TrueNAS.
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only display 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 alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.
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.Click here for more information
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) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Network alert settings apply to network interfaces configured on your TrueNAS.
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
You can customize alert settings for when a deprecated service configuration is detected or a deprecated service is running, and when Fibre Channel HBAs are added or replaced. You can also customize alerts for iSCSI issues: IP addresses bound to an iSCSI portal are not found, iSCSI authorized access has invalid characters or leading/trailing whitespace, and iSCSI discovery authorization is set to global, has multiple mutual CHAP, or is merged. For NFS, you can customize alerts for when NFS services cannot bind to specific IP addresses using 0.0.0.0, an NFS export entry is blocked, host or network lists are excessively long, share references to hosts cannot be resolved, and NFS start is blocked by entries in /etc/exports.d. For SMB, you can customize alerts for when NTLMv1 authentication is attempted in the last 24 hours, SMB1 connections to the TrueNAS server are performed in the last 24 hours, an SMB share audit configuration contains invalid groups, an SMB share path has unresolvable issues, SMB shares use an incorrect recordsize value for Veeam Fast Clone, and an SMB user is missing a required password hash. You can also set alerts for when a share is unavailable because it uses a locked dataset.Click here for more information
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
You can customize alert settings for when a dataset exceeds standard or critical quotas, a pool has new available feature flags, pool space usage exceeds 85, 90, or 95 percent, and pool status is not healthy. You can also change alert settings for when a scrub pauses, too many snapshots exist on the system or on a specific dataset.Click here for more information
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.
You can customize alert settings for when an API key is revoked, API or SSH login failures occur, the admin user is overridden, administrator account activity is detected, the boot pool is unhealthy, core files are detected, and the running system version does not match the selected update profile. You can also change alert settings for when a failover event or fencing causes a system reboot, a Gmail OAuth configuration is discarded, NTP health checks fail, a GPU configuration update requires a reboot, the system is not ready for Kdump, and system mocking endpoints are in use. For TrueCommand, you can customize alerts for when an API key is pending confirmation or disabled by iX Portal, and when the TrueCommand container or service fails a scheduled health check. You can also set alerts for when unencrypted datasets are detected within encrypted datasets and when an update is available.Click here for more information
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub, and snapshot tasks scheduled on your TrueNAS.
You can customize alert settings for when cloud backup or cloud sync tasks fail, a cloud provider is removed, VMWare snapshot creation or deletion fails, VMWare login fails, replication fails or succeeds, rsync tasks fail or succeed, a scrub fails to start or starts, snapshot tasks fail, and when a task is unavailable because it uses a locked dataset.Click here for more information
TrueNAS Connect Service alert settings apply to the TrueNAS Connect service on your TrueNAS system.
UPS alert settings apply to a UPS connected to your TrueNAS.
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 |
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 Alerts icon button and 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.
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.
Settings Options
The Settings icon button displays a menu of general system settings options. The options are Change Password, Preferences, My API Keys, Guide and About.
Click on the Change Password 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 icon to display entered passwords. To stop displaying the password, click on the icon.
The Preferences screen settings configure the color theme, session duration before timing out and logging out the currently logged-in user, and localization settings for the logged-in user account.
The Theme settings customize the UI theme colors for the currently logged-in user. Options are: ixDark (default option), ixBlue, Dracula, Nord, Paper, Solarized Dark, Midnight, and High Contrast. Selecting an option immediately changes the UI to the selected color theme.
Session Timeout sets the number of seconds a session remains active or inactive before it is automatically ended by logging out the user.
Localization sets the screen language, date format, and time format for the currently logged-in user account. To see the keyboard map and timezone, use the System > General Settings > Localization configuration screen.
Select the desired language for the UI from the Language dropdown list. The default setting is English but might be customized to the language based on the country of origin for an Enterprise customer. You can filter the list by typing in the field after clearing the default value, or use the scroll option to find and select a language.
Select the desired format in the Date Format and Time Format that matches your geographic location.
Click Save to set all changes for the currently logged-in user.
TrueNAS automatically terminates the currently logged-in user session when the default session timeout expires and shows the TrueNAS login splash screen.
To extend the allotted session time, go to the Preferences screen and change the Session Timeout to a value that suits the use case for the logged-in user.
The default lifetime setting is 300 seconds or five minutes.
The maximum is 2147482 seconds, or 596 hours (24 days and 20 hours), 31 minutes, and 22 seconds.
Click Save.
Click on My 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.
Click on Guide to display the TrueNAS Documentation Hub in a new tab.
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.
User API Keys Screen
laptop My 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.
Add opens the Add API Key screen.
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.
Reset removes the existing API key and generates a new random key.
delete delete for any API key on the list opens a Delete API Key dialog to remove 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 Auth Screen
Two-factor authentication is time-based and requires a correct system time setting.
The Two Factor Auth screen allows managing user-level two-factor authentication (2FA) credentials. Access this screen by going to Credentials > Two Factor Auth, or from the Settings menu on the top toolbar when Global 2FA is enabled.
Administrators can enable Global 2FA on the Advanced Settings screen. For more information, see the Managing Global 2FA tutorial.
The Two Factor Auth screen displays different information depending on the Global 2FA and user 2FA configuration status.
When Global 2FA is not enabled, the screen displays a warning message:
Two-Factor authentication is not enabled on this system. You can configure your personal settings, but they will have no effect until two-factor authentication is enabled globally by system administrator.
Users can still configure their personal 2FA settings, but authentication codes are not required for login until a system administrator enables Global 2FA.
When Global 2FA is enabled but the current user has not configured their personal 2FA, the screen displays the following messages:
Two-Factor authentication is enabled on this system, but it’s not yet configured for your user. Please configure it now.
Two-Factor Authentication has been enabled on this system. It is strongly recommended to set up 2FA for your account to enhance security. Make sure to scan the QR code with your authenticator app before logging out or navigating away, otherwise you may have difficulty accessing your account later.
Users should configure their 2FA immediately to maintain secure access to their account.
When the user has configured 2FA, the screen displays a green confirmation message:
Two-Factor authentication has been configured.
The screen also displays the QR code and text code for the user’s 2FA secret.
The Set Up Two-Factor Authentication card contains the following elements:
Configure 2FA Secret shows before the user configures 2FA. Clicking on this generates a new 2FA secret and displays the QR code.
Renew 2FA Secret appears after 2FA is configured. Click to generate a new secret and QR code. A confirmation dialog appears with the message:
Renewing the secret will cause a new URI and a new QR code to be generated, making it necessary to update your two-factor device or app.
Click Renew to confirm or Cancel to keep the existing secret.
Unset 2FA Secret removes the existing 2FA configuration for the user. A confirmation dialog appears with the message:
Are you sure you want to unset two-factor authentication? This will remove your current 2FA configuration and you will need to set it up again to use 2FA.
Unset 2FA confirms changes. Cancel keeps the existing configuration.
Removing your 2FA configuration reduces account security. If Global 2FA is enabled, you are prompted to set up 2FA again on your next login.
After configuring 2FA, the screen displays a QR code that users scan with their authenticator app. The screen also displays the following warning:
Scan this QR Code with your authenticator app of choice. The next time you try to login, you will be asked to enter an One Time Password (OTP) from your authenticator app. This step is extremely important. Without the OTP you will be locked out of this system.
Below the QR code, the screen displays the text version of the 2FA secret with a copy-to-clipboard button. The copy-to-clipboard button allows users save the code and then manually enter it into their authenticator app if they cannot scan the QR code.
Using UI Global Search
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.
Click the Search UI bar or type Ctrl + / to select the UI global search.
Enter a keyword to search for elements within the TrueNAS UI. For example, enter SMB to search for results relating to SMB shares and the SMB service.
Global search returns UI screens, widgets, and button names matching the entered query. Click View More to view additional results, if needed.
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.
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.
Managing API Keys
TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API with support for user-linked API access keys (API Reference).
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 laptop My API Keys from the account_circle user settings dropdown menu in the top right toolbar. The User API Keys screen opens.
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 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.
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.
Click Add API Key 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.
Click Save. The API Key dialog opens with a generated key string. TrueNAS API key strings are 64 randomly generated characters long.
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 file in a secure location.
Click Close to return to the User API Keys screen.
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.
Select the user row and then click edit edit to open the Edit API Key screen.
Make the desired changes and click Save.
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.
Click delete delete for any API key on the list to remove that key. TrueNAS opens a Delete API Key dialog.
Select Confirm, then click Delete.
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 WebSocket API 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
This procedure applies to TrueNAS Enterprise High Availability (HA) systems only.
If you need to power down your TrueNAS Enterprise system with HA enabled, this is the procedure:
While logged into the TrueNAS Web UI using the virtual IP (VIP), click the power button in the top right corner of the screen.
Select Shut Down from the dropdown list.
This shuts down the active controller.
The system fails over to the standby controller.
When the TrueNAS Web UI login screen displays, log back in to the system. This logs you in to the standby controller.
Click the power button in the top right corner of the screen.
Select Shut Down from the dropdown list.
This shuts down the standby controller.
Top Toolbar Screens
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.
| Icon | Name | Description |
|---|---|---|
| Toggle collapse | Click to expand or collapse the main menu panel on the left side of the screen. | |
 | Search UI | Searches UI screens and elements or redirects queries to the TrueNAS Documentation Hub. |
| Send Feedback | Opens the Send Feedback feedback window for sending UI ratings and bug reports to the TrueNAS developers. | |
| Status of TrueCommand | Displays either the status of a TrueCommand cloud connection or a dialog that allows users to sign up for a new TrueCommand cloud connection. | |
| Status of TrueNAS Connect | Opens the TrueNAS Connect Service and dialog showing the current status of the service and the TrueNAS Connect dialog that allows you to connect to the service 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. | |
| Directory Services status | Displays a dialog with the status of Active Directory and LDAP directory servers configured on the system. | |
| 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. | |
| Alerts | Displays a list of system alerts and a dropdown list with the alert options Alert Settings and Email. | |
| Settings | Displays a dropdown list of setting options Change Password, Two-Factor Authentication (when Global 2FA is enabled), My API Keys, Guide, and Log Out. | |
| Power options | Displays the power related options Restart or Shut Down. |
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
Click the Search UI bar or type Ctrl + / to select the UI global search.
Enter a keyword to search for elements within the TrueNAS UI. For example, enter SMB to search for results relating to SMB shares and the SMB service.
Global search returns UI screens, widgets, and button names matching the entered query. Click View More to view additional results, if needed.
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.
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 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.
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.
Issue Reporting Example
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.
Bug reports are created in the publicly visible TrueNAS Jira project.
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.
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.
The Status of TrueCommand icon lets users sign up with and connect to TrueCommand Cloud.
Clicking Signup opens the TrueCommand sign-up page in a new tab.
After users sign up, they can click the Connect button and enter their API key to connect TrueNAS to TrueCommand Cloud.
TrueNAS displays a message telling users to check their email for verification instructions.
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.
Click Get Connected to open the TrueNAS Connect sign-in screen.
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_off Disable Service to disconnect the system from TrueNAS Connect.
See connect.truenas.com for more information.
When configured, the Directory Services Monitor icon button displays the status of Active Directory and LDAP services.
Click on either service to go to its configuration screen.
The Running Jobs 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.
For more information, see Jobs Screens.
The Alerts 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. You can also select the All Alerts, Critical, Warnings, Info, or Dismissed alert type tabs to filter alerts by type.
Use the 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.
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.
Each screen in TrueNAS displays relevant alerts with an admonition box.
Click Learn More on an admonition to view documentation related to the issue, or click close to dismiss the alert.
The Settings button shows a menu of general system settings options. The options are Change Password, Preferences, Two-Factor Authentication (when Global 2FA is enabled), My API Keys, Guide, and Log Out.
The Change Password button displays a dialog where you can change the login password for the currently logged-in administrator.
The Preferences option opens a screen with Theme, Session Timeout, and Localization settings to customize the UI for the currently logged in user account.
The Two-Factor Authentication button displays only when Global 2FA is enabled and opens the Two Factor Auth screen. Users can also access this screen from Credentials > Two Factor Auth.
The My 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 Guide button opens the TrueNAS Documentation Hub website in a new browser tab.
The Log Out button logs the current user out of the TrueNAS UI.
The Preferences screen customizes the UI screens for the currently logged-in user.
| Setting | Description |
|---|---|
| Theme | Sets the UI color theme for the currently logged-in user. Options are: ixDark (default option), ixBlue, Dracula, Nord, Paper, Solarized Dark, Midnight, and High Contrast. Selecting an option immediately changes the UI to the selected color theme. |
| Session Timeout | Sets the number of seconds a session remains active or inactive before it is automatically ended by logging out the user. |
| Language | Sets the lauguage for the UI screen. The default setting is English, but it might be customized to the language based on the country of origin for an Enterprise customer. You can filter the list by typing in the field after clearing the default value, or use the scroll option to find and select a language. |
| Date Format | Sets the desired date format for the UI. |
| Time Format | Sets the desired time format for the UI. |
The Power button provides two options that let the user restart or shut down their TrueNAS system.
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 arrow beside the State or ID header to change the display order, or the arrow to return to the top down display order.
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 TrueNAS Dashboard is the first screen you see after logging in. It displays system, storage, and network information widgets that can be customized to suit your preferences.
Customizing the Dashboard
This section contains tutorials for the main Dashboard.
You can customize the main Dashboard by moving, adding, or deleting widgets.
Click Configure to put the Dashboard into configuration mode.
While in configuration mode all widgets show as widget groups that are surronded by dotted line borders. Each widget group includes a drag handle, and the edit and delete icon buttons.
To move a widget to a new position on the Dashboard screen, click Configure to put the screen into configuration mode.
Locate the widget you want to reposition.
Click on and hold the drag handle at the top center of the widget group, then drag the widget to the desired position on the screen.
After moving widgets, click Save at the top right of the screen to exit configuration mode and show widgets in the new positions.
You can add new widgets to the dashboard or change existing widgets to a new layout, category, or type.
Click Configure at the top right of the screen to put the screen into configuration mode.
If adding a new widget, click Add to open the Widget Editor.
If changing an existing widget, locate the widget group on the screen, then click Edit at the top right of that widget group to open the Widget Editor with the layout and settings for that widget group.
Click on the layout image you want to use. The image on the screen show the new widget layout.
If adding a new widget, the default layout is full size with the category and type set to Empty.
If editing an existing widget, the current layout changes to show the existing category and type in the first widget of the new layout. An error shows in the selected widget of the group if the widget size does not support the selected category and type.
Select the widget in the group you want to add or change. If the layout includes half and/or quarter size widgets, the first widget in the group is selected by default.
To configure another widget in the layout, select the position in the group you want to configure.
Select the Widget Category and Widget Type to apply to the selected widget. For example, if configuring a network widget, you can use one full size layout or select one with half and quarter size widgets. The example below shows two layout options for configuring a network widget.
If the selected category is not supported for the selected widget, either select a new layout or change the Widget Category and/or Widget Type to one the widget supports.
(Optional) Edit the next widget in the widget group for the selected layout. After adding or changing the widget category and type, either click on the next widget in the group to configure it.
Click Save to close the Widget Editor and return to the Dashboard.
Edit or add as many widgets 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.
To delete a widget from the Dashboard screen, click Configure to put the screen into configuration mode.
Click the Delete icon in the widget group to delete the widget 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 widget.
Dashboard Screen
The Dashboard is the first screen you see after logging into the web interface after installing TrueNAS. It displays a set of default widgets 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 widget displays on or off.
The Dashboard widgets show information about the TrueNAS system basic settings, CPU and memory usage, network traffic and link status, storage, and backup tasks. Dashboard widgets are customizable. Options include changing widget layouts and the location on the screen and adding custom or application widgets.
Pool and network interface widgets vary based on system storage and network configurations.
Click on the Reports icon to display the data report screen that corresponds to the widget category. For example, clicking the assessment icon on the CPU widget opens the Reporting > CPU screen.
System Information Widget
The System Information widget shows general information about the TrueNAS system. The Updates Available button opens the System > Update screen.
If installed on a customer-provided server, the widget shows a generic TrueNAS image.
If installed on iXsystems-provided hardware, the widget shows a picture of the system. Click on the image to display the View Enclosure screen.
| Field | Description |
|---|---|
| Platform | 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 icon to display the full name of the release installed and to copy the version to the clipboard. |
| Edition | Shows the edition of the currently installed software release of TrueNAS. |
| 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. |
| System Serial | Shows the unique serial number of the attached TrueNAS system. |
HA System Information Widgets
The two HA Active and Standby controller System Information widgets show only for systems licensed for HA.
Each HA active or standby System Information widget shows the same information found on the non-HA System Information widget but also shows the system serial number, system license number, and type. The standby controller widget shows the Initiate Failover button. The active controller widget shows the Check for Updates button.
CPU Widget
The CPU widgets 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 widget shows gauges and graphs showing CPU statistics:
- CPU Model widget 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 widget 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 widget shows the current temperature of the system CPU.
Memory Widget
The Memory widget shows current system memory consumption information.
The widget includes a gauge showing GiB Free in blue, ZFS Cache in fuchsia pink, and Services in orange.
You can configure the memory widget as one large (100%) or one long (50%) plus two quarter-size (25%) widget layouts.
Network and Interface Widgets
The Network widget shows two widgets, 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 widget to the Interface widget and set each to the interfaces on your system. An Interface widget shows traffic, link status, interface media type and subtype, and any VLANS and the IP Address and port number.
Storage and Pool Widgets
The Storage widget 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 widget includes the Create Pool widget that when clicked, opens the Pool Creation Wizard screen. You can configure individual pool widgets that show the same information as the root pool in the Storage widget.
Backup Tasks Widget
The Backup Task widget 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.
When a backup task exists, the widget shows details about the various backup tasks configured on the system.
The widget 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 Widget
The TrueNAS Help widget shows links to various TrueNAS websites.
Links included are:
- TrueNAS Documentation Site
- TrueNAS Community Forums
- TrueNAS Newsletter where users can sign up for the newsletter.
- TrueNAS Open Source software
Click on each link to open it in a new browser tab.
In configuration mode, dashboard widgets are enclosed in dotted-line boxes to show the grouping area for each widget.
Add opens a blank Widget Editor screen.
Save saves all changes made to the dashboard.
Cancel closes configuration mode without saving any changes. Changes made and saved on the Widget Editor screen are discarded if you click Cancel.
Add opens a blank Widget Editor.
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 widget group area configurations or placements.
Widget groups (areas) can use one of five layouts that consist of other widgets of different sizes and configurations. Layout options show on the Widget Editor screen.
Each grouping area shows three function icons:
Drag handle that allows you to grab and move the widget to a new location on the screen. Dragging a widget to a new location shifts the other widgets one position to the left or right depending on where the dragged widget is placed.
Edit opens the Widget Editor populated with the settings for the existing widget.
Delete removes the widget from the Dashboard.
Pressing Tab allows selecting the next button or function icon on the screen and across all widget groups.
Access to the Widget Editor screen is available when the Dashboard screen is in configuration mode. The edit icon for any widget group opens the Widget Editor populated with the current settings for that widget group. Add opens the Widget Editor with no settings.
Select an individual widget in a layout with multiple widgets to change the category and type and customize the display of the widget group.
| Setting | Description |
|---|---|
| Layouts | Click on the layout image to add one to four widgets in the group. Not all widget categories support all layouts. |
| Widget Category | Select the information category from the dropdown list of options: |
| Widget Type | Select the type of information to show in the selected widget. Options change based on the selected Widget Category. See Widget Type Options by Category for information on the options by the category and type selected. |
Widget Type Options for System Information
The System Information widget has six Widget 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 widget types.
The dashboard in larger systems with hundreds of drives have a slower response when populating the screen widgets in normal and configuration mode. Be patient and wait until your system is fully online before attempting to customize dashboard widgets.
HA-licensed system dashboards show the active and standby controller widgets in a full-size widget.
The System Information widget displays the following Widget 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 widget. These can be included in a widget group with other widget categories and types to create a mixed information widget.
Storage
The TrueNAS Storage section provides controls for pools, disk management, and storage configuration. This section also provides access to datasets, zvols, quotas, and permissions.
Pools
TrueNAS pools are ZFS storage containers that combine physical disks to provide storage capacity and data protection.
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.
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.
Importing SED Drives
When importing SED drives into a pool, TrueNAS automatically detects locked SED disks before the import, shows information about locked drives, and provides the option to unlock or skip a listed drive.
Use the individual disk SED password if the disk is locked by an indivisual password, otherwise use the global SED password to unlock it. After clicking Unlock the Import Pool shows you the global password field and gives you the option to unlock disks.
Skip proceeds with the import with only the unlocked disk.
Creating Pools
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
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.
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.
Click Create Pool to open the Pool Creation Wizard.
Enter a name of up to 50 lowercase alpha-numeric characters. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters. Use only the permitted special characters that conform to ZFS naming conventions. Names can have upper or lowercase alphanumeric characters, but use lower-case alpha characters to avoid potential problems with sharing protocols. Names can have special characters such as underscore (_), hyphen (-), colon (:), or a period (.), but do not begin a pool name with a special character.
You cannot change the pool name after creation.Select the encryption option for the pool. Select None to create an unencrypted pool. We recommend not encrypting the pool root dataset or the system dataset. If creating a second pool on your system and you want to encrypt this pool, select Software Encryption (ZFS). All datasets created with this option selected are also encrypted by default.
TrueNAS EnterpriseIf your Enterprise system is licensed for and has SED drives, you can select Self-Encrypting Drives (SED) to create a pool with SED drives and encryption. You may only select SEDs when using Self-Encrypting Drives (SED) encryption.
Enter and confirm the global SED password. This applies to all SED drives in the system.
(Enterprise systems only) Select the Enclosure Option to apply the dispersal strategy of your choice.
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.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.
Create the required data VDEV.
Pool Creation Wizard 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.
The Layouts field shows the following options:
Stripe
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.
<!-- comment out the setting automation tag {id="pool_create_auto-select"} -->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. 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. 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 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. 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.
See vdev_draid.c for more information.
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.
Creating 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).
On the Storage Dashboard, click Create Pool, or click Add To Pool, then select New 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.
Add disks to the Data vdev, then click on the Metadata option to add a disk or disks to the VDEV.
Click Save And Go To Review, then click Save to create the VDEV.
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. We suggest using 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 using 3-way mirrors for your metadata VDEVs.
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.
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. To see if the AutoTRIM function is enabled, locate the Storage Health widget for the pool.
To enable or disable the function, click on the dropdown menu and select AutoTRIM to open the Pool Options for poolname dialog.
Select Auto TRIM.
Click Save.
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.
Use the Disconnect button to delete or export a pool and transfer drives to a new system where you can import the pool. Deleting the pool also deletes any data stored on it.
Backup critical data stored in the pool you intend to export or delete before performing these procedures!
Click on Disconnect for the pool on the Storage Dashboard to open the *Disconnect poolname window.
After backing up critical data stored in the pool you plan to export, click Disconnect for the pool.
Click Export Pool in the *Disconnect poolname window.
Leave Delete saved configuration from TrueNAS? option selected and then select the Confirm Export Pool option to activate the Disconnect button.
Click Disconnect to begin the export.
After backing up critical data stored in the pool you plan to export, click Disconnect for the pool.
Click Delete Pool in the *Disconnect poolname window.
To delete the pool and erase all the data on the pool, leave Remove all releated configurations selected, and then select Confirm Delete Pool. Enter the pool name in the confirmation text field, to activate the Disconnect button.
Click Disconnect to delete the pool. A confirmation dialog opens when the delete operation completes.
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.
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.
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 corrects them or generates an alert in the web interface.
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, number of threshold days, and enable or disable the scheduled scrub.
Threshold Days sets the days before a completed scrub can 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, TrueNAS 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.
The Disks button on the Storage Dashboard screen and the View Disks button on the Disk Health widget 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.
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 you use one of the above methods, TrueNAS does not automatically expand the pool to fit newly available space.
To expand an existing pool:
- Navigate to Storage, click on the dropdown menu, and select Expand Pool.
- Select Confirm in the Expand Pool pop-up screen.
- Click Continue to initiate the pool expansion process.
TrueNAS expands the pool to use the additional available capacity.
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 RAIDZ extensions 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 are 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 because 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. Replicate and rewrite the data to the extended pool to manually recover capacity.
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.
For more information, read the article written by Jim Salter at Ars Technica and the upstream RAIDZ extension PR, sponsored by iXsystems, at OpenZFS. See also “ZFS RAIDZ Expansion Is Awesome but Has a Small Caveat” by Louwrentius for an in-depth discussion of lost capacity and recovering overhead.
To extend a RAIDZ VDEV, go to Storage. Locate the pool and click View VDEVs on the VDEVs widget to open the Poolname VDEVs screen.
Select the target VDEV and click Extend to open the Extend Vdev window.
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.
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.
To add a VDEV to an existing pool, you can:
Click Add To Pool to open the Add To Pool window, and select Existing Pool. Select the pool on the Existing Pool dropdown.
or
Click View VDEVs on the VDEVs widget to open the Poolname VDEVs screen, then click Add VDEV to open the Add Vdevs to Pool wizard.
Enterprise systems that are licensed for and contain SEDs display a message about SED encryption, indicating that only SED-capable disks are available for VDEV selection within the SED-encrypted pool. Pools that are not SED encrypted do not display this message.
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.
Select the layout, mirror, or stripe.
Select the disk size to use the Automated Disk Selection option. 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.
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. The Manual Selection screen closes and returns to the Add Vdev to Pool wizard screen (in this case, the Spare option).You can 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.Adding a VDEV Manually
Repeat the same process above for each type of vdev to add.
Click Save and Go to Review to show 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.
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 adding duplicated files 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). When pruning the size, select the percentage or age measurement to use.
Use Set Quota to set the DDT quota. This 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.
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 unavailable, you can off-line 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.
Click Offline on the ZFS Info widget to take the disk offline. The button toggles to Online.
Remove the disk from the system.
Insert a larger capacity disk into an open enclosure slot (or if no empty slots, the slot of the offline disk being replaced).
a. Click Replace on the Disk Info widget on the Poolname Devices screen for the disk you off-lined.
b. Select the new drive from the Member Disk dropdown list on the Replacing disk diskname dialog.
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. This can take a long time for pools with large amounts of data. 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.
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 can significantly impact read and write performance.
In addition, you can remove a data VDEV from an existing pool under specific circumstances. This process preserves data integrity but has multiple requirements:
Upgrade the pool with the
device_removalzfs feature flag.The pool must be upgraded to a ZFS version with the
device_removalfeature flag. The system shows the Upgrade button after upgrading TrueNAS when new ZFS feature flags are available.Use mirror or stripe VDEVs.
All top-level VDEVs in the pool must be only mirrors or stripes.
Keep special VDEVs in RAIDz data VDEVs.
Special VDEVs cannot be removed when RAIDZ data VDEVs are present.
Use the same basic allocation unit size.
All top-level VDEVs in the pool must use the same basic allocation unit size (
ashift).Maintain sufficient free space in the data VDEV for removed data.
The remaining data VDEVs must contain sufficient free space to hold all data from the removed VDEV.
It is generally not possible to remove a device when a RAIDZ data VDEV is present.
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.
Pool Creation Wizard Screen
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.
Unassigned Disks shows the number of available disks by size on the system. This list dynamically updates as disks move to VDEVs added in the wizard.
The Pool Creation Wizard for most systems has seven configuration screens, numbered in sequence, to create a pool with VDEVs.
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.
The General Info shows the Name and Encryption options: None or Software Encryption ZFS, and shows available disks listed under Select disks you want to use. When available disks are exported from a pool, a message alerting you to this shows above the disk options.
| Setting | Description |
|---|---|
| Name | Sets the pool name, which can have up to 50 characters and must follow ZFS naming conventions. Names can have upper or lowercase alphanumeric characters, but use lower-case alpha characters to avoid potential problems with sharing protocols. Names can have special characters such as underscore (_), hyphen (-), colon (:), or a period (.), but do not begin a pool name with a special character. |
| Encryption | Shows two options: None and Software Encryption (ZFS). None does not apply encryption to the pool. Software Encryption (ZFS) applies ZFS encryption for the pool and all datasets (or zvols) within the pool created using the TrueNAS UI. Do not encrypt the root pool or the system dataset pool! All child datasets in an encrypted pool are encrypted and cannot be unencrypted. Best practice to allow the option for encrypted or unencrypted datasets in the pool is to create a new child dataset with encryption and leave the root dataset for the pool unencrypted. |
| Select disks you want to use | Shows disk options to select disk from, and if the options are disks from exported pools, a warning message shows just above the options. If system disks have non-unique serial numbers, a warning displays with additional fields. 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. |
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.
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.
Enterprise systems licensed for and containing SED encryption can use the Self Encryption Drives (SED) encryption type.
The General Info wizard screen shows the Self Encryption Drives (SED) radio button and options in addition to other General Info setting for non SED-licensed systems.
After selecting the Self Encryption Drives (SED) radio button, the Global SED Password and Confirm SED Password fields show.
The Global SED Password is a system-wide setting. A message shows above this field indicating if a password is already configured, and that entering a new password updates it for all pools using SED encryption.
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 the 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.
Common Pool Creation Wizard Settings
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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
The Log wizard screen settings configure a log VDEV. ZFS log devices can improve synchronous write speeds.
Common Pool Creation Wizard Settings
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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
The Spare wizard screen settings configure a hot spare for a drive in a data VDEV.
Common Pool Creation Wizard Settings
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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
The Cache wizard screen settings configure a ZFS L2ARC read-cache VDEV.
Common Pool Creation Wizard Settings
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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
The Metadata wizard screen settings configure a special allocation class VDEV. Metadata VDEVs are used to speed up metadata and blocks below configured size. Use when creating a fusion pool.
Common Pool Creation Wizard Settings
The Layout dropdown list includes the Stripe, Mirror, RAIDZ1, RAIDZ2, RAIDZ3, dRAID1, dRAID2, and dRAID3 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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
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.
Common Pool Creation Wizard Settings
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.
The Layouts field shows the following options:
Stripe
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.
| 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. |
| 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. |
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 |
|---|---|
| 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. |
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.
| Setting | Description |
|---|---|
| Search | Enter the disk name or other details to search for disks matching the specified value to filter available disks in the system. |
| Filter by Disk Type | Resets the available disks listed to show only the selected type (HDD or SSD). |
| Filter by Disk Size | Resets the available disks listed to show only disks matching the selected size. |
| TrueNAS System | Click to expand and show the list of available disks in the system. Filter options change the disks displayed on this list. |
The Review wizard screen shows a summary of VDEVs in the pool configuration.
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.
VDEV Screens
The VDEVs screen lists VDEVS and disks configured for the selected pool. Go to Storage and click on View VDEVs on the VDEVs card to view the VDEVs screen.
Click anywhere on the VDEV to see the drives in it and the ZFS Info card for that VDEV.
Click anywhere on a drive to see the drive cards.
Add VDEV opens the Add a VDEVs to Pool screen with the Pool Creation Wizard for the selected pool. For example, find the VDEVS card for a pool and click View VDEVs. This opens the Pool Creation Wizard with tank prepopulated but not editable.
The ZFS Info card 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 card to remove the drive from the VDEV (pool).
Each disk in a VDEV has two cards that show information for that disk: ZFS Info and Disk Info. After selecting a disk, the cards show on the right side of the screen in the Details for diskname area of the screen.
The ZFS Info card 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.
Detach opens a confirmation dialog and removes the selected drive from the parent VDEV.
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 card 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.
Replace opens the Replacing disk diskname dialog, where diskname is the name of the selected disk.
The Hardware Disk Encryption card only shows on Enterprise systems with an SED license and with SED drives.
The Hardware Disk Encryption card shows drive information, like whether the SED password is set or not. It might show on non-enterprise systems with self-encrypting drives, but not all configuration options show in the UI. Community users should use the SED utilities to manage these drives.
The Manage SED Password link opens a Manage SED Password dialog, where you can enter a disk SED password to set the disk encryption password.
Global SED Password shows the status as set or not set. The Manage Global SED Password link opens the System Settings > Advanced screen, where you can change the global SED password that overrides the disk passwords.
The *Replacing disk diskname dialog allows replacing the selected disk with a new disk selected from the Member Disk dropdown list.
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.
Disks
TrueNAS provides tools to manage, replace, and wipe the physical drives installed in your system.
Replacing Disks
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:
- Take the disk offline.
- Replace the disk.
- Refresh the screen.
To replace a disk in a pool with a hot spare:
- Take the disk offline.
- Detach the failed disk to promote the hot spare.
- Refresh the screen.
- Recreate the hot spare VDEV.
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.
The Storage Dashboard pool widgets also show the status of each of your pools.
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.
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.
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.
A Hot Spare vdev sets up a disk 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.
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.
After promoting the hot spare, recreate the Spare vdev and assign a disk to it.
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.
Click the Spare (Optional) row to expand it.
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.
SLOG Over-Provisioning
Over-provisioning an SSD distributes the total number of writes and erases across more flash blocks on the drive. Seagate provides a thoughtful investigation into over-provisioning SSDs here: https://www.seagate.com/blog/ssd-over-provisioning-benefits-master-ti/.
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.
TrueNAS Customer Support Support Portal https://support.ixsystems.com support@ixsystems.com Telephone and Other Resources https://www.ixsystems.com/support/
Managing Self-Encrypting Drives (SED)
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later) that requires an active SED license. 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.
- Legacy interface for older ATA devices (Not recommended for security-critical environments!)
- TCG Opal 1 legacy specification
- TCG Opal 2 standard for newer consumer-grade devices
- TCG Opalite, which is a reduced form of OPAL 2
- 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.
- TCG Ruby 1.0
See this Trusted Computing Group and NVM Express® joint white paper for more details about these specifications.
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.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later) that requires an active SED license. 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.
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.
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive card.
Click Configure to open the Self-Encrypting Drive configuration screen.
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!
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 for a confirmed SED to expand the row. Click Edit to open the Edit Disk screen.
Enter the password in the SED Password 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.
Select Clear SED Password to clear the existing password, and click Save. Reopen the Edit Disk screen to enter and save a new password.
Repeat this process for each SED and any SEDs added to the system in the future.
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.
Improper use of thesedutil-clican 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.
Disks Screen
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 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.
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. An expanded disk on an Enterprise systems licensed for SED drives shows SED options.
Edit opens the Edit Disk screen.
If a disk is not associated with a pool and is inactive, the Wipe option shows. Wipe opens the Wipe Disk dialog.
An SED disks shows the SED Reset and Unlock options.
Select a checkbox to the left of a disk on the Disks screen to display the Batch Operations functions: Edit Disk(s).
Edit Disk(s) opens the Bulk Edit Disks screen.
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.
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.
Wipe opens the wipe disk confirmation dialog.
Confirm activates Continue, and 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.
The Unlock button opens the Unlock SED for diskname dialog with the Password field where you enter the SED password to unlock the disk with the global SED password or the individual disk SED password if one is assigned to the disk.
The SED Reset button opens the SED Reset - Secure Erase window. This window shows a critical warning stating the operation is irreversible and permanently destroys all data on the disk.
Reseting the SED is a destructive process and should only be used as a last resort after all data on the disk and in the pool is backup to a secure location.
Physical Security ID (PSID) requires entering the PSID from the label on the drive.
I understand this will permanently destroy all data on this disk is required and confirms you understand this is a destructive process before you can proceed.
Where to find the PSID provides information on the physical label on a disk.
Example PSID format shows an example of the label PSID to help you locate the correct number on the disk.
Perform SED Reset activates after entering the required information and selecting the I understand… option. Cancel closes the window without performing the reset.
The Edit Disk screen allows users to configure and manage general disk, power management, 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.
| Setting | Description |
|---|---|
| Name | Shows the current name of the disk. To change, enter a Linux disk device name. |
| Serial | Shows the serial number for the selected disk. To change, enter the disk serial number. |
| Description | Text-entry field for typed notes about this disk. |
| Setting | Description |
|---|---|
| HDD Standby | Shows a list of options or leave 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: |
Shows only for SED disks in an SED-licensed Enterprise system.
SED Password sets or changes the individual password of this SED disk. When entered, TrueNAS uses this password instead of the global SED password.
Clear SED Password clears an individual password assigned to the SED disk.
Drive Health Management
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 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.
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 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.
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.
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.
| 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. |
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.
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.
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.
We recommend scheduling SMART tests so that they do not overlap with other data protection tasks like snapshot creation or removal, or pool scrubs.
To run a manual test, go to System > Shell and run:
smartctl -t {short/long} /dev/<device>
Choose whether to run a short or long test and replace /dev/<device> with the target disk device name. Repeat for all devices as needed.
Example: smartctl -t short /dev/sda
To review manual test output, go to System > Shell and run:
smartctl -a /dev/<device>
For a full reference of smartctl options and output interpretation, see the smartmontools documentation.
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} '["*"]'
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.
Storage Dashboard Screens
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.
The No Pools screen displays before you add the first pool.
The Create Pool button in the center of the screen opens the Pool Creation Wizard screen.
After adding pools, the dashboard shows the pool widgets, the Update and Disconnect buttons, and a dropdown menu with more options: Expand Pool and AutoTrim.
The buttons at the top right of the Storage Dashboard screen provide access to pool and disk functions:
Import Pool
Import Pool opens the Import Pool screen.
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.
Disks opens the Disks screen.
Create Pool opens the Pool Creation Wizard.
Disconnect Button
The Disconnect button opens a Disconnect Pool: poolname window with two options: Export Pool and Delete Pool. Each option changes what shows in this window.
The Disconnect Pool window shows a different warning statement below the delete and export options. The Delete Pool warning states all data is deleted from the pool, and instructs users to back up critical data before deleting the pool. The Export Pool warning states you lose access to data in the exported pool until you import the pool, and instructs users to back up criical data before exporting the pool.
Expand the System dataset will be moved off this pool message to shows the full statement about the system dataset.
Exporting/deleting 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.
Figure 3: Disconnect Delete Pool Window 
Figure 4: Disconnect Export Pool Window The Remove all related configurations and Confirm Delete Pool shows at the bottom of the window after selecting Delete Pool. The text field below shows after selecting the Remove all related configuration option. This field accepts typed or copy/paste of the pool name.
Deleted Saved Configurations from TrueNAS and Confirm Export Pool shows at the bottom of the window after selecting Export Pool. A text field below these options shows after selecting Confirm Export Pool. This field accepts typed or copy/paste of the pool name.
Disconnect activates after entering the pool name in the confirmation field.
Disks in an exported pool become available for 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.
A status window shows progress. When complete, a final dialog states that the export/disconnect completed successfully.
AutoTrim
The Auto TRIM option on the dropdown menu opens the AutoTRIM dialog. The ZFS Health widget shows whether this function is set to on.
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
autotrimproperty description in zpool.8.Upgrade
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.
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.
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 Window
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.
The Add To Pool window has three radio buttons:
- New Pool opens the Pool Creation Wizard.
- Existing Pool shows the Existing Pool dropdown list of available pool options.
- Existing Pool (Legacy) adds the Existing Pool dropdown list of available pool options.
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.
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.
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.
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.
View Datasets opens the Datasets screen.
The Storage Health widget shows health-of-the-pool information.
Possible widget details include:
- Pool status shows the pool status as** Online, no errors** or Offline, Degraded no errors.
- Scheduled Scrub shows the time based on a 24-hour clock and frequency of a scheduled scrub (the day the task runs).
- Auto TRIM shows when the auto trim feature is on or off.
- Last Scan shows the date and time of the last completed scrub.
- Last Scan Errors shows the number of errors detected during the last scrub.
- Last Scan Duration shows the time, in minutes and seconds, that the last scrub ran.
- Deduplication Table only shows if a dedup VDEV is added to the pool. Shows the size of the deduplication table.
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.
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.
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.
Age shows the Age (in days) field where you enter the number of days between pruning processes the system waits before automatically pruning the DDT.
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.
Custom shows the Custom Qutoa field where you enter the maximum size of the DDT (quota).
None disables the quota.
The Disk Health widget shows information on the health of the disks in a pool.
The disk health details include:
- Disk temperature-related alerts
- Highest Temperature
- Lowest Temperature
- Average Disk Temperature
TrueNAS complies with SAS/SATA specifications and reports temperatures in Celsius. TrueNAS converts Kelvin to Celsius
View Disks opens the Storage > Disk screen.
View Reports opens the Report screen for the disks in the selected pool.
Datasets
This section has tutorials about dataset configuration and management.
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.
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.
Enter a value in 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).
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.
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.
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.
For more information on quotas, see Managing User or Group Quotas.
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.
For information on ACL settings see Setting Up Permissions.
Deduplication is found on the Add Datasets Advanced Settings screen.
To add deduplication to a new dataset, after entering the name and selecting the dataset preset, click Advanced Settings.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 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.
Click Continue.
Change Checksum to SHA512.
Complete any other setting changes you want to make, then click Save.
First, add the pool with a Metadata VDEV.
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 and select the Dataset Preset, then scroll down to the Use Metadata (Special) VDEVs setting.
Select On to enable storing data blocks in the special allocation class. The Threshold field appears. Enter a maximum block size (1 byte to 16 MiB) for blocks to store in the special class. The default threshold is 16 MiB. Blocks smaller than or equal to the threshold are assigned to the special allocation class; larger blocks are assigned to the regular class.
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.
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.
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.
For more information, see the Setting Up Permissions article.
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.
Encryption
TrueNAS supports dataset and zvol encryption to secure stored data at rest.
Encrypting Datasets
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.
Data-at-rest encryption is available with:
- Self Encrypting Drives (SEDs) using OPAL or FIPS 140.2 (Both AES 256)
- Encryption of specific datasets (AES-256-GCM)
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).
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.
If your system loses power or you restart the system, all encrypted datasets and zvols automatically lock to protect data.
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.
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).
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.
To add an encrypted dataset, go to Datasets.
Select a dataset in 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).
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.
To change to passphrase encryption, select Passphrase from the Encryption Type dropdown.
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.
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.
To change the passphrase for passphrase-encryption, enter a new passphrase in Passphrase and Confirm Passphrase.
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.
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.
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.
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.
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.
To change encryption properties from passphrase to key or enter a new key or passphrase, select the zvol, then click Edit on 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.
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.
To manually back up a root dataset key file, click Export Key on the Encryption widget.Always back up the key file to a safe and secure location.
See Changing Dataset-Level Encryption for more information on changing encryption settings.
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.
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.
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.
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.
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.
Encryption Screen
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. |
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 Options settings under Advanced Options on the Add Dataset screen configure encryption for that dataset.
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 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.
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 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.
Permissions
TrueNAS provides ACL-based permission controls for datasets to manage user and group access to stored data.
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.
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.
Only use NFSv4 ACLs with SMB shares. Using POSIX ACLs with SMB shares can result in unexpected permissions behavior.
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.
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.
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_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.
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.
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
rootpermissions 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_rootuser 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_rootwith the required access to any dataset paths used by the container.See Granting Root Access to Host Paths for more information.
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.
- 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.
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.
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.
Edit ACL Screen
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 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.
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.
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.
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.
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.
For an NFSv4 ACL, click Use Preset ACL on the Edit ACL screen to access the NFS4 Select a Preset ACL window.
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.
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.
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.
The POSIX Access Control Entry settings include Who, Permissions, and Flags options.
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.
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.
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 Permissions options for the user or group in Who.
Click the Basic radio button to display the flag settings that enable or disable ACE inheritance.
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.
Quotas
TrueNAS quota settings limit how much storage space a dataset, user, or group can consume.
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.
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.
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.
Capacity Settings Screen
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. |
User and Group Quota Screens
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
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.
The Show All Users toggle button displays all users or hides built-in users.
{< trueimage src="/images/SCALE/Datasets/UserQuotasDataQuotaSCALE.png" alt=“User Quotas List View” id=“User Quotas List View” >}}
Add opens the Set User Quotas screen.
If you have several user quotas set up, the Actions options include Set Quotas (Bulk).
Click on a user name to display the Edit User window.
The Edit User Quota window allows you to modify the user data quota and user object quota values for an individual user.
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. |
To display the Set User Quotas screen click the Add button.
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.
The Show All Groups toggle button displays all groups or hides built-in groups. Add displays the Set Group Quotas screen.
If you have several group quotas set up, the Actions options include Set Quotas (Bulk).
Click on a group name to display the Edit Group window.
!
The Edit Group window allows you to modify the group data quota and group object quota values for an individual group.
Click Save to set the quotas or click the “X” to exit without saving.
To display the Set Group Quotas screen, click the Add button.
Snapshots
TrueNAS snapshots capture the state of a dataset or zvol at a point in time, enabling data recovery without full backups.
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.
Taking snapshots requires the system have all pools, datasets, and zvols already configured.
Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.
There are two ways to access snapshot creation:
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.
Existing snapshots display as a list.
From the Datasets screen select the dataset to snapshot, then click Create Snapshot on the Data Protection 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
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.
- Go to Data Protection, locate the Periodic Snapshot Tasks widget, then click the Snapshots button in the lower right-hand corner of the widget.
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.
Click to view snapshot options.
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.
Click Clone to confirm.
The Go to Datasets button opens the Datasets screen.
Click on the clone name in the dataset listing to populate the Dataset Details widget and display the Promote button.
After clicking the Promote button, the dataset clone is promoted and this button no longer appears.
Promote now displays on the Dataset Details widget when you select the demoted parent dataset.
See zfs-promote.8 for more information.
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.
Click the Delete button. A confirmation dialog displays. Select Confirm to activate the Delete button.
To delete multiple snapshots, select the left column box for each snapshot to include. Click the delete Delete button that displays.
To search through the snapshots list by name, type a matching criteria into the search Filter 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.
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.
Click Confirm to activate the Rollback button.
All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden
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.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
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
Snapshots Screens
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.
Enter a dataset path in the search field at the top of the screen to check for snapshots for other datasets.
Add opens the Add Snapshot screen.
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.
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. |
| Rollback | Opens the Dataset Rollback From Snapshot window with three radio button options. Confirm activates the Rollback button. |
| Hold | 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. |
The snapshot Rollback option replaces the data in the selected dataset with the information saved in the snapshot.
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.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.
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.
Click Clone to confirm.
The Go to Datasets button opens the Datasets screen.
Click on the clone name in the dataset listing to populate the Dataset Details widget and display the Promote button.
After clicking the Promote button, the dataset clone is promoted and this button no longer appears.
Promote now displays on the Dataset Details widget when you select the demoted parent dataset.
See zfs-promote.8 for more information.
The snapshot Delete option opens a window that lists the snapshot(s) you select.
Confirm activates the Delete button.
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.
Batch Operations Delete opens a window listing all selected snapshots.
Confirm activates the Delete button. If a snapshot has the Hold option selected, an error displays to prevent you from deleting that snapshot.
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.
Zvols
Zvols are block-level datasets used as virtual disks for virtual machines and iSCSI shares.
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.
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.
First, add the pool with a Metadata VDEV.
Select the root dataset of the pool (with the metadata VDEV), then click Add Zvol.
Enter a name and size for the zvol, then scroll down to the Use Metadata (Special) VDEVs setting.
Select On to enable storing data blocks in the special allocation class. The Threshold field appears. Enter a maximum block size (1 byte to 16 MiB) for blocks to store in the special class. The default threshold is 16 MiB. Blocks smaller than or equal to the threshold are assigned to the special allocation class; larger blocks are assigned to the regular class.
Click Save.
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.
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.
Zvols Screen
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.
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.
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.
Edit opens the Edit Zvol screen for the selected zvol.
Delete opens the Delete zvol dialog.
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.
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.
Edit opens the Edit Encryption Options for zvol window for the selected zvol.
For more details on encryption windows and functions, see Encryption Settings.
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.
Take Snapshot opens the Add Snapshot screen.
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.
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.
| Setting | Description |
|---|---|
| Zvol name | (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:
|
| 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). |
| Use Metadata (Special) VDEVs | Enables storing data blocks in a special allocation class (fusion pool) metadata VDEV. Options:
|
| 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. |
Depending on their workload, zvols can require additional tuning for optimal performance. See the OpenZFS handbook workload tuning chapter for more information.
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.
Datasets Screens
The Datasets screen and cards 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.
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 datasetname dataset cards 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.
Add Zvol opens the Add Zvol screen.
Add Dataset opens the Add Dataset screen.
Begin typing the name of a dataset in the Search field to filter datasets to a short list of those matching what is typed.
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 cards 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 card. 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 card. |
| 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. |
| NVMe-oF Share |  | Indicates the dataset or zvol is used by an NVMe-oF 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. |
Each dataset has a set of information cards (cards) in the Details for datasetname area of the screen. These cards and information is grouped by functional areas. The cards for a root or parent dataset differ from a child dataset, or a dataset used by another service or with encryption.
Dataset cards are:
The Details card shows information about the dataset that allows you to manage an existing dataset.
Information includes:
- 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 card 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 card 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.
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.
The Space Management card shows the total space allocation (data written, children of the dataset, available space). The card shows if an encrypted dataset is unlocked. After locking the dataset, this card disappears until you unlock the dataset.
The donut graph on the card 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.
The Data Protection card shows snapshot and backup task information for the dataset.
Take Snapshot opens the Add Snapshot screen.
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.
The Permissions card 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 card shows the owner and type of access control list (ACL) and ACL Entries (ACEs) for the dataset in the lower portion of the card. Owner shows both the onwer user and group on one line, formatted as owner:group. For example, Owner: root:root.
The permission screen and card options vary based on the ACL type. Root datasets have POSIX permissions, and the entries are not editable.
Non-root dataset can be POSIX or NFSv4 based on the Dataset Preset selected when you create the dataset.
NFSv4 ACL type (the default ACL type) shows the user and group entries on the Permissions card as buttons that show selectable options to change selectable Permissions Advanced and Flags Advanced options for that entry on the Permissions card.
Edit for a POSIX ACL opens the Unix Permissions Editor screen. Root datasets do not show the Edit button.
Edit for an NFSv4 ACL opens the Edit ACL screen.
The Usage card 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 card shows two links: Create SMB Share that opens the Add SMB screen and Create NFS Share that opens the Add NFS screen.
The Usage card for a parent dataset with child datasets with shares shows this, but does not link to other screens.
| Usage | Link Included | Description |
|---|---|---|
| System dataset | Manage Advanced Settings | Select the option to configure the System Dataset |
| Apps | Manage Apps Settings | Shows the app using the dataset. |
| Dataset with no share | Create SMB Share Create NFS Share | Opens either the Add SMB or Add NFS share screen to configure the share. |
| SMB share | Manage SMB Shares | Shows the name of the SMB share using the dataset. Select the snare on the Sharing SMB screen to edit it. |
| Other share | Link to the share type screen | Shows the name of the share using the dataset. Select the option on the share screen (NFS or iSCSI) to edit it. |
| Multiprotocol share | Manage SMB Shares Manage NFS Shares | 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. |
The Encryption card only shows for encrypted datasets. Options shown in the card 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 card shows Lock when the dataset is unlocked or Unlock when the dataset is locked. These are not available on the card for the root dataset. The dataset table also shows Locked or Unlocked by Parent.
The Encryption card 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.
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 card opens the Edit Dataset screen.
Edit on the Encryption card opens an encryption edit window. The Encryption card only shows if a dataset is encrypted. Edit on the Permissions card 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.
The Advanced Options screen shows:
- Quota management tools and settings
- Encryption Options settings
- Other Options settings
The Basic Options show on the Advanced Options screen.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
The Add Dataset and Edit Dataset screens show the Advanced Options button. Advanced Options show:
- Quota Management settings
- Encryption settings
- Other Options settings
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 card 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.
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 card 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.
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.
Other Options Settings
{id=“dataset_add_advance-other”}
| Setting | Description |
|---|---|
| Comment | 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: |
| 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: |
| 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: 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: |
| Checksum | Sets the checksum to the option selected on the dropdown list. Options:verify. |
| Setting | Description |
|---|---|
| Read-only | 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 |
| 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: |
| 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:--no-perms in the task Auxiliary Parameters field. |
| Use Metadata (Special) VDEVs | Enables storing data blocks in a special allocation class (fusion pool) metadata VDEV. Options: |
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.
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) share 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.
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.
Windows Shares (SMB)
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 to manage and administer 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.
Adding and Managing 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.
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.
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.
Create the SMB share user account.
You can manually add user accounts or use directory services like Active Directory or LDAP to provide additional user accounts. If setting up an external SMB share, we recommend using Active Directory or LDAP, or at a minimum, synchronizing the user accounts between systems.
Create the SMB share and dataset.
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 > Integrations Veeam 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.
After adding or modifying the user account for the share, edit the dataset permissions.
Start the service and mount the share to your other system.
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.
When accessing files through a web file share (WebShare) and an SMB share, you must configure the SMB share with the Multi-Protocol share Purpose preset. This configuration coordinates file access between the different protocols. It reduces, but does not eliminate, the risk of file conflicts. This configuration results in the SMB share experiencing a performance impact (slower response).
Note, even with this preset configuration, avoid simultaneous access to the same files from both protocols, since that can cause data corruption.
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.
Use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to restrict access later.
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.
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 name.
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.
A basic SMB share does not need to use the Advanced Options settings. Click Advanced Options to finish customizing the SMB share settings.
See SMB Shares Screens for all settings and other possible use cases.
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.
Configure filtering to audit only necessary operations.
Use Watch List to specify which groups should have their SMB operations audited. Use Ignore List to exclude specific groups from auditing.
- 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.
Configuring 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, you may need to 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.
To manage an SMB share, click 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 Share ACL opens the Share ACL screen, where you can add or edit ACL entries.
- 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.
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.
Configure filtering to audit only necessary operations.
Use Watch List to specify which groups should have their SMB operations audited. Use Ignore List to exclude specific groups from auditing.
- 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.
Configuring 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, you may need to 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.
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 widget, 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.
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 Edit 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.
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 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.
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.
Enter or select Group in the Who field.
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.
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.
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.
To connect to an SMB share, start the SMB service.
After adding or editing a share, TrueNAS prompts you to restart the SMB service so that changes take effect.
You can also start the service from the Windows (SMB) Share widget or on the System > Services screen from the SMB service row.
From the Sharing screen, click on the Windows (SMB) Shares 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.
To make SMB share available on the network, go to System > Services and click the SMB Start Service button to start the service. Toggle Start Automatically on if you want the service to activate when TrueNAS boots.
Configure the SMB service by clicking Config Service from the 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.
SMB Stateful Failover requires an Enterprise license and a High Availability (HA) configuration. When enabled, this setting is incompatible with:
- Enable SMB1 support
- Any share using the Multi-Protocol Share or Legacy Share purpose
- Any auxiliary SMB parameters
TrueNAS 26 and later supports stateful SMB HA failover for Enterprise systems. When enabled, TrueNAS maintains SMB session state across controller failover events, so SMB clients can recover existing connections without re-authentication.
TrueNAS blocks updates while this setting is active because the underlying CTDB clustering layer requires matching versions on both controllers.
To upgrade an HA system with Stateful Failover enabled:
- Disable Stateful Failover and click Save.
- Upgrade both controllers.
- Re-enable Stateful Failover and click Save.
Go to System > Services and click the edit Configure icon on the SMB service row to open the SMB Service screen.
Click Advanced Settings to expand the advanced options.
Select the Stateful Failover checkbox.
Click Save.
TrueNAS supports macOS Spotlight search on SMB shares through the TrueSearch indexing service. When enabled, macOS users can use native Finder search to quickly locate files on mounted SMB shares.
Spotlight search requires an Enterprise license or TrueNAS Connect configuration. If neither is configured, the Enable Search (Spotlight) setting is disabled and a notice displays with a link to configure TrueNAS Connect.
Go to System Settings > Services and locate the SMB service row.
Click the Configure icon to open the SMB Service screen.
Click Advanced Settings to expand the advanced options.
Select Enable Search (Spotlight).
Click Save.
After enabling, TrueSearch indexes all enabled SMB shares. Encrypted datasets are excluded from indexing to protect sensitive data.
TrueSearch indexes all enabled SMB shares globally. You cannot enable indexing for individual shares.
Open Finder.
Click Go > Connect to Server in the menu bar.
Enter the SMB share address in the format
smb://<TrueNAS-IP>/<sharename>and click Connect.Enter the username and password for a TrueNAS user account with access to the SMB share, then click Connect.
The mounted share appears in the Finder sidebar under Locations.
After mounting the SMB share:
Open Finder and navigate to the mounted SMB share.
Press Cmd+F or click the search icon in the Finder window.
Click the SMB share name in the search bar to set the search scope to the mounted share. Spotlight search does not return results from SMB shares when searching This Mac.
Enter search terms. Spotlight supports searching by file name, file content, and file type.
Search results appear as files are found in the TrueSearch index.
The instructions in this section cover mounting the SMB share on a system with the following operating systems.
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 or LDAP 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.
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*.
Add descriptions to each share that identify the purpose of the share. The description shows on the Windows (SMB) Shares widget and the SMB screen.
Save changes made to the share.
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 uses predefined setting options to establish an SMB share that fits a predefined purpose, such as a basic Time Machine share.
To set up a basic time machine share:
Create the user(s) for this SMB share. Go to Credentials > Users and click Add.
Create the share and dataset with Purpose set to Time Machine Share.
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. The Windows client often attempts to load all snapshots into the 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 Mac OS 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.
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. From this screen, you can create the dataset, enable the SMB2/3 protocol setting in the SMB service, and create the Time Machine share.
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.
Enter a value in 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).
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 widget, 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:
Set the Purpose to Time Machine Share.
TrueNAS selects Enabled by default to allow sharing of this path when you start the SMB service. 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.
You can configure the SMB service before adding the share. Alternatively, enable the setting from the Add SMB or Edit SMB screens while creating or modifying a 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. On the Services screen, if the SMB service is running, click the Stop Service button to turn it off. Then click edit Edit 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.
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_xattrTrueNAS 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.
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).
To set up a Final Cut Pro storage share, complete the following steps in order:
- Enable Apple SMB2/3 Protocol Extensions
- Create the Share and Dataset
- Configure Advanced Options (optional)
- Configure Dataset Permissions
- Start the SMB Service and Mount the Share
- Connect from Mac Client
Enable this service setting before creating the share.
Go to Shares and click on the Windows (SMB) Shares widget header.
Select Config Service to open the SMB Service screen.
Alternatively, go to System > Services, locate SMB, and click the edit configure button.
Click Advanced Settings to expand advanced options.
Select Enable Apple SMB2/3 Protocol Extensions.
Click Save.
If the SMB service is already running, restart it for the changes to take effect.
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.
Click Create Dataset.
Enter a name for the dataset (e.g., AppleMediaShare or FCPProjects) and click Create.
The dataset name populates the Name field and becomes the share name.
Select Final Cut Pro Storage Share from the Purpose dropdown.
(Optional) Enter a description such as Final Cut Pro project storage to identify the share’s purpose.
Ensure Enabled is selected to activate the share when the SMB service is running.
If Apple SMB2/3 Protocol Extensions are not enabled, a requirement error appears below the Purpose field.
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.
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.
Optionally enable Audit Logging:
- Select Enable Logging to track share access.
- 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.
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 Adding and Managing SMB Shares for detailed information on configuring ACL permissions.
If the SMB service is not running, start it from the Windows (SMB) Shares widget:
- Click on the widget header.
- Select Turn On Service.
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.
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.
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
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.
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.
Users with an SMB client cannot delete shadow copies. Instead, the administrator uses the TrueNAS web interface to remove snapshots.
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 to open the Sharing > SMB screen. Select the share, then click the 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.
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
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.
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).
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, LDAP, or Active Directory). Users that requires 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?
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, go to 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 from the options provided.
SMB Access is selected by default, and required for a user to have access to an SMB share.Select WebShare to give this user access to a WebShare.
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.
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.
(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 ValidationUsers 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.
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.
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 widget, 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 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.
Before creating the private share dataset, go to Datasets, select the parent dataset for the private share dataset, locate the Permissions card to view the owner and ACL entry permissions listed for that dataset. To see more details, click Edit to open the Edit ACL screen.
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.
To create 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.
Follow naming conventions for:
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 applies to your share needs.
Click Save.
Enable or restart the SMB service when prompted and make the share available on your network.
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 modify who can see or access the share when connecting to it through 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 Checking Parent Dataset File Permissions 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 that maintains the documents either FULL or CHANGE permissions.
Click Save when finished.
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 in the a Purpose dropdown list 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.
Follow the instructions in the Adding Private Dataset Shares section below to set up private and personal shares.
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. The 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.
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 Dataset Share 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.
Using SMB Shares with macOS Decomposed Unicode
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.
For more information see Unicode Normalization Forms or Combining Diacritical Marks.
Setting Up SMB Multichannel
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 link aggregation.
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.
If you already have clients connected to SMB shares, disconnect them before activating multichannel.
- Go to System > Services and click the 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.
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 connections
Get‑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
Get-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
}
]
}
]
SMB Shares Screens
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.
Add at the top right of the widget opens the Add SMB screen where you configure SMB shares.
After adding an SMB share, it is listed in the table on the widget.
The Windows (SMB) Shares 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 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 dropdown list for each share shows four options:
- Edit opens the Edit SMB screen.
- Edit Share ACL opens the Edit Share ACL screen.
- Edit Filesystem ACL opens the Edit ACL screen.
- Delete opens the Delete dialog.
The delete icon opens the Delete dialog.
Select Confirm to activate the Delete button.
The Shares > SMB screen shows an expanded presentation of the table on the Windows (SMB) Shares widget.
Shares in the breadcrumb at the top of the screen returns you to the main Shares dashboard.
SMB Sessions opens the SMB Status screen.
Columns shows a set of options to customize the list view. Options include Unselect All, Path, Description, Enabled, and Reset to Defaults.
Add opens the Add SMB configuration screen.
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 dropdown list at the right of each table row shows four options for a share:
- Edit opens the Edit SMB screen.
- Edit Share ACL opens the Edit Share ACL screen.
- Edit Filesystem ACL opens the Edit ACL screen.
- Delete displays the Delete dialog.
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.
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.
| Setting | Description |
|---|---|
| Path | 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 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: 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. |
| 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 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 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
See Legacy Share Settings for complete details on these options.
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.
| Setting | Description |
|---|---|
| Enable Logging | 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. |
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.
| Setting | Description |
|---|---|
| Use Apple-style Character Encoding | 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.
| Setting | Description |
|---|---|
| Time Machine Quota | Sets the quota for Time Machine shares in bytes. |
| VUID | 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.
| Setting | Description |
|---|---|
| Use Apple-style Character Encoding | 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.
| Setting | Description |
|---|---|
| Use Apple-style Character Encoding | 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_xattrTrueNAS 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.
The Legacy Share purpose is incompatible with the Stateful Failover SMB service setting.
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.
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. |
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. |
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 share Edit Share ACL icon on the Windows (SMB) Shares widget or the 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: |
| Permission | Sets the level of access to a selected predefined permission combination from the dropdown list. Options are: |
| Type | Sets how TrueNAS applies permissions to the share to the selected option on the dropdown list. Options are: |
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.
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 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
Unix (NFS) shares allow TrueNAS to share data with Unix-like operating systems and other NFS-compatible clients.
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.
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.
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.
Use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to restrict access later.
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.
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. Enter a value in Name. Select the Dataset Preset option you want to use. Options are: 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). 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.Creating a Dataset Using Add Dataset
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 icon to the left of /mnt to locate the dataset and populate the path.
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.
Click Add to the right of Allowed Hosts if you want to enter allowed networks and hosts.
If needed, adjust access permissions.
Click Save to create the share.
After adding the first NFS share, the system opens an enable service dialog.
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.
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.
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.
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.
To begin sharing, click the 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.
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 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.
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.
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.
NFS Shares Screens
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.
Add at the top right of the widget opens the Add NFS screen where you configure NFS shares.
After adding an NFS share, it is listed in the table on the widget.
The Unix (NFS) Share 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 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.
- NFS Sessions that opens the NFS Sessions 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 dropdown list for each share shows two options:
- Edit opens the Edit NFS screen.
- Delete opens the Delete dialog.
After adding the first NFS share, the system opens an enable service dialog.
Enable Service turns the NFS service on and changes the toolbar status to Running.The Enable toggle for each share shows the current status of the share. Disabling the share does not delete the configuration from the system.
The delete icon displays a delete confirmation dialog that removes the share from the system.
Select Confirm to activate the Delete button.
The NFS screen shows an expanded presentation of the table on the Unix (NFS) Shares widget.
Shares in the breadcrumb at the top of the screen returns you to the main Shares dashboard.
NFS Sessions opens the NFS Session screen.
Add opens the Add NFS configuration screen.
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 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.
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.
| Setting | Description |
|---|---|
| Path | 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 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 tune the share access permissions and define authorized networks. Advanced Options shows the Access settings listed below.
| Setting | Description |
|---|---|
| Read-Only | 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. |
| 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. |
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
- on the Shares > Unix (NFS) Shares widget
- NFS Sessions on the NFS screen
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.
Multiprotocol Shares
A multiprotocol share exposes the same dataset over both SMB and NFS simultaneously, so Windows clients and Unix-like systems can access the same data without duplicating storage. This is most useful in mixed environments where some clients lack an SMB client or where a Linux workload and Windows clients need shared access to the same files.
For many environments, a single-protocol SMB share is simpler to administer and delivers better performance. Linux clients can access SMB shares using mount.cifs.
Consider multiprotocol sharing when your environment genuinely requires concurrent access from both protocol types.
To protect data integrity, NFS clients must preserve extended attributes when copying files; otherwise, the copy can discard SMB metadata. We recommend NFSv4 with Active Directory and Kerberos authentication for the NFS side of the share, as NFS defaults provide limited access control. This is especially important for Enterprise environments.
TrueNAS enables SMB3 unix extensions for multiprotocol shares, allowing Linux clients with SMB3 POSIX support to use filesystem primitives beyond standard SMB semantics. Windows clients without unix extension support are unaffected.
When accessing files through a web file share (WebShare) and an SMB share, you must configure the SMB share with the Multi-Protocol share Purpose preset. This configuration coordinates file access between the different protocols. It reduces, but does not eliminate, the risk of file conflicts. This configuration results in the SMB share experiencing a performance impact (slower response).
Note, even with this preset configuration, avoid simultaneous access to the same files from both protocols, since that can cause data corruption.
TrueNAS provides two methods for adding a multiprotocol share. Which you choose depends on whether the dataset already exists.
If you are setting up multiprotocol sharing for the first time and do not yet have a dataset, use the Add Dataset method. TrueNAS creates the dataset, the SMB share, and the NFS share together in a single step. This is the recommended approach for new setups.
If you already have a dataset or NFS share and want to add Windows SMB access to it, use the Add SMB method. This configures the SMB share with the settings required for safe multiprotocol interoperability, including for paths accessed by local processes, containers, or FTP. If the dataset does not yet have an NFS share, you need to create one separately after adding the SMB share.
Before adding a multiprotocol share, start the SMB and NFS services. From the Shares screen, click on the Windows (SMB) Shares or Unix (NFS) Shares widget and select Turn On Service. From the System > Services screen, click Start Service for the SMB or NFS service. Toggle Start Automatically on to start the service when TrueNAS boots.
To configure service settings, click on the widget and select Config Service, or go to System > Services and click edit Edit for the service.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default SMB service settings. After adding a share, use the share toggle on the widget to enable or disable that individual share.
Open the NFS service settings using Config Service from the menu on the Unix (NFS) Shares widget. Alternatively, go to System > Services and click edit Edit for NFS. Select only NFSv4 on the Enabled Protocols dropdown list. For security hardening, we recommend disabling the NFSv3 protocol. Select Require Kerberos for NFSv4 if you are using Active Directory.
If Active Directory is already joined to the TrueNAS server, click Save, then reopen the NFS service screen. Click Add SPN to open the Add Kerberos SPN Entry dialog.
Click Yes when prompted to add a service principal name (SPN) entry. Enter the AD domain administrator user name and password in Name and Password.
TrueNAS automatically applies SPN credentials if you enable the NFS service with Require Kerberos for NFSv4 selected before joining Active Directory.
Click Save, then start the NFS service.
Each NFS share also has a toggle to enable or disable that individual share.
The NFS service does not automatically start on boot if all NFS shares remain encrypted and locked.
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.
If you are not using Active Directory, NFS access controls rely on client-reported UIDs rather than verified credentials. NFS without Kerberos has no robust per-user authentication, making it an inherently less secure configuration.
For Enterprise environments, we recommend joining TrueNAS to an Active Directory domain before creating the share. Configure a container (group or organizational unit), Kerberos admin, and user accounts in AD. This enables verified per-user authentication for NFS clients and is the most secure configuration for multiprotocol access.
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 allows you to create the dataset and add a multiprotocol (SMB and NFS) share using the Add Dataset screen. This is the recommended method when creating a multiprotocol share for the first time.
Select the parent dataset where you want to add the multiprotocol 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 applies the same settings as the Multi-Protocol Share option in Purpose on the Advanced Options for the Add SMB screen. To modify share settings after saving, go to Shares, click on the share, select Edit, and click Advanced Options.
After adding the dataset, edit the dataset ACL to configure permissions.
If you have an existing dataset or NFS share and want to add Windows SMB access, use this method. Adding a multiprotocol share from the Add SMB screen configures the SMB share with the correct settings for multiprotocol interoperability. These settings also apply to paths accessed by local processes, containers, or FTP. If the dataset does not yet have an NFS share, complete steps 6–8 below to create one after saving the SMB share.
To create the share and dataset, go to Shares and click Add on the Windows (SMB) Shares widget. The Add SMB screen opens.
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.
(Optional) Enter a Description to help explain the share purpose.
Click Save. TrueNAS prompts you to restart the SMB service. Click Restart SMB Service to apply the new share configuration immediately, or dismiss the prompt to apply changes later. Restarting causes a brief interruption for all connected SMB clients.
Configure the ACL when prompted.
If the dataset already has an NFS share, the multiprotocol share is now configured. Skip to Completing the Share Configuration.
If the dataset does not yet have an NFS share, continue with steps 6–8.
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.
After creating the multiprotocol share using either method, complete the following steps.
Go to Shares and edit the NFS share to configure additional settings.
Select the new share listed on Unix (NFS) Shares widget, click on the icon and then click Edit. The Edit NFS screen opens with the Basic Options settings showing.
If you are using Active Directory, we recommend enabling Kerberos security. Click Advanced Options and select KRB5 from the Security dropdown. This applies the Kerberos ticket generated when you joined Active Directory.
(Optional) Select Read-Only to prevent clients from writing to the share. Use this to expose the share as a read-only data source, for example when multiple teams need access to the same files but only one should be able to modify them.
Click Save.
Use the Edit ACL screen to verify that users and groups who need access to the share have the correct permissions.
To open the ACL editor from the Shares screen, select the share row on the Windows (SMB) Shares widget and click Edit Filesystem ACL.
Editing the dataset ACL sets permissions for both the SMB and NFS shares.
Alternatively, go to Datasets, select the dataset row created for the multiprotocol share on the Datasets table, then scroll down to the Permissions widget for the dataset. Click Edit to open the Edit ACL screen.
Review the Access Control List to verify the required users or groups are present with the correct permissions. If not, add an Access Control Entry (ACE).
Select User or Group from the Who dropdown. If using Active Directory, select Group and enter your AD group.
Enter or select the user or group name in the field below.
Set the appropriate level in the Permissions dropdown. Select Full Control to grant full read and write access.
Click Save Access Control List to apply the changes.
See Permissions for more information on editing dataset permissions.
After setting the dataset permission, connect to the share.
After creating and configuring the shares, connect to the multiprotocol share using either SMB or NFS. Supported clients include Windows, Apple, FreeBSD, and Linux/Unix systems.
For more information on accessing shares, see Mounting the SMB Share and Connecting to the NFS Share.
Block Shares (iSCSI)
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.
- dash (
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.
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.
There are a few different approaches for configuring and managing iSCSI-shared data:
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.
Adding iSCSI Block Shares
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.
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 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.
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.
Add the extent and select the device type.
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.
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.
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.
Add a target.
a. Click Add to open the Add iSCSI Target screen.
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.
a. Enter a name.
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.
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 description for the portal if desired.
b. Click Add to show the IP Address field. Enter the IP address and netmask (CIDR) for the portal. Click Add for each IP address to add.
Enter 0.0.0.0 to listen on all IPv4 addresses, :: to listen on all IPv6 addresses, or enter the server IP address.
c. Click Save.
Enter authorized access networks. Click on the Authorized Access tab, then click Add to open the Add Authorized Access 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.
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.
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 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. .
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.
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.
Next and for all systems, go to Shares and click Wizard on the iSCSI widget to open the wizard.
Select Fibre Channel as the target mode, then select Create New in Target. Click Next to show the Extents screen.
Configure the extent.
a. Enter a name for the target in Name.
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.
Click Save.
Start the iSCSI service when prompted. If you did not stop the iSCSI service, restart it by clicking the 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.
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 = secretThe user for
discovery.sendtargets.auth.usernameis set in the Authorized Access used by the iSCSI share Portal. Likewise, the password to use fordiscovery.sendtargets.auth.passwordis 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. Thewcommand tellsfdiskto save any changes before quitting.
After creating the partition on the iSCSI disk, a partition slice displays on the device name.
For example, 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.
This section provides instructions on setting up Windows iSCSI Initiator Client to work with TrueNAS iSCSI shares.
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.Click here for more information
Increasing iSCSI Available Storage
TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage in an iSCSI share.
To expand a Zvol LUN, go to Datasets and click the Zvol LUN name. The Zvol Details widget displays. Click the Edit button.
Enter a new size in Size for this zvol, then click Save.
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.
Go to Shares and click Configure in the Block (iSCSI) Shares Targets screen, then select the Extents tab.
Click the more_vert next to the file-based LUN and select Edit.
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.
Block (iSCSI) Share Target Screens
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.
After adding a share, the widget lists them in a table.
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 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 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.
- Config Service opens the iSCSI Global Configuration screen.
The dropdown list for each target shows two options:
- Edit opens the Edit iSCSI Target screen.
- Delete opens the Delete dialog.
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).
Delete opens a confirmation dialog with two options:
- Delete 1 associated extent - Shows the number of associated extend for the selected target.
- Force Delete - Deletes the target even if the share is still in use.
Cancel closes the dialog without deleting. Delete deletes the target but does not delete the iSCSI volumes associated with the extents.
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.
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.
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.
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 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.
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.
Global Target Configuration opens the iSCSI service configuration screen.
Wizard opens the iSCSI wizard configuration screens.
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 Authorized Networks shows networks added on the Add or Edit iSCSI Target screens.
- 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.
- Extents shows extents associated with the target.
Add opens the Add iSCSI Target screen.
Edit opens the Edit iSCSI Target screen for the target selected in the table.
Delete opens the Delete Target dialog.
The screen shows three widgets on the right side of the screen for the selected target:
Extents- Shows a list of LUNs, and includes two options:
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.
The Remove Extent Association 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.
The Associate dialog shows the target name.
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.
The Add Target and Edit Target screens show the same configuration settings.
The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.
Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.
The Delete iSCSI Extent name deletes the specified extend. The name of the extent shows in the dialog title.
Force allows deleting the extend even if the share is active.
Delete deletes the extent and closes the dialog. Cancel closes the dialog without deleting the extent.
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 opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.
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.
Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
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.
Add opens the Add Authorized Access screen.
The dropdown list for each group ID shows two options:
- Edit opens the Edit iSCSI Assoicated Access screen.
- Delete opens the Delete dialog.
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.
Fibre Channel Screens
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.
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 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.
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.
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.
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 iSCSI wizard Protocol Options screen for fibre channel shows three setting options to configure fibre channel ports and initiators.
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.
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.
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.
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.
Extents shows a list of LUNs, and includes two options: Associate button and a Remove Extent Association icon.
iSCSI Connections shows a list of the connections configured on the system.
Delete opens a confirmation dialog with two options:
- Delete 1 associated extent - Shows the number of associated extend for the selected target.
- Force Delete - Deletes the target even if the share is still in use.
Cancel closes the dialog without deleting. Delete deletes the target but does not delete the iSCSI volumes associated with the extents.
The Remove Extent Association 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.
The Associate dialog shows the target name.
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.
The Add Target and Edit Target screens show the same configuration settings.
The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.
Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.
The Delete iSCSI Extent name deletes the specified extend. The name of the extent shows in the dialog title.
Force allows deleting the extend even if the share is active.
Delete deletes the extent and closes the dialog. Cancel closes the dialog without deleting the extent.
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 opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.
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 configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
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.
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.
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.
NVMe-oF Subsystems
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 NVMe-oF
You can access the NVMe-of service screen from the:
- 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.
TrueNAS populates the Base NQN field with the NVMe identifier. Accept this value or click in the field to paste a new, properly formatted Base NQN identifier. TrueNAS uses the NQN 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.
Click Save to save changes and close the screen.
Go to the NVMe-oF Global Configuration screen.
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 license. If the system does not have the required hardware, the screen shows Not enabled, because this system does not support RDMA.
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.
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
Go to the Add Subsystem wizard, then:
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 some special characters such as the dash (-) and underscore (_).
Leave the NQN set to Generate from global setting. To change it, click on it or the edit icon, and then enter or 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.
To add a new file, click on the New File tab, browse to select the parent dataset, then enter a file name, enter the desired file size.
Click Save, then click the breadcrumb at the top of the screen to return to the Add Subsystem wizard.
Click Next to show the Access screen.
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.
a. Enter or copy/paste the NQN number obtained from the host system.
b. (Optional) Select Require Host Authentication to show and add authentication setting options.
c. (Optional) Enter the DH-CHAP key obtained from the host system to use when connecting to TrueNAS. Enter or 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 this key and paste it 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 this key and paste it into the host system to use when authenticating TrueNAS when it connects.
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.
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.
Enter the size for the zvol. For example, 10 GiB.
Accept the default settings for the remaining settings, or click the 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 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.
After configuring an 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 dropdown menu on the row for the subsystem listed in the NVMe-oF Subsystems card.
Select View to open the NVMe-oF screen for that subsystem and showing the Details cards for it.
or
Click on the NVMe-oF Subsystems card 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 cards for that 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 card. 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 card, then enter or copy/paste a new correctly-formatted NQN in the field.
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 card. TrueNAS copies the identification number to the clipboard.
Before deleting a namespace subsystem, delete the port and any associated host. TrueNAS shows an error if the subsystem has an active port and a 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.
To delete a zvol namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete icon to the right of the zvol in the Namespace card.
The Delete Namespace dialog opens. Deleting the namespace from the zvol does not delete the zvol; it only removes it from the subsystem.
Click Delete to delete the namespace.
To delete a file namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete icon to the right of the file in the Namespace card.
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.
You can add new ports or edit existing ports from the Ports card on the NVMe-oF screen. First, select the subsystem row in the table, then click the Add dropdown on the right of the Ports card 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.
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports card. 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 card, the added port shows as an option on the dropdown list.
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports card. Click Manage Ports to open the Ports window.
Select the 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.
You can change the port number assigned to the subsystem using the 
Remove this port from the subsystem icon on the Ports card.
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 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 card for a selected subsystem on the NVMe-oF screen.
To delete the port, click on the 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.
The Associated Hosts card 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 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 card with options to edit, delete, or remove them from the 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.
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 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.
To delete a host from the subsystem, click Add, then select Manage Hosts. The Hosts window opens. click the 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.
TrueNAS offers two experimental options that allow users to try out methods to implement changes to the NVMe-oF service: SPDK (Userspace) and Linux Kernel.
To activate either of these options:
Turn off the NVMe-oF service.
Select the option that suits your use case.
Click Save
Start the service.
NVMe-oF Share Screens
The NVMe-oF screens provide access to screens, cards, 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.
The NVMe-oF Subsystems card shows on the Shares screen. The header shows the status of the NVMe service as Stopped or Running, the Add button, and the 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 card 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 dropdown menu for each subsystem shows two options:
- View - Opens the NVMe-oF screen showing the cards for the selected subsystem.
- Delete - Opens Delete Subsystem dialog.
The Delete Subsystem dialog confirms you want to delete the subsystem before it is deleted from the TrueNAS system.
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.
The NVMe-oF screen displays a table listing subsystems (targets) added to Truenas, and a set of Details cards 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 card with information about subsystems and a basic comparison to iSCSI.
Global Configuration opens the NVMe-oF Global Configuration screen.
Add Subsystem opens the Add Subsystem screen.
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 cards for that subsystem. Select the row of any listed subsystem to view the detail cards for that subsystem.
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 alert icon shows beside the namespace name in the table and on the Ports and Namespaces cards until these are added.
Each subsystem shows a group of four Details for subsystemName cards on the right side of the screen, subsystemName is the name given to the subsystem (i.e., test). Subsystem cards are:
The Details card shows the name and NQN ID associated with the TrueNAS subsystem. The NQN shows an edit icon that changes the NQN to a text-entry field.
The Namespaces card lists namespaces (zvol or file) added to the subsystem and the path to it. Namespaces are similar to iSCSI extents.
Add opens the Add Namespace screen.
Delete opens a confirmation dialog for the namespace.
The Ports card shows the port type and ID associated with the subsystem.
The Add button to the right of Ports shows a dropdown list of options:
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.
The Associated Hosts card 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 card 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.
Add shows a dropdown list of options:
- Create New opens the Add Host screen.
- Manage Hosts opens the Hosts window
- 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.
Sets system-wide NVMe-oF settings. Config Service on the NVMe-oF Subsystem card dropdown menu, Global Configuration on the NVMe-oF screen, and the edit icon on the NVMe-oF row on the System > Services screen open the NVMe-oF Global Configuration screen.
Enterprise systems equipped with the right hardware and license show the SPDK (userspace) and Linux Kernel options that change the NVMe backend. These experimental implementation functions are geared towards experimentation with client compatibility. Try each option based on your use case, and if you have issues with certain clients, such as hypervisors that might require specific capabilities that come with the Linux Kernel or SPDK option. Stopping the service enables these options. After selecting, restart the service.
The Add Subsystem wizard opens after clicking Add on the NVMe-oF Subsystem card or Add Subsystem on the NVMe-oF screen. The wizard has two parts, What to Share and Access. What to Share shows by default.
The What to Share screen allows configuring the subsystem and adding a namespace.
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:
Save saves changes, creates the subsystem, closes the wizard screen, and returns to the previous screen.
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 card on the NVMe-oF screen opens the Add Namespaces screen.
These screens have three tabs:
- Zvol (selected by default)
- Existing File
- New File
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.
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.
The New File tab on the Add Namespace screen allows creating a new file for a namespace.
Save saves the settings, closes the screen, and returns to the previous screen.
The Delete Namespace opens after clicking the delete icon to the right of a zvol on the Namespaces card.
The delete icon to the right of a file opens a Delete Namespace dialog showing the option to delete the file.
Use to create a new zvol for the namespace to use for storage. Create Zvol on the Add Namespace screen with the Zvol tab selected opens this screen.
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 settings.
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.
The Passphrase settings set encryption to a passphrase of your choice to encrypt the data in the zvol.
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.
Require Host Authentication shows the additional setting options.
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 icon and the delete icons.
Add New opens the Add Host screen.
Edit opens the Edit Host screen.
Delete opens a delete confirmation dialog for the port.
The Delete Host confirmation dialog deletes the host(s) from the listed subsystems(s) listed in the dialog and from TrueNAS.
Cancel closes the dialog without removing the host from the subsystem.
Delete Anyway deletes the host from the subsystem(s) specified in the dialog.
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.
The Edit Port screen shows current port settings for the selected subsystem. The edit icon on the port row listed on the Ports dialog opens the Edit Port screen.
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 icon and the delete icon.
Add New opens the Add Port screen.
Edit opens the Edit Port screen.
Delete opens a delete confirmation dialog for the port.
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 card 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.
WebShare
WebShare provides web-based file access to authorized users through a browser interface. Unlike SMB or NFS shares that require mounting on client systems, WebShare allows users to browse, upload, download, and search files directly from a web browser.
WebShare requires TrueNAS Connect to be configured and active.
Configuring WebShare
The WebShare widget displays Open WebShare and Add buttons, and a icon for accessing service options. Each configured WebShare displays as a row showing the share name, path, and action icons to open the share in a new browser tab, edit the share, or delete the share.
Before configuring WebShare, ensure the following:
- TrueNAS Connect is configured and active on your system
- A dataset exists for the files you want to share
- At least one local user account exists with WebShare access enabled
Configure the WebShare service before creating shares.
Go to Shares and locate the WebShare widget.
Click the icon and select Config Service.
(Optional) Select Enable TrueSearch to enable file indexing and search functionality. When enabled, TrueSearch indexes all active WebShares for fast file searching.
Configure the Passkey setting based on your security requirements:
- Disabled turns off passkey authentication.
- Enabled allows passkeys as an optional authentication method.
- Required requires users to authenticate using passkeys.
Click Save.
Toggle on the WebShare service to start it.
When accessing files through a web file share (WebShare) and an SMB share, you must configure the SMB share with the Multi-Protocol share Purpose preset. This configuration coordinates file access between the different protocols. It reduces, but does not eliminate, the risk of file conflicts. This configuration results in the SMB share experiencing a performance impact (slower response).
Note, even with this preset configuration, avoid simultaneous access to the same files from both protocols, since that can cause data corruption.
After configuring the service, create a WebShare to provide access to a specific directory.
Go to Shares and locate the WebShare widget.
Click Add.
Select the Path to the directory you want to share. The path must be under /mnt/poolname/. All subdirectories within the selected path are accessible to authorized users based on their file system permissions.
Enter a Name for the WebShare. The name must contain only letters, numbers, hyphens, and underscores.
(Optional) Select Home Share to use this share as the base path for user home directories. Only one WebShare can have this option enabled.
Click Save.
To modify an existing WebShare, click the icon on the share row. The Edit WebShare screen allows you to change the path, name, and home share setting.
To delete a WebShare, click the icon on the share row. A confirmation dialog displays before TrueNAS removes the WebShare.
Users must have WebShare access enabled to connect.
Go to Credentials > Users.
Click the user you want to grant access to, then click Edit.
Locate the Allow Access section and enable WebShare Access.
Click Save.
After configuring the service, creating a share, and enabling user access:
Click Open WebShare on the WebShare widget in the Shares dashboard. Alternatively, access WebShare directly using your TrueNAS Connect URL on port 755.
Log in with the credentials for a TrueNAS user account that has WebShare Access enabled.
Navigate to the share to browse files.
The WebShare interface provides a file browser with toolbar buttons for common actions.
The file list displays columns for file name, owner, size, and modified date. Click a folder to open it. Click the icon in the column header to navigate to the parent directory. Click the Name column header to sort files alphabetically.
Click the icon to open the upload panel. Drag and drop files into the upload area or click Browse Files to select files from your computer. Toggle between Files and URL to upload files from a web URL instead.
Click the icon to create a new folder in the current directory.
The toolbar provides additional options:
- Filter - Filter the file list
- Refresh - Refresh the current directory
- Timeline - View snapshots of the current directory
- Share - Create a shareable link
- Hidden files - Toggle visibility of hidden files
- File details - Open the file details panel
Click the icon on a file row to access file-specific actions such as download, rename, copy, move, and delete.
When TrueSearch is enabled in the WebShare service configuration, users can search for files within WebShare.
TrueSearch requires an Enterprise license or TrueNAS Connect configuration. Encrypted datasets are excluded from indexing.
After logging into WebShare:
Locate the search box in the top right corner of the WebShare interface.
Enter search terms. TrueSearch supports searching by:
- File name
- File content
- File type
Review search results as they appear.
TrueSearch indexes all enabled WebShares globally. You cannot enable or disable indexing for individual shares.
WebShare Shares Screens
If you have not added WebShare shares to the system, the WebShare widget shows text stating general information about WebShares until a share is added.
Add at the top right of the widget opens the Add WebShare screen where you configure a Webshare share.
After adding an WebShare share, it is listed in the table on the widget.
The WebShare header shows the status of the WebShare 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 > WebShare screen.
Open WebShare opens a browser window with access to the WebShare. Add opens the Add Webshare screen.
The dropdown list shows two options available to WebShare shares in general:
- Turn Off/ON Service toggles to Turn Off Service when the WebShare service is enabled, and to Turn On Service when the WebShare service is disabled.
- Config Service opens the WebShare service configuration screen.
The WebShare table in the WebShare widget and on the WebShares screen lists all WebShare shares added to the system. The table header shows the status of the WebShare service as stopped or running. The table columns show the share name and the path to the dataset for the share.
A message shows at the top of the table and on the WebShares widget on the Shares screen if a user is not configured to allow WebShare access.
Each Webshare share row shows the share name, the path to the shared dataset, and three icons:
- Open - Launches a web browser showing access to the WebShare.
- Edit - Opens the Edit Webshare.
- Delete - Opens a delete confirmation dialog.
The delete icon opens a Delete confirmation dialog. The dialog shows the name of the share, and a warning message about deleting the WebShare.
Select Confirm to activate the Delete button.
The Shares > WebShare screen shows the same WebShares table found on the WebShare widget.
Shares in the breadcrumb at the top of the screen returns you to the main Shares dashboard.
Columns shows a set of options to customize the list view. Options include Unselect All, Name, Path, and Reset to Defaults.
Add opens the Add WebShare configuration screen.
The two WebShare configuration screens, Add WebShare and Edit WebShare, have the same setting options.
The Create Dataset option becomes active after selecting a parent dataset in the Path file browser field. It opens the Create Dataset dialog.
Save creates the share (or saves an existing one) and adds it to the WebShare widget and the WebShare table on the WebShare screen.
| Setting | Description |
|---|---|
| Path | Populates with the full path to the dataset for the share based on the datasets selected using the file browser directly under the Path field. |
| Create Dataset | Opens the Create Dataset dialog, which allows you to create a dataset for a share while configuring the share. Create adds the dataset. The Create Dataset option remains inactive until a dataset is clicked on in the file browser. |
| Name | Sets the name for the share of alphanumeric characters and can include a hyphen or underscore. |
| Home Share | Used as the base path for a user home directory when set. Only one WebShare can have this enabled. |
Migrating AFP 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.
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 24.04 to migrate previously-saved AFP configurations into SMB configurations.
To prevent data corruption that could result from the sidegrade operation, in TrueNAS, go to Windows (SMB) Shares, select the 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 24.04, 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.
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
Shares Screens
Click Shares on the main navigation panel to open the Sharing screen, which displays options to access SMB, NFS, iSCSI, and NVMe-oF shares.
Data Protection
The Data Protection screen task widgets allow users to set up multiple redundant tasks to protect and back up data in case of drive failure. The screen shows No Data Protection Tasks, a message, and Create Pool until you add the first pool to your system. After adding a pool, the screen shows a description of each task in the widgets until you configure a task. Configured tasks are listed in the corresponding task widgets with details about, and the status of the task.
Refer to the articles listed below for information on how to set up and manage various data protection tasks.
TrueCloud Backup Tasks
TrueCloud backup tasks allow TrueNAS to back up data to Storj iX cloud storage.
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.
You must configure all system storage (pool and datasets or zvols) and have them ready to receive or send data.
To create a TrueCloud Backup task:
Create the TrueNAS Storj cloud credential.
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.
Create the TrueCloud Backup task for one bucket.
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.
Enter a descriptive name to identify the credential in the Name field.
You can create your Storj iX cloud service account using two methods:
- Go to the TrueNAS Storj web page and click Sign Up & Log in - iX-Storj.
- Go to Credentials > Backup Credentials and click Add. Select Storj iX as the Provider on the Cloud Credentials screen, then click Sign up for account.
The Storj Create your Storj account web page opens.
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.
After setting up your Storj iX account, set up Storj S3 access and create your Storj bucket.
The endpoint set in the Storj credential applies to all Cloud Sync Tasks that use that credential.
After completing this configuration form, you can set up the TrueCloud Backup task.
After creating your Storj iX account, add S3 access credentials.
Click Access Keys to open the Access Keys dashboard, then click New Access Key.
The New Access window opens.
Enter the name you want to use for this credential. Select S3 Credentials for access type, then click Next.
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.
To enable TrueNAS to create new Storj buckets, set the access configuration to Full Access.(Optional) If configuring advanced access options:
a. Select the permissions to allow. Choose one or more of Read, Write, List, Delete, or choose All Permissions. Click Next.
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.
d. Review access details and then click Create Access.
Use Copy All or Download All to obtain the access key, secret key, and endpoint. Keep these in a safe place where you can back up the file.
Click Close.
Enter these keys in the Authentication fields in TrueNAS on the Cloud Credentials screen to complete setting up the cloud credential.
Enter the authentication information provided by Storj in the Access Key ID and Secret Access Key fields.
Click Verify Credentials and wait for the system to verify the credentials.
Click Save.
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.
If using the Add TrueCloud Backup Task screen:
Select the stored Storj cloud credential from the Credentials dropdown. Do this as part of setting up a task.
Select Add New from the Bucket dropdown.
Enter a name for the new bucket. Only lowercase letters, numbers, and hyphens are allowed
Continue to configure the TrueCloud backup task, then click Save. TrueNAS creates the task and remote bucket on Storj.
If using the Cloud Sync Task Wizard:
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.
Select Add New to open the Add Bucket screen.
Enter a name for the new bucket.
Click Save. TrueNAS creates the remote bucket on Storj and then returns to the Cloud Sync Task Wizard.
To add the TrueCloud backup task, go to Data Protection > TrueCloud Backup Tasks:
Click Add to open the Add TrueCloud Backup Task 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.
Optionally, enter or browse to select a Cache Path to store cache files. This can improve backup performance for users with massive datasets and large numbers of files.
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.
(Optional) Enter a Rate Limit value in KiB/s (kibibytes per second) to limit the backup transfer rate. This is a static rate limit that applies throughout the entire backup process. Leave empty for no rate limit.
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 on the task and select Run Job to start the task apart from the scheduled time.
The task status changes to SUCCESS when complete.
Advanced Options and Advanced Remote Options contain additional settings for advanced users.
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.
To edit an existing TrueCloud backup task, click the vertical ellipses 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 on the task and select Run Job to start the task immediately.
To delete a task, click the vertical ellipses on the task and select delete Delete for the task to delete.
See TrueCloud Backup Tasks Screens for more information on TrueCloud Backup Task screens.
To restore data from a TrueCloud backup, locate an existing snapshot on the Snapshots widget.
Click the vertical ellipses on the task and select history Restore to open the Restore from Snapshot screen.
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.
To delete an existing snapshot, locate it on the Snapshots widget. Click the vertical ellipses on the snapshot and select delete Delete to delete the snapshot. A Delete Snapshot dialog opens.
Click Confirm and then Delete to start the job.
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.
The TrueCloud Backup Tasks widget shows a list of tasks configured on the system.
The widget shows No records have been added yet until a TrueCloud task is added.
The widget header opens the TrueCloud Backup Tasks screen that lists all TrueCloud backup tasks configured on the system.
Add on the widget and the TrueCloud Backup Tasks screen opens the Add TrueCloud Backup Task Screen.
Each task on the widget includes a vertical ellipses icon that opens a dropdown menu with four options for various functions:
Edit opens the Edit TrueCloud Backup Task screen populated with with the settings for that task.
play_arrow Run 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.
Delete 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.
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.
Task options perform the same functions as the icons on the widget:
Edit opens the Edit TrueCloud Backup Task screen populated with with the settings for that task.
play_arrow Run Now starts and runs the backup task outside of the scheduled time.
Delete 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.
The Snapshots widget lists existing TrueCloud snapshots for the selected backup task. It contains options to restore from or delete an existing snapshot.
history Restore opens the Restore from Snapshot screen.
Delete opens a confirmation dialog before the system deletes the snapshot.
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. |
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.
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.
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.
| Settings | Description |
|---|---|
| Source Path | 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 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 to the left of the /mnt folder again to collapse the directory tree. |
| Cache Path | Optional. Directory path where cache files are stored. This speeds up the backup process for users with massive datasets and large numbers of files. If not set, performance can degrade. |
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 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 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. |
| Rate Limit | Optional. Positive integer that sets the rate limit for the backup process in KiB/s (kibibytes per second). This is a static rate limit that applies throughout the entire backup process. Unlike Cloud Sync bandwidth limits, this setting does not support time-based scheduling. |
| 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 establish a schedule for when to run the backup task.
| Settings | Description |
|---|---|
| Schedule | Shows a list of schedule preset options. See Schedule Presets below for more info. |
| 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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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 are intended for advanced users.
| Settings | Description |
|---|---|
| Use Snapshot | 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. |
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: |
Cloud Sync Tasks
This section has tutorials to configure and manage data backups from TrueNAS to various third-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:
- Amazon S3
- Backblaze B2
- Box
- Dropbox
- File Transfer Protocol (FTP)
- Google Cloud Storage
- Google Drive
- Google Photos
- Hypertext Transfer Protocol (HTTP)
- Hubic (closed to new accounts)
- Microsoft Azure Blob Storage
- Microsoft OneDrive
- OpenStack Swift
- pCloud
- SSH File Transfer Protocol (SFTP)
- Storj iX*
- WebDAV
- Yandex
*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.
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.
Backing Up Google Drive to TrueNAS
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.
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.
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.
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 to the left of / 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 to the left of / 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.
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.
Managing Cloud Sync Tasks
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.
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.
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.
The rclone project has identified known issues with Filename Encryption in certain configurations, such as when long file names are used. See SSH_FX_BAD_MESSAGE when syncing files with long filename to encrypted sftp storage. In some cases, this can prevent backup jobs from completing or being restored.
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 Filename Encryption is 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 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.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
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.
One common error occurs when the Dropbox copyright detector flags a file as copyrighted.
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 does not display in the TrueNAS UI. These folders are essentially empty directories and Backblaze API restricts them so they do not display.
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.
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.
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.
To create a new cloud sync task that uses the same options but reverses the data transfer, click the vertical ellipses on an existing cloud sync task on the Data Protection page and select history Restore. 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 might 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.
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.
See the Google API update notice for more details.
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:
- Plan your deployment and select a local dataset.
- Generate Google API credentials on the Google Cloud API dashboard.
- Install rclone and generate a token on your remote client OS.
- Add Google Photos cloud credentials on TrueNAS.
- Configure the cloud sync task on TrueNAS.
Review your storage and data protection requirements before setting up a Google Photos cloud sync task. See the rclone Google Photos backend documentation for details on standard options and API limitations that can help you plan your deployment.
Decide how you want to manage media files in Google Photos and your local dataset. Choose the cloud sync direction and transfer mode, target folder, and local dataset (new or existing) that best fit your needs.
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.
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 |
|---|---|---|---|
| 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. | |
| 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. | |
| 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. |
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.
Enter a value in 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).
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.
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.
After you select your project, click Enabled APIs & Services on the left menu, then click + ENABLE APIS AND SERVICES.
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.
Click OAuth consent screen on the left menu, select EXTERNAL, then click CREATE.
Enter a value in App name and User support email.
Enter an email address in Developer contact information, then click SAVE AND CONTINUE.
Continue to the Test users section and click + ADD USERS, enter the email addresses of users who run cloud sync tasks, then click ADD.
On the OAuth consent screen, click PUBLISH APP under Testing and push the app to production.
Click Credentials on the left menu, then click + CREATE CREDENTIALS and select OAuth client ID.
Select Desktop app in the Application type dropdown, then enter a name for the client ID and click CREATE.
Copy and save your client ID and secret, or download the JSON file.
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.
Do not edit the advanced config.
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.
In the TrueNAS Web UI, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
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.
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 on the task and select Run Job to start the cloud sync task immediately.
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:
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.
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:
- Amazon S3
- Backblaze B2
- Box
- Dropbox
- File Transfer Protocol (FTP)
- Google Cloud Storage
- Google Drive
- Google Photos
- Hypertext Transfer Protocol (HTTP)
- Hubic (closed to new accounts)
- Microsoft Azure Blob Storage
- Microsoft OneDrive
- OpenStack Swift
- pCloud
- SSH File Transfer Protocol (SFTP)
- Storj iX*
- WebDAV
- Yandex
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
The Cloud Sync Task widget lists tasks configured on the system. The widget shows a description of cloud sync tasks before adding a task.
The widget header opens the Cloud Sync Task screen that lists all tasks configured on the system.
Add on the widget and the Cloud Sync Task screen opens the Cloudsync Task Wizard.
The vertical ellipses opens a dropdown menu with five options for various functions for each task:
Edit opens the Edit Cloud Sync Task screen populated with with the settings for that task.
Run Now starts the cloud sync, running it outside of the scheduled time.
Dry Run 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.
Restore creates a new cloud sync task from an existing task. The new task has the same settings but reverses the data transfer.
Delete 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.
The Cloud Sync Task screen lists all tasks configured on the system.
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.
Edit opens the Edit Cloud Sync Task screen.
Delete opens a dialog where you confirm the action before the system deletes the task.
The Cloud Sync Task wizard screens simplify the task creation process. The wizard has two screens, Provider and What and When.
The Provider wizard screen allows you to set the cloud sync provider with the Credentials dropdown. Selecting a provider from the dropdown list shows the additional credential settings required 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.
The What and When screen sets the direction (push or pull), transfer mode (move, copy, or sync), sets 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 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.
Manage Credentials opens the Backup Credentials screen.
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.
| Settings | Description |
|---|---|
| Description | 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: |
| Directory/Files | Enter or browse to select the source or receiving dataset or folder. Click the 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 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. |
The Remote settings specify the cloud sync provider and destination storage locations. The option selected in Credential changes settings 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 to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task. |
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.
| Settings | Description |
|---|---|
| Bucket Name | Enter a name for the new bucket |
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 establish a schedule for when the cloud sync task occurs.
| Settings | Description |
|---|---|
| Schedule | Shows a list of schedule preset options. See Schedule Presets below for more info. |
| 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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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 are for advanced users. Selecting Push in Direction adds the Use Snapshot option.
| Settings | Description |
|---|---|
| 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).--exclude option. |
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.
| Settings | Description |
|---|---|
| Remote Encryption | 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. |
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
The rclone project has identified known issues with Filename Encryption in certain configurations, such as when long file names are used. See SSH_FX_BAD_MESSAGE when syncing files with long filename to encrypted sftp storage. In some cases, this can prevent backup jobs from completing or being restored.
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!
Periodic Snapshot Tasks
Periodic snapshot tasks automatically create read-only copies of datasets or zvols on a schedule.
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.
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.
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.
| 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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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. |
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.
Examples:
| Naming Scheme | Snapshot Names Look Like |
|---|---|
| replicationsnaps-1wklife-%Y%m%d_%H:%M | replicationsnaps-1wklife-20210120_00:00, replicationsnaps-1wklife-20210120_06:00 |
| autosnap_%Y.%m.%d-%H.%M.%S-%z | autosnap_2021.01.20-00.00.00-EST, autosnap_2021.01.20-06.00.00-EST |
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.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
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.
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.
The Periodic Snapshot Task widget displays a list of tasks configured on the system. The widget shows a description of periodic snapshot tasks when a task is not configured.
The Periodic Snapshot Task widget header opens the Periodic Snapshot Task screen.
Add opens the Add Periodic Snapshot Task screen.
VMware Snapshot Integration opens the VMware Snapshots screen.
Snapshots opens the Snapshots screen.
The vertical ellipses at the right of the task on the Periodic Task Widget opens a dropdown menu with two task options: Edit and Delete.
The Delete opens a delete dialog. Confirm activates the Delete. Delete deletes the saved periodic snapshot task.
Edit opens the Edit Periodic Snapshot Task screen.
State shows the status of the next cloud sync task. It opens a Logs window for that task.
Download Logs saves a copy of the current task logs.
Periodic snapshot tasks show on both the Periodic Snapshot Task widget on the Data Protection screen and the Periodic Snapshot Tasks screen.
Add opens the Add Periodic Snapshot Task 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 shows the details for the selected task.
Edit opens the Edit Periodic Snapshot Task screen.
Delete opens the delete dialog that removes the task from the system.
The Add Periodic Snapshot Task and Edit Periodic Snapshot Task show the same settings.
Dataset settings show on both the add and edit configuration screens.
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 that 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 | Shows a list of schedule preset options. See Schedule Presets below for more info. |
| 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. |
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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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. |
Rsync Tasks
Rsync tasks allow TrueNAS to push or pull data to or from a remote system using the rsync protocol.
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:
- Set up an SSH connection to the remote server.
- Set up an rsync module for the remote server.
An rsync task has two basic methods:
- Module
- SSH
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.
Enter the authentication settings.
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.
Click Save.
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.
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 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.
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.
Leave this set to Module if syncing with a non-TrueNAS remote system. See Addin an Rsync Task Using Module Mode for more information.
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 bytes.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
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*/2runs 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.
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 months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 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 for the task, and select the Run Now.
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.
Enter the authentication settings.
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.
Click Save.
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.
Enter the authentication settings.
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.
Click Save.
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.
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.
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.
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.
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*/2runs 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.
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 months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 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 Now play_arrow icon for the rsync task on the Rsync Task widget.
Rsync Tasks Screens
The Rsync Task widget on the Data Protection screen shows rsync tasks configured on the TrueNAS system. It 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.
The Rsync Tasks widget shows a description about rsync tasks until the first task is configured, then it shows a list of tasks configured on the system, with th details about the task, and the task status.
The widget header opens the Rsync Task screen.
Add opens the Add Rsync Task screen.
The vertical ellipses icon to the right of each task opens a dropdown menu with three options for various functions:
Edit opens the Edit Rsync Task screen populated with with the settings for that task.
The play_arrow Run job starts the rsync operation, running it outside of the scheduled time.
Delete opens a confirmation dialog.
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.
The Rsync Task screen lists all tasks configured on the system.
The screen shows a table listing each task, with details about the task, and the task status. Table column headings sort the list in ascending or descending order.
The vertical ellipses icon to the right of each task opens a dropdown menu with three options for various functions:
Edit opens the Edit Rsync Task screen populated with with the settings for that task.
The play_arrow Run job starts the rsync operation, running it outside of the scheduled time.
Delete opens a confirmation dialog.
Add opens the Add Rsync Task screen.
The Add Rsync Task and Edit Rsync Task screens show the same settings. The sections below group settings by functional area.
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 option (Module or SSH) set in Rsync Mode.
TrueNAS measures filename and path length limits in bytes, not characters. For standard ASCII characters (English letters, numbers, and common symbols), one character equals one byte. Characters from other scripts — such as Chinese, Arabic, or accented characters — and emoji can each occupy 2–4 bytes, which significantly reduces the number of characters that fit within the limit. For example, a 4-byte emoji counts as 4 bytes against a 255-byte filename limit, allowing approximately 63 emoji rather than 255 characters. Keep filenames short and descriptive to avoid unexpected truncation.
Schedule defines when the remote sync task occurs. The More Options specify other settings related to when and how the rsync occurs.
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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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. |
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.
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.
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.
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.
Setting Up a Local Replication Task
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.
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.
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.
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.
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.
For information on replicating encrypted pools or datasets, see Setting Up an Encrypted Replication Task.
Setting Up a Remote Replication Task
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.
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.
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.
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 allowcommand 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.d. Enter the settings for the other location (source or destination), which is automatically set to On This System. Browse to select the dataset.
e. (Optional) Select Encryption to add a second layer of encryption over the already encrypted dataset.
(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.
For information on replicating encrypted pools or datasets, see Setting Up an Encrypted Replication Task.
When using a TrueNAS system on a different release, the remote or destination system user is always root.
To configure a new SSH connection while in the Replication Task Wizard:
Select Add New on the SSH Connection dropdown list to open the New SSH Connection screen.
Enter a name for the connection.
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.
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.
Replication Task Screens
The Replication Task widget on the Data Protection screen lists replication tasks configured on the TrueNAS system. The widget shows a definition of replication tasks before adding a task when none exist on the 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 Replication Tasks widget heading opens the Replications Tasks screen.
Add on the Replication Task widget opens the Replication Task Wizard.
The vertical ellipses to the right of each task opens a dropdown menu of options:
Edit icon opens the Edit Replication Task screen.
Run Now Run job opens a dialog.
Restore Restore to opens the Restore Replication Task window.
Delete Delete opens a delete confirmation dialog.
State shows the status of the replication task. Status shows as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
The state oval opens the Logs dialog for that task. Download Logs saves a copy of the current task logs.
The Replications Tasks screen lists the replication tasks configured on the system.
Column headings sorts the list in ascending or descending order.
Columns shows 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.
Click anywhere on a task row to expand it and show details about that task and options to run, restore, edit, or delete that task.
The details view of each replication task shows the Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, and Auto settings.
Run Now opens a Run Now dialog.
Restore opens the Restore Replication Task window.
Edit opens the Edit Replication Task screen.
Delete opens a delete confirmation dialog.
Run Now opens the Run Now dialog.
Continue starts the replication task.
The Restore Replication Task window shows settings to configure a restore task operation. where the system creates the new file and displays the task on both the widget and list screen with the PENDING status.
Name is the name of the new file created by the restore operation.
Destination sets the mount path where TrueNAS creates the new file resulting from the restore operation.
Restore starts the restore operation.
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.
The Delete confirmation dialog shows the task name with both source and destination information.
Confirm activates Delete.
Delete removes the task from the system.
There are two ways to add a replication task: the wizard and the advanced creation screen. These two methods share many settings described in the shared settings in the sections below.
The Edit Replication Task screen shows the same settings. Shared settings are documented in these sections:
Add opens the 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, when 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.
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 on the wizard screen change based on the Source Location and Destination Location options 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.
Also include snapshots with the name options show different snapshot settings based on the naming option selected.
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.
The Encryption option shows additional settings on the Add Replication Task screen and the What and Where wizard screen below the Destination settings.
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.
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.
The Replication Schedule options set when to run the task based on the schedule defined in Schedule or to run it one time.
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.
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.
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.
These settings display for all three Transport options.
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.
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.
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.
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.
The snapshot settings below change options displayed based on selections made.
These schedule setting options are common to both the Replication Task Wizard and Add Replication Task screens.
Advanced Schedule Settings
| Setting | Description |
|---|---|
| Run Automatically | 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. |
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 | months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 |
| 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 Replication Tasks
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, setting up replication tasks as an admin user differs from 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.
Configuring Advanced Replication
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.
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.
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.
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 the SSH service. Go to the System > Services screen, verify the SSH service configuration, then enable it.
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 allowon the remote system 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 generated from a periodic snapshot task 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-%Mfinds and replicates snapshots likecustom-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*/2runs 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.
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 months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1 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.
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.
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.
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.
When enabled, and when migrating from a FreeBSD-based to a Debian-based TrueNAS, verify the ACL Type and Encryption settings on a migrated dataset before configuring a replication task. When a migrated dataset is used as the replication source, this option can silently overwrite the destination dataset properties with incorrect settings. For datasets associated with SMB shares, confirm the ACL Type is set to SMB/NFSv4 and not Inherit — an incorrect setting can cause SMB share users to lose folder access. Also, verify Encryption settings are correct for your environment before running replication.
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.
Select Recursive to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
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.
When a replication task has difficulty completing, select Save Pending Snapshots. This prevents the source TrueNAS from automatically deleting any snapshots that failed to replicate to the destination system.
By default, TrueNAS sets the destination dataset to 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 (set to IGNORE).
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 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.
We recommend defining the Snapshot Retention Policy 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.
Selecting Only Replicate Snapshots Matching Schedule restricts the replication to only those snapshots created at the same time as the replication schedule.
Setting Up an Encrypted Replication Task
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.
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.
Configure the remote replication as described in the Creating a Remote Replication Task.
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.
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.
- Click Save.
This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.
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
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.
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.
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.
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.
VMware Snapshots
VMware snapshot integration allows TrueNAS to coordinate ZFS snapshots with VMware datastores.
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 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.
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.
a. Configure CHAP authentication if needed or leave set to Do not use CHAP.
b. Click Add dynamic target, enter the IP address for the TrueNAS system, and click Save Configuration to return to the Adapters screen.
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.
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.
Click the Add button to configure the VMWare Snapshot Task.
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, ERROR, or BLOCKED. A BLOCKED state indicates the snapshot task is prevented from running due to an Outbound Network restriction configured in Network > Global Configuration.
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.
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.
The cloned zvol appears on the Datasets screen.
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.
c. Go to the Datastores tab. You might need to click Refresh again. A new datastore for the mounted snapshot appears in the list of datastores.
Stop the old virtual machine(s) you want to revert and use the snapshot datastore to register an existing VM from the snapshot.
a. Go to Virtual Machines in ESXi, select the existing VM(s) to revert, and click Power Off.
b. Click Create / Register VM to open the New virtual machine screen.
c. Select Register an existing virtual machine and then click next.
d. Click Select and use the Datastore Browser to select the snapshot datastore.
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.
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.
Add opens the Add VMware Snapshot screen.
| Setting | Description |
|---|---|
| Hostname | 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.
Data Protection Screens
The Data Protection screen widgets allow users to set up multiple redundant tasks that protect and/or back up data in case of drive failure. The screen shows No Data Protection Tasks, a message, and Create Pool until you add the first pool to your system. After adding a pool, the screen shows a description of each task in the widgets until you configure a task. Configured tasks are listed in the corresponding task widgets with details about, and the status of, each task.
Network
The System > Network menu option has several screens for network interface configuration and general system-level network settings. The tutorials in this section cover the various screens and configuration forms within this menu item.
Interface Configuration
TrueNAS supports configuring different types of network interfaces such as a standard interface, network bridge, link aggregation (bond), 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.
Configuring Interfaces
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.
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.
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:
- Using the Console Setup menu
- 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 (bond), 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 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!
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.
To change an existing interface, click on the 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 (for example, a bridge, vlan, or link aggregation), 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 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 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.
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.
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 icon for the interface, and then click Edit to open the Edit Interface screen.
Select the Define Static IP Addresses option.
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!
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 nework changes.
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 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.
Click test the network change
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.
Setting Up a Network Bridge
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. 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.
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.
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.
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 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.
Click Add to open the Add Interface screen. Configure the interface:
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 unless you want to defer interface learning until runtime. Disabling learning prevents premature state transitions and potential issues during system startup.
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.
Setting Up a Link Aggregation
A link aggregation combines multiple network interfaces into a single logical bond interface (e.g., bond0, bond1) to provide additional bandwidth or redundancy. TrueNAS implements link aggregation using Linux kernel bonding.
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 bond 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.
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.
To set up a link aggregation, 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.
Name populates with the default name for a link aggregation interface, bond1.
You cannot change the Name of the interface after clicking Apply.
Leave Define Static IP Addresses selected.
(Optional, but recommended) Enter any notes or reminders about this particular link aggregation interface in Description.
Select the protocol from the Link Aggregation Protocol dropdown. Options are LACP, FAILOVER, or LOADBALANCE. Each option displays additional settings.
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 link aggregation 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.
TrueNAS uses vlan(4) to manage 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.
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.
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.
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.
Add opens the Add Interface screen.
The at the right of each interface shows a dropdown list with two options:
- edit Edit - Opens the Edit Interface screen.
- refresh Reset Configuration - Opens the Reset Configuration dialog.
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.
The Reset Configuration dialog allows you to reset the configuration settings for that interface.
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.
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 configure the network interface name, type, and IP address assignment. These settings are common to the three interface types.
| Setting | Description |
|---|---|
| Type | (Required) Only shows on the Add Interface screen. Sets the type of interface based on the selection on the dropdown list. Options are: |
| Name | (Required) Accepts manual or copy/paste entry of a name for the interface. Names must use the format bondX for a link aggregation, 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. Descritpions 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. reate a static IPv4 or IPv6 configuration. |
| 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 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.
Bridge Members sets the network interfaces to include in the bridge to the option selected on the dropdown list. |
Link aggregation (bond) 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 link aggregation interface is used.
| Setting | Description |
|---|---|
| Link Aggregation Protocol | The protocol determines the outgoing and incoming traffic ports. Shows a dropdown list with three link aggregation protocol options: |
| 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! |
| 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 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.
| Setting | Description |
|---|---|
| Parent Interface | 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). |
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
Test Changes starts the 60-second timer.
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
Network configuration covers global network settings, interface options, and platform-specific configurations.
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.
Use the Network Configuration widget to add general network settings like the default gateway and DNS name servers to allow external communication.
To add new or change existing network interfaces, see Interface Configurations.
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
Select as many services as desired.
- 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.
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.
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.
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.
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.
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.
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.
Go to either Shares or Datasets to create the share and dataset.
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.
See Adding NFS Shares or Windows Shares (SMB) for more information on adding shares.
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.
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)
The instructions in the article only apply to TrueNAS Enterprise (HA) systems.
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.
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 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 Save
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.
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.
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. |
| 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. |
| Setting | Description |
|---|---|
| Primary | 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. |
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.
| Setting | Description |
|---|---|
| Allow All | 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. |
| Setting | Description |
|---|---|
| HTTP Proxy | Specifies an HTTP proxy address when using a proxy. Accepts manual or copy/paste entry of the network proxy information in the format http://my.proxy.server:3128 or http://user:password@my.proxy.server:3128. |
| Host Name Database | 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
Static routes define specific paths for network traffic that bypass the default gateway.
Configuring Static Routes
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.
Static Routes Screens
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.
TrueNAS does not have defined static routes by default.
Add opens the Add Static Route screen where you can enter a static route to reach portions of the network.
| Setting | Description |
|---|---|
| Destination | The destination IP address entered in the format A.B.C.D/E where E is the CIDR or netmask. This is a required field. |
| Gateway | The IP address of the gateway. This is a required field. |
| Description | Text entry field for any notes or an identifier describing the route. |
Save adds the static route in TrueNAS.
IPMI
IPMI provides out-of-band management of TrueNAS hardware independent of the operating system.
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.
Click edit on the channel you wish to edit to open the IPMI configuration screen.
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.
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.
IPMI Screens
The IPMI widget on the Network screen shows the available IPMI channels.
IPMI requires a compatible motherboard with IPMI support. Refer to your hardware documentation to determine compatibility.
Click to open the IPMI manager in a new browser tab where users can log into the IPMI web interface.
Click edit to go to the IPMI configuration screen.
Click Show Events to show the IPMI Events log.
Click edit on the channel you wish to edit to open the configuration screen.
On TrueNAS Enterprise High Availability (HA) systems, the IPMI configuration screen includes the Remote Controller section.
| Setting | Description |
|---|---|
| Remote Controller (HA only) | 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. |
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.
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.
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 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.
Click Add to open the Add Interface screen. Configure the interface:
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 unless you want to defer interface learning until runtime. Disabling learning prevents premature state transitions and potential issues during system startup.
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.
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.
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.
To edit the NIC attached to an existing VM:
Go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget.
Click Add and select the secondary interface from the MAC VLAN dropdown list.
Linux Example
Linux VMs and containers can access TrueNAS storage using FTP, SMB, and NFS.
In the example below, the Linux VM uses FTP to access a home directory for a user on TrueNAS.
Network Screen
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.
Credentials
TrueNAS credential options are organized into screens to manage local users and groups, backup credentials (cloud and SSH), certificates, and directory services.
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, 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 configure individual 2FA secrets and link the system to an authenticator app on a mobile device. When global 2FA is enabled, users with configured 2FA secrets must provide a 2FA code to log in.
Users
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.
To see user accounts, go to Credentials > Users.
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.
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.
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 edit Edit.
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 group Members 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.
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, go to 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 from the options provided.
SMB Access is selected by default, and required for a user to have access to an SMB share.Select WebShare to give this user access to a WebShare.
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.
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.
(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 ValidationUsers 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.
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.
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.
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.
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.
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 edit Edit to open the Edit API Key screen. Click delete Delete to delete 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.
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.
The Clear Two-Factor Authentication button only appears for users who have 2FA configured. Users without 2FA configured do not show this button.A confirmation dialog appears asking if you want to clear two-factor authentication settings for this user.
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.
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.
Users Screens
The Credentials > Users screen shows a table with all users created on the system. A set of widgets 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.
Add opens the Add User screen.
Edit opens the Edit user screen for the selected or default user row.
The Users screen search is set to the basic, or simple search option by default. It accepts any word entered, such as a username, user type, or role.
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.
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 an 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. |
| Indicates the user has WebShare access. | |
| Indicates the user has an API key. | |
| Indicates the user has SSH access. |
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 widgets.
The User screen shows up to three widgets 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.
- Access - Shows for all user types.
Edit opens the Edit User screen.
The Profile widget shows the full name, group membership, type of user (Local, Built-in, or Directory Service), home directory path, and the user ID.
The Password widget shows for users who require credentials to access the UI, an SSH session, or have external communication capabilities (Built-in users). The widget 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 widget for the truenas_admin and admin users not currently logged in shows the Generate One-Time Password button.
Generate One-Time Password opens the One-Time Password window showing a system-generated password.
Copy to Clipboard copies the key to the clipboard so you can paste it into a text file and save it for use later when TrueNAS prompts you to enter it.
The Access widget 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.
Information details on the Access widget:
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.
The password shows an active 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 widget.
The access area shows:
- Last action time and date by the user, and the See Logs link, which opens the Audit log screen for the selected user.
- Services (such as SMB Access) and indicates whether it is active or inactive when not granted.
- Pre-defined privilege or 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. The Add API Keys link shows when no key exists, and opens the Add API Key screen. The 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.
- Allowed sudo commands setting
- Allowed Sudo Commands (No Password) setting
The following table legend shows the icons found on the Access widget:
| Icon | Description |
|---|---|
| Indicates user has a password. | |
| Indicates the user has TrueNAS Access. |
| Indicates the user has SMB access. |
| Indicates the user has WebShare access. | |
| Indicates the user has an API key. | |
| Indicates the user has SSH access. | |
| Indicates the user has shell access. |
See Logs opens the Audit screen showing log details for activity associated with that user.
Add API Key link that opens the Add API Key screen. When the user has an API key, View API Keys shows and opens the user API Keys screen.
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.
Only clear 2FA for a user when it is necessary, such as when the user has lost access to their authenticator device. This action temporarily reduces account security until 2FA is reconfigured.
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.
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.
| Setting | Description |
|---|---|
| Username | (Required) Text entry field that accepts manual or copy/paste entry of a 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 parenthesis ( ), exclamation mark (!), at symbol (@), tilde (~), question mark (?), greater or less than symbols (<)(>), or equal (=). |
| Allow Access | Specifies the access granted to the user account. Each option shows different settings. Access options are: |
| Select Role | Shows after selecting TrueNAS Access. Each role adds the appropriate group to the Groups option under Additional Details. |
Authentication settings show after selecting Shell Access or SSH Access options under Allow Access. Password shows for all access options.
| Setting | Description |
|---|---|
| Password | (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 widget. 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! |
The edit icon or on 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.
| Setting | Description |
|---|---|
| Full Name | Text entry field that accepts manual entry of the full name (first and last) for the user. |
| Enter the email address of the new user. This email address receives notifications, alerts, and messages based on configured settings. | |
| Groups | Shows the Create New Primary Group pre-selected by default, and Auxiliary Groups settings after clicking the edit icon. Create New Primary Group creates a new primary group with the same name entered in Username. Disabling Create New Primary Group shows a dropdown list with group options. Auxiliary Group shows a dropdown list after clicking in the field. This sets the membership auxiliary group. 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. Disabling Create Home Directory changes the mount path and browser fields to Home Directory. The mount path field allows manual entry of the path to the home directory for this user, or populates with the path selected with the file browser directly below. 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. Disabling Default Permissions shows the Home Directory Permissions Read/Write/Execute and User/Group/Other checkboxes to customize the home directory permissions. |
| Shell | Select the shell for local and SSH logins from the dropdown list. Options are bash dash, rbash, sh, tmux, TrueNAS CLI, TrueNAS Console, and zsh. |
| Sudo Commands | Shows options for entering sudo commands. Options are: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. Grants limited root-like permissions for this user when using these commands, and prompts the user for their account password. sudo commands, but prompts the user to enter their password.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. Exercise caution when allowing sudo commands without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks.sudo commands without seeing a prompt to enter their password. This is not recommended! |
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.
Administrator passwords can be changed on the Edit User screen or, if currently logged in as that admin user, by clicking the Settings icon on the top toolbar and clicking Change Password.
Click on the Change Password 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 icon to display entered passwords. To stop displaying the password, click on the icon.
Create a new administrator account or select an existing account to grant administrative privileges. Note the primary group assigned to that user.
Go to Credentials > Groups and select the row for primary group of the admin user to expand it. Click edit Edit.
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 group Members 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.
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.
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.
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.
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.
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.
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 ValidationUsers must have a home directory and shell access to log in with SSH.
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.
Administrator logins work with TrueCommand, but you need to set up the TrueNAS connection using an API key.
Groups
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.
To see saved groups, go to Credentials > Groups.
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.
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.
Group names must also align with the Portable Filename Character Set defined by The Open Group.
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.
Click anywhere on a row to expand that group and show the group management buttons.
Use Members to manage membership and Edit or Delete to manage the group.
To manage group membership, go to Credentials > Groups, click on the group entry to expand it, then click Members to open the Update Members screen.
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.
To edit an existing group, go to Credentials > Groups, expand the group entry, and click edit Edit to open the Edit Group configuration screen. See Groups Screens for details on all settings.
Groups Screens
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.
Add opens the Add Group configuration screen.
Privileges opens the Privileges screen
Clicking on the arrow or anywhere on a group row expands it to show the group management buttons.
Use Members to manage membership and Edit or Delete to manage the group.
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.
| Setting | Description |
|---|---|
| GID | (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. 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. 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. |
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
TrueNAS privileges define the level of administrator access that members of different groups or roles have to the web interface. TrueNAS includes three predefined administrator roles (Read-Only Admin, Sharing Admin, and Local Administrator). Administrators can create custom privilege roles and assign them to groups to grant tailored levels of access to TrueNAS settings and features.
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.
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.
Privileges Screens
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.
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
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.
TrueNAS provides unified directory services configuration that supports connections 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 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.
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.
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.
Verify the domain controller has a valid PTR record in DNS.
TrueNAS performs a reverse DNS (PTR) lookup on the domain controller IP address during the domain join process. Kerberized services broadly require domain controllers to be resolvable via reverse DNS — without a valid PTR record, service behavior is unpredictable. Windows typically creates PTR records for domain controllers automatically, but confirm the record exists and resolves correctly before attempting to join.
Change the default hostname of the system from truenas to the name assigned to the TrueNAS system.
After taking these actions, you can connect to the Active Directory domain.
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.
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.
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.
Or
- Set the system BIOS to either local time or universal time.
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.
Enter the Basic Configuration settings:
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.
Enter the Credential Configuration settings:
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.
Select Use TrueNAS Server IDMAP Defaults to use default IDMAP configuration. Selected by default and recommended for most setups.
To customize IDMAP settings, clear Use TrueNAS Server IDMAP Defaults to reveal additional configuration options:
Builtin section with optional Name field and required Range Low and Range High fields.
IDMAP Domain section with required IDMAP Backend, Name, Range Low, and Range High fields.
See Understanding IDMAP Backends for more information on IDMapping.
Click Save.
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.
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.
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.
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.
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.
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.
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.
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.
Enter the Basic Configuration settings:
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 Configuration settings:
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.
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.
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 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.
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.
Enter the Basic Configuration settings:
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 Credential Configuration settings:
Select Kerberos User from the Credential Type dropdown list. Required.
Enter the IPA user account username in Username. Required.
Enter the password for the user account in Password. Required.
Enter the IPA Configuration settings:
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.
Configure SMB domain settings:
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.
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.
Click Settings to open the IPA screen to remove the IPA configuration. Clear all settings and click Save.
Configuring Kerberos
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).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!
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.
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.
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.
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.
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.
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 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.
Kerberos Realms Screens
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).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!
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.
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.
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.
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 a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).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!
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.
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.
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 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.
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. |
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
The Directory Services Configuration screen shows common and directory service-specific settings based on the type of directory service selected in Configuration Type.
Common settings:
Directory Service-specific settings:
The Basic Configuration settings show settings common to the three directory services available in TrueNAS: Active Directory, LDAP, and IPA (formerly FreeIPA).
The Credential Type setting changes the authentication settings shown for the directory service no matter which type is selected in Configuration Type. Active Directory, IPA and LDAP all show Kerberos authentication options, but LDAP shows additional settings based on LDAP options.
Credential Type sets the credential used to bind to the specified directory service. Kerberos credentials are required for Active Directory or IPA domains. Generic LDAP environments support various authentication methods. Available methods depend on the remote LDAP server configuration. If Kerberos credentials are selected for LDAP, GSSAPI binds replace plain LDAP binds. Use Kerberos or mutual TLS authentication when possible for better security.
LDAP Credential Configuration Settings
When Configuration Type is set to LDAP, Credential Configuration shows five options to define the authentication method for LDAP access:
- LDAP Plain
- LDAP Anonymous (shows no additional settings)
- LDAP MTLS
- Kerberos Principal
- Kerberous User
Each option shows different settings in Credential Configuration.
| Setting | Description |
|---|---|
| Bind DN | Specifies the distinguished name to use for authentication. This is the administrative account name for the LDAP server. Shows when LDAP Plain is selected. For example, cn=Manager,dc=test,dc=org. |
| Bind Password | Specifies the password for the Bind DN. Shows when LDAP Plain is selected. |
| Client Certificate | Specifies the client certificate to use for mutual TLS authentication to the remote LDAP server. Shows when LDAP MTLS is selected. |
| Kerberos Principal | A Kerberos principal is the unique identity, formatted as username@DOMAIN.COM, that Kerberos uses to issue authentication tickets. Kerberos keytabs configured in TrueNAS show on the dropdown list. The specified principal must have a matching entry in a keytab stored on TrueNAS. Keytabs are managed in Directory Services > Advanced Settings > Kerberos Keytabs. If a keytab entry does not exist for the specified principal, authentication fails. |
| Kerberos User | Shows the Username and Password authentication fields, and sets authentication to use the LDAP administrative account credentials. |
| Username | Username of the account used to obtain a Kerberos ticket for authentication to the LDAP server. A Kerberos ticket is a time-limited, encrypted |
| credential that allows TrueNAS to authenticate without transmitting passwords over the network. | |
| Password | Password for the user account that obtains the Kerberos ticket. A Kerberos ticket is a time-limited encrypted |
| credential that allows TrueNAS to authenticate without transmitting passwords over the network. |
The Active Directory Configuration section settings define the connection parameters and domain-specific options.
Beginning in TrueNAS 25.10, trusted domains are configured as part of the Active Directory configuration rather than as separate IDmap entries.
The Trusted Domains Configuration section controls access for trusted domains.
Enable Trusted Domains shows the Trusted Domains options that allow clients to access TrueNAS if they are members of domains with a trust relationship. When enabled, the Trusted Domain section and Add button show. Add shows the Basic Configuration section with the IDMAP Backend options.
The IDMAP Backend configuration defines how domain accounts joined to TrueNAS are mapped to Unix UIDs and GIDs on the TrueNAS server. Most TrueNAS deployments use the RID backend, which algorithmically assigns UIDs and GIDs based on the Active Directory account SID. Another common option is the AD backend, which reads predefined Active Directory LDAP schema attributes that assign explicit UID and GID numbers to accounts.
The IDMAP Backend dropdown list shows four options:
- AD (RFC2307/SFU attributes from Active Directory)
- LDAP
- RFC2307 (RFC2307 attributes from a standalone LDAP server)
- RID (Default - algorithmic mapping based on RID values)
Each option shows different settings.
Trusted Domain AD (RFC2307/SFU Attributes from Active Directory) Settings
| Setting | Description |
|---|---|
| Name | Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| Schema Mode | The schema mode the IDMAP backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2. |
| Unix Primary Group | Defines if the user’s primary group is fetched from Unix attributes (Services for Unix) or the Active Directory primary group. If enabled, the TrueNAS server uses the gidNumber LDAP attribute. If disabled, it uses the primaryGroupID LDAP attribute. |
| Unix NSS Info | If enabled, the login shell and home directory are retrieved from LDAP attributes (Unix attributes in Active Directory). If disabled, or if the Active Directory LDAP entry lacks Unix attributes, the home directory defaults to /var/empty. |
Trusted Domain LDAP Settings
| Setting | Description |
|---|---|
| Name | Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| LDAP Base DN | Directory base suffix to use for mapping UIDs and GIDs to SIDs. |
| LDAP User DN | Defines the user DN to be used for authentication to the LDAP server. |
| LDAP User DN Password | Secret to use for authenticating the user specified by ldap_user_dn. |
| LDAP Url | LDAP server to use for the IDMAP entries. |
| Readonly | If enabled, TrueNAS does not attempt to write new IDMAP entries. |
| Validate Certificates | Verify certificate authenticity. |
Trusted Domain RFC2307 Attributes from Standalone LDAP Server Settings
| Setting | Description |
|---|---|
| Name | Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| LDAP Url | LDAP server to use for the IDMAP entries. |
| LDAP User DN | Defines the user DN to be used for authentication to the LDAP server. |
| LDAP User DN Password | Secret to use for authenticating the user specified by ldap_user_dn. |
| Bind Path User | The search base that contains user objects in the LDAP server. |
| Bind Path Group | The search base that contains group objects in the LDAP server. |
| User CN | If set, query the CN attribute instead of the UID attribute for the user name in LDAP. |
| LDAP Realm | Append @realm to the CN for groups. Also, append it to users if user_cn is specified. |
| Validate Certificate | Verify certificate authenticity. |
Trusted Domain RID (Default - Algorithmic Mapping Based on RID Values) Settings
| Setting | Description |
|---|---|
| Name | Short name for the domain. This should match the NetBIOS domain name for Active Directory domains. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| SSSD Compat | Generate an IDMAP low range using the algorithm from SSSD. Use this option if the domain uses only a single SSSD IDMAP slice. |
Use Trusted Server IDMAP Defaults is enabled by default. Use the TrueNAS default IDMAP configuration unless you want to customize ID mapping. Defaults are suitable for new deployments without existing support for Unix-like operating systems. The default configuration uses the RID backend with predefined UID/GID ranges (builtin: 90000001-100000000, domain: 100000001-200000000).
When disabled, it shows IDMAP configuration settings to customize ID mapping.
Only administrators experienced with configuring ID mapping should customize IDMAP settings.
The Builtin settings map Windows built-in local groups to Unix GIDs, defining the UID/GID range allocated to Windows built-in local groups, such as Administrators, Users, and Guests. TrueNAS creates this entry automatically when joining a domain. Adjust the range only if it conflicts with existing local UID/GID assignments.
IDMAP Domain settings configure how TrueNAS maps Windows domain users and groups from the joined domain to Unix UIDs and GIDs. The selected backend determines whether mappings are generated algorithmically or read from directory attributes. The UID/GID range defined here must not overlap with local accounts or trusted domain ranges.
The IDMAP Backend configuration defines how domain accounts the domain TrueNAS is joined to are mapped to Unix UIDs and GIDs on the TrueNAS server. Most TrueNAS deployments use the RID backend, which algorithmically assigns UIDs and GIDs based on the Active Directory account SID. Another common option is the AD backend, which reads predefined Active Directory LDAP schema attributes that assign explicit UID and GID numbers to accounts.
The IDMAP Backend dropdown list shows four options:
- AD (RFC2307/SFU attributes from Active Directory)
- LDAP
- RFC2307 (RFC2307 attributes from a standalone LDAP server)
- RID (Default - algorithmic mapping based on RID values)
Each option shows different settings.
IDMAP Domain AD (RFC2307/SFU Attributes from Active Directory) Settings
| Setting | Description |
|---|---|
| Name | Short name for the joined domain. Typically matches the NetBIOS domain name. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| Schema Mode | The schema mode the IDMAP backend uses to query Active Directory for user and group information. The RFC2307 schema applies to Windows Server 2003 R2 and newer. The Services for Unix (SFU) schema applies to versions before Windows Server 2003 R2. |
| Unix Primary Group | Defines if the user’s primary group is fetched from Unix attributes (Services for Unix) or the Active Directory primary group. If enabled, the TrueNAS server uses the gidNumber LDAP attribute. If disabled, it uses the primaryGroupID LDAP attribute. |
| Unix NSS Info | If enabled, the login shell and home directory are retrieved from LDAP attributes (Unix attributes in Active Directory). If disabled, or if the Active Directory LDAP entry lacks Unix attributes, the home directory defaults to /var/empty. |
IDMAP Domain LDAP Settings
| Setting | Description |
|---|---|
| Name | Short name for the joined domain. Typically matches the NetBIOS domain name. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| LDAP Base DN | Directory base suffix to use for mapping UIDs and GIDs to SIDs. |
| LDAP User DN | Defines the user DN to be used for authentication to the LDAP server. |
| LDAP User DN Password | Secret to use for authenticating the user specified by ldap_user_dn. |
| LDAP Url | LDAP server to use for the IDMAP entries. |
| Readonly | If enabled, TrueNAS does not attempt to write new IDMAP entries. |
| Validate Certificates | Verify certificate authenticity. |
IDMAP Domain RFC2307 Attributes from Standalone LDAP Server Settings
| Setting | Description |
|---|---|
| Name | Short name for the joined domain. Typically matches the NetBIOS domain name. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| LDAP Url | LDAP server to use for the IDMAP entries. |
| LDAP User DN | Defines the user DN to be used for authentication to the LDAP server. |
| LDAP User DN Password | Secret to use for authenticating the user specified by ldap_user_dn. |
| Bind Path User | The search base that contains user objects in the LDAP server. |
| Bind Path Group | The search base that contains group objects in the LDAP server. |
| User CN | If set, query the CN attribute instead of the UID attribute for the user name in LDAP. |
| LDAP Realm | Append @realm to the CN for groups. Also append it to users if user_cn is specified. |
| Validate Certificate | Verify certificate authenticity. |
IDMAP Domain RID (Default - Algorithmic Mapping Based on RID Values) Settings
| Setting | Description |
|---|---|
| Name | Short name for the joined domain. Typically matches the NetBIOS domain name. |
| Range Low | The lowest UID or GID that the IDMAP backend can assign. |
| Range High | The highest UID or GID that the IDMAP backend can assign. |
| SSSD Compat | Generate an IDMAP low range using the algorithm from SSSD. Use this option if the domain uses only a single SSSD IDMAP slice. |
The LDAP Configuration section settings define the connection parameters and validation options.
The Auxiliary Parameters subsection allows customization of auxiliary parameters.
Use Standard Auxiliary Parameters is enabled by default. Disable to enter custom options for nslcd.conf.
Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
The Search Bases uses standard search bases when enabled. Disable to allows customization of search base DNs. Use the base DN for user, group, and netgroup searches. Disable to specify alternative LDAP search base settings to define where to find user, group, and netgroup entries. Use custom search bases only if the LDAP server uses a non-standard LDAP schema or if you want to limit the accounts available on TrueNAS.
The Attribute Maps settings allow customization of attribute mappings by defining custom LDAP attribute names for user and group account fields. An attribute left blank uses the default attribute name for that field. Only use custom attribute maps if the LDAP server is non-standard, if your LDAP schema uses non-standard attribute names.
Use Standard Attribute Maps is enabled by default, and uses standard RFC2307 or RFC2307BIS attribute mappings. When disabled, the standard LDAP attribute mapping for LDAP servers that do not follow RFC2307 or RFC2307BIS shows to allow for customization.
The screen groups settings into LDAP password attributes, shadow attributes, and group attributes: LDAP Password Attributes, LDAP Shadow Attributes, LDAP Group Attributes, and LDAP Net Group Attributes.
LDAP Password Attribute Settings
| Setting | Description |
|---|---|
| User Object Class | Specifies the entry object class in LDAP for the user. |
| Username Attribute | Specifies the LDAP attribute for the login name for the user. |
| UID Attribute | Specifies the LDAP attribute for the id of the user. |
| GID Attribute | Specifies the LDAP attribute for the primary group id for the user. |
| GECOS Attribute | Specifies the LDAP attribute for the gecos field for the user. |
| Home Directory Attribute | Specifies the LDAP attribute for the home directory for the user. |
| Shell Attribute | Specifies the LDAP attribute for the path to the default shell for the user. |
LDAP Shadow Attribute Settings
| Setting | Description |
|---|---|
| Last Change Attribute | Specifies the LDAP attribute for password last change. |
| Min Days Attribute | Specifies the LDAP attribute for minimum password age. |
| Max Days Attribute | Specifies the LDAP attribute for maximum password age. |
| Warning Attribute | Specifies the LDAP attribute for password warning period. |
| Inactive Attribute | Specifies the LDAP attribute for the account inactive period. |
| Expire Attribute | Specifies the LDAP attribute for account expiration. |
LDAP Group Attribute Settings
| Setting | Description |
|---|---|
| Group Object Class | Specifies the LDAP object class for groups. |
| Netgroup Member Attribute | Specifies the LDAP attribute for group members. |
| Netgroup Triple Attribute | Specifies the LDAP attribute for group triples. |
LDAP Net Group Attribute Settings
| Setting | Description |
|---|---|
| Netgroup Object Class | Specifies the LDAP object class for netgroups. |
| Netgroup Member Attribute | Specifies the LDAP attribute for netgroup members. |
| Netgroup Triple Attribute | Specifies the LDAP attribute for netgroup triples. |
The IPA Configuration settings define the connection parameters and validation options.
The SMB Domain Configuration settings control SMB integration.
Use Default SMB Domain Configuration is enabled by default, and uses the default SMB domain settings detected during the IPA join. Settings for the IPA SMB domain are automatically detected by TrueNAS during the domain join process. Some IPA domains might not include SMB schema configuration. IPA includes integrated Samba support and can provide user and group information for SMB authentication. Disable to enter custom settings.
The Show button to the right of Advanced Settings opens a warning dialog stating that incorrectly configuring advanced settings is dangerous. Continue closes the warning dialog.
After closing the warning dialog, the Directory Services screen shows the Kerberos Realm and Kerberos Keytab cards.
Each Kerberos card shows the realms or keytabs configured in TrueNAS.
Add on the Kerberos cards opens configuration screens for each Kerberos function:
The Add Kerberos Realm screen allows adding a Kerberos realm to the TrueNAS system.
| Setting | Description |
|---|---|
| Name | Specifies a short name for the Kerberos realm. The Kerberos standard allows upper case characters, DNS rules apply, and does not exceed 253 characters (letters, digits, and/or hyphens). TrueNAS does not enforce naming conventions, but requires entering a name. |
| Primary KDC | Specifies the master Kerberos domain controller for this realm. TrueNAS uses this as a fallback if it cannot get credentials because of an invalid password. This can help in environments where the domain uses a hub-and-spoke topology. Use this setting to reduce credential errors after TrueNAS automatically changes its machine password. |
| KDC | Specifies the name of the Key Distribution Center. Pressing Enter separates multiple values. |
| Admin Server | Defines the server where all changes to the database are performed. Pressing Enter separates multiple values. |
| Password Server | Defines the server where all password changes are performed. Pressing Enter separates multiple values. |
The Add Kerberos Keytabs allows adding a keytab file using the file browser option and assigning the keytab a name.
Name specifies a short name for the keytab on the TrueNAS system. Kerberos does not have a name convention for keytab files.
Choose File opens the file browser to locate and upload a keytab file. Kerberos keytab files are binary files in a specific format (MIT Kerberos keytab format). Keytab files can have either the .keytab or .kt extension.
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.
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:
- Amazon S3
- Backblaze B2
- Box
- Dropbox
- File Transfer Protocol (FTP)
- Google Cloud Storage
- Google Drive
- Google Photos
- Hypertext Transfer Protocol (HTTP)
- Hubic (closed to new accounts)
- Microsoft Azure Blob Storage
- Microsoft OneDrive
- OpenStack Swift
- pCloud
- SSH File Transfer Protocol (SFTP)
- Storj iX*
- WebDAV
- Yandex
*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.
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.
For details on each provider authentication settings see Cloud Credentials Screens.
Enter a name for the credential.
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.
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.
Enter a descriptive name to identify the credential in the Name field.
You can create your Storj iX cloud service account using two methods:
- Go to the TrueNAS Storj web page and click Sign Up & Log in - iX-Storj.
- Go to Credentials > Backup Credentials and click Add. Select Storj iX as the Provider on the Cloud Credentials screen, then click Sign up for account.
The Storj Create your Storj account web page opens.
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.
After setting up your Storj iX account, set up Storj S3 access and create your Storj bucket.
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.
After creating your Storj iX account, add S3 access credentials.
Click Access Keys to open the Access Keys dashboard, then click New Access Key.
The New Access window opens.
Enter the name you want to use for this credential. Select S3 Credentials for access type, then click Next.
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.
To enable TrueNAS to create new Storj buckets, set the access configuration to Full Access.(Optional) If configuring advanced access options:
a. Select the permissions to allow. Choose one or more of Read, Write, List, Delete, or choose All Permissions. Click Next.
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.
d. Review access details and then click Create Access.
Use Copy All or Download All to obtain the access key, secret key, and endpoint. Keep these in a safe place where you can back up the file.
Click Close.
Enter these keys in the Authentication fields in TrueNAS on the Cloud Credentials screen to complete setting up the cloud credential.
Enter the authentication information provided by Storj in the Access Key ID and Secret Access Key fields.
Click Verify Credentials and wait for the system to verify the credentials.
Click Save.
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.
If using the Add TrueCloud Backup Task screen:
Select the stored Storj cloud credential from the Credentials dropdown. Do this as part of setting up a task.
Select Add New from the Bucket dropdown.
Enter a name for the new bucket. Only lowercase letters, numbers, and hyphens are allowed
Continue to configure the TrueCloud backup task, then click Save. TrueNAS creates the task and remote bucket on Storj.
If using the Cloud Sync Task Wizard:
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.
Select Add New to open the Add Bucket screen.
Enter a name for the new bucket.
Click Save. TrueNAS creates the remote bucket on Storj and then returns to the Cloud Sync Task Wizard.
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:
Open a web browser tab to Amazon AWS.
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.
a. Enter the S3 API endpoint URL in Endpoint URL.
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.
b. Enter an AWS resources in a geographic area in Region.
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
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. Dropbox Create an access token from the Dropbox account. Google Drive 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. Yandex Create the Yandex access token here. Click Verify Credentials to make sure you can connect with the entered credentials.
Click Save.
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.
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.
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:
Enter your OpenStack OS_USERNAME from an OpenStack credentials file in User Name.
Enter the OS_PASSWORD from an OpenStack credentials file in API Key or Password.
(Optional) Select the version from the AuthVersion. For more information see rclone documentation. Select the desired option based on your use case.
Click Verify Credentials.
Click Save.
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.
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.
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.
Enter the authentication settings.
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.
Click Save.
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.
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.
Enter the authentication settings.
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.
Click Save.
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.
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.
Enter the authentication settings.
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.
Click Save.
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.
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.
Verify the user has TrueNAS Access selected and the full admin role selected, and the SSH Access selected to show the SSH authentication fields.
Paste the SSH public key text into the Public SSH Key field in the Authentication settings.
Do not paste the SSH private key.Click Save.
If you need to generate a new SSH key pair, see Generating SSH Keypairs.
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.
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 at the bottom of the SSH Keypairs configuration screen to download these strings as text files for later use.
Cloud Credentials Screens
These providers are supported for Cloud Sync tasks in TrueNAS:
- Amazon S3
- Backblaze B2
- Box
- Dropbox
- File Transfer Protocol (FTP)
- Google Cloud Storage
- Google Drive
- Google Photos
- Hypertext Transfer Protocol (HTTP)
- Hubic (closed to new accounts)
- Microsoft Azure Blob Storage
- Microsoft OneDrive
- OpenStack Swift
- pCloud
- SSH File Transfer Protocol (SFTP)
- Storj iX*
- WebDAV
- Yandex
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
The Cloud Credentials widget displays a list of cloud storage credentials configured on the system.
Before adding cloud credentials for a cloud storage provider, the Cloud Credentials widget displays No Cloud Credentials configured.
Add opens the Cloud Credentials configuration screen.
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.
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 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.
Amazon S3 has basic authentication and advanced authentication settings. This section provides information on the basic authentication settings.
This section provides information on Amazon S3 advanced authentication settings for endpoints. The basic authentication settings are required when using the advanced settings.
This section provides information on the BackBlaze B2 authentication settings.
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.
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.
Google Cloud Storage authentication uses a Google service account JSON key credential file to authenticate the account.
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.
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 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 uses the Microsoft Azure account name and account key to authenticate the account credentials.
OpenStack Swift uses several required settings to authenticate credential accounts. The AuthVersion setting selection changes setting options displayed in 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.
V3 Authentication Settings
Setting AuthVersion to v3 shows additional authentication settings.
| Setting | Description |
|---|---|
| User ID | (Optional) Enter the user ID to log in. To log into most swift systems, leave this blank. For more information, see rclone documentation. |
| User Domain | (Optional) Enter the user domain. For more information, see rclone documentation. |
| Tenant Name | (Required) Enter the OS_TENANT_NAME from an OpenStack credentials file. |
| Tenant ID | Required for v2 and v3. Enter the tenant ID. For more information, see rclone documentation. |
| Tenant Domain | (Optional) Enter the tenant domain. 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 | Enter service catalog option. For more information, see rclone documentation. |
WebDAV uses a URL, service type, and user credentials to authenticate the cloud account credentials.
Microsoft OneDrive uses several required settings to authenticate credential accounts.
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.
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 icon shows options to Edit or Delete the connection. Delete opens a dialog with an option to delete the associated SSH Keypair.
The settings on the SSH Connections configuration screens are the same whether you add a new connection or edit an existing connection.
| Name | Description |
|---|---|
| Connection Name | (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: |
These authentication settings show when Setup Method is Semi-automatic (TrueNAS only).
| Name | Description |
|---|---|
| TrueNAS URL | (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. |
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.
| Name | Description |
|---|---|
| Host | (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. |
| Name | Description |
|---|---|
| Connect Timeout | Enter the time (in seconds) before the system stops attempting to establish a connection with the remote system. |
Save automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The SSH Keypairs widget on the Backup Credentials screen lists SSH key pairs added to the TrueNAS system.
The name of the key pair listed on the widget is a link that opens the SSH Keypairs configuration screen.
The 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.
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.
| Name | Description |
|---|---|
| Name | 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. |
| Private Key | See Authentication in SSH/Authentication. |
| Public Key | See Authentication in SSH/Authentication |
Save adds the key pair to the widget and activates the more_vert with options to Download Private Key and Download Public key.
Backup Credentials Screens
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 Backup Credentials screen displays the Cloud Credentials, SSH Connections, and SSH Keypairs widgets.
Click Add on the widget for the type of credential to add to open that configuration screen.
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.
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.
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.
TrueNAS allows you to rename a certificate or to add it to the TrueNAS trusted store.
Click on the 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.
Click on the 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 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 that the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
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.
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.
For information on how to add a DNS authenticator in TrueNAS, see Adding ACME DNS Authenticators.
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.
Click Next.
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.
Click Next.
(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.
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.
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 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.
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.
Enter a name.
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 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.
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 invoke an authenticator script and add an external DNS authenticator.
This requires an ACME authenticator script saved to the system. The script can invoke acme.sh or similar.
Creating ACME Certificates
TrueNAS allows users to automatically generate custom domain certificates using Let’s Encrypt.
- 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.
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.
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.
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.
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.
Certificates Screens
The Certificates widget on the Credentials > Certificates screen shows certificates added to TrueNAS.
Import opens the Import Certificate screen.
The icon for a listed certificate shows a dropdown list of options: Download, Edit, and Delete. Each TrueNAS has an internal certificate that enables encrypted access to the web interface.
Download downloads the certificate to the system. In Windows, this is the Downloads folder.
Edit opens the Edit Certificate screen.
Delete opens the Delete dialog.
The Import Certificate screen provides the settings options needed to import an existing certificate using the private key.
| Setting | Description |
|---|---|
| Name | (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. |
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. |
| 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 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.
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.
The icon for a listed CSR shows a dropdown list of options: Create ACME Certificate, Download, Edit, and Delete.
Create ACME Certificate opens the Create ACME Certificate screen.
Edit opens the Edit CA screen for the selected CSR.
Download puts a copy of the CSR on your server.
Delete opens the Delete Certificate dialog.
Add opens the Add CSR wizard.
The Create ACME Certificate screen shows settings to create an ACME Certificate by selecting an ACME Server Directory URI.
| Setting | Description |
|---|---|
| Identifier | 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. |
| DNS:UnitedStates | Sets the authenticator to validate the domain. Shows a dropdown list of previously configured ACME DNS authenticators. |
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.
| 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) 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. |
| 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 clipboard icon copies the certificate or public key to the clipboard.
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 (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.
| Setting | Description |
|---|---|
| Name | 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: |
| Profile | Sets the predefined certificate extention to either HTTPS RSA Certificate or HTTPS ECC Certificate. |
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.
| Setting | Description |
|---|---|
| Key Type | Sets the type of certificate to RSA or EC, and changes settings shown on the screen. RSA shows the Key Length field. EC shows the EC Curve field. See Why is elliptic curve cryptography not widely used, compared to RSA? for more information about key types. |
| EC Curve | 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. |
The Import Certificate screen shows when Type on the Identifier and Type screen is set to Import Certificate Signing Request.
| Setting | Description |
|---|---|
| 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. |
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.
| Setting | Description |
|---|---|
| Country | 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. |
| 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. |
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.
| Setting | Description |
|---|---|
| Basic Constraints | 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: |
| 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. |
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.
Add opens the Add DNS-Authenticator screen.
The icon for a listed certificate shows a dropdown list of options.
Edit opens the Edit DNS Authenticator screen.
deletes opens a Delete DNS Authenticator dialog.
Fields change based on Authenticator selection. The Edit DNS Authenticator screen shows the current settings entered and saved on the Add DNS Authenticator screen.
| Setting | Description |
|---|---|
| Name | 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. |
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
Configuring KMIP
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.
To connect TrueNAS to a KMIP server, import a Certificate from the KMIP server, then configure the KMIP options.
For security reasons, we strongly recommend protecting the certificate values.
Go to Credentials > KMIP.
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.
KMIP Screen
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.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 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.
| 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
TrueNAS supports Linux containers (LXC) for lightweight, isolated application environments that share the host system kernel.
Creating and Managing Containers
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.
When you first access the Containers screen, it displays a message indicating no containers are configured.
You can create containers immediately using the Create New Container button, or configure global settings first using the Configuration menu.
For more information on screens and screen functions, refer to the UI Reference article on Containers Screens.
Use the Configuration menu to access Settings where you can configure an optional preferred storage pool for containers and default network settings. The Configuration menu also provides access to Map User/Group IDs for configuring UID and GID mappings.
Click Configuration on the Containers screen header and select Settings to open the Settings screen. The screen displays global options that apply to all containers. Use these options to configure an optional preferred storage pool for containers and default network settings.
The Preferred Pool setting allows you to specify a default storage pool for container data. This setting is optional. If you do not specify a preferred pool, TrueNAS prompts you to select a pool when creating each container.
To set a preferred pool:
Click Configuration on the Containers screen header and select Settings.
Select a pool from the Preferred Pool dropdown list. The dropdown displays all available pools on your system.
Click Save.
We recommend keeping the container use case in mind when choosing a preferred 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 faster speed and resilience for repeated read/writes.
You can change the preferred pool at any time by opening Configuration > Settings and selecting a different pool from the Preferred Pool dropdown.
Use the Default Network settings in the Settings screen to define how containers connect to the network. These settings apply to all new containers unless you configure different network settings for individual containers.
To configure default network settings:
Click Configuration on the Containers screen header and select Settings.
Select a bridge from the Bridge dropdown list:
- Automatic to allow TrueNAS to create and manage a dedicated virtual bridge (
truenasbr0) on the TrueNAS host using DHCP and routes their outbound traffic through the host via NAT. Change the defaults using the IPv4 Network and IPv6 Network fields if they conflict with your network. - Select an existing bridge interface to use that bridge for container networking.
See Accessing NAS from VMs and Containers for information on creating bridge interfaces.
TrueNAS EnterpriseCustom bridge selection is not available on High Availability systems. HA deployments always use Automatic to prevent issues that could interfere with controller failover.- Automatic to allow TrueNAS to create and manage a dedicated virtual bridge (
(Optional) When Bridge is set to Automatic, configure IP address ranges:
a. Enter an IPv4 address and subnet in IPv4 Network (for example, 192.168.1.0/24) to assign a specific IPv4 network for containers. Leave empty to allow TrueNAS to assign the default IPv4 address.
b. Enter an IPv6 address and subnet in IPv6 Network (for example, fd42:96dd:aef2:483c::1/64) to assign a specific IPv6 network for containers. Leave empty to allow TrueNAS to assign the default IPv6 address.
Click Save.
Adjust these settings as needed to match your network environment and ensure proper connectivity for containers.
High Availability (HA) functionality is available in TrueNAS Enterprise systems.
TrueNAS 26 adds support for containers in High Availability (HA) configurations. Containers can run on HA systems and automatically restart after a controller failover. However, HA environments require specific network configuration to ensure containers remain accessible after failover events.
Containers in HA environments must have a static IP address configured in the container operating system.
Without a static IP, the container loses network connectivity after a controller failover and becomes inaccessible.
Configure the static IP inside the container OS, not in TrueNAS network settings. Refer to your container operating system documentation for instructions on setting a static IP address.
When you configure containers for HA environments:
- Configure a static IP address inside each container OS before deploying containers in an HA system. This ensures the container retains its IP address across reboots and failover events. Maintain records of static IP addresses assigned to each container for troubleshooting and network planning.
- Mount container data to datasets that persist across failovers. This ensures container data remains available after a controller switchover.
- Select the Autostart option in container configuration to automatically start containers after a failover. See Editing Container Configuration Settings for details.
- Perform test failovers to verify containers restart properly and remain accessible with their static IP addresses.
When a controller failover occurs in an HA system:
- Containers on the active controller experience a hard shutdown without a graceful stop sequence.
- After failover completes, containers configured with Autostart automatically start on the new active controller.
- Containers with static IP addresses restore network connectivity and become accessible again.
- Container data persists if stored on datasets that remain available after failover.
A hard shutdown during failover can result in data loss for applications that do not handle abrupt stops gracefully.
For production containers in HA environments:
- Use applications designed to handle unexpected shutdowns
- Configure regular backups or snapshots
- Store critical data on persistent datasets
- Test your containers’ behavior during simulated failovers
When a container reads or writes to a host dataset mounted via a file system device, TrueNAS checks whether the user identity inside the container has permission to access that path on the host. User accounts inside containers are independent from host user accounts, so a user named appuser with UID 1000 inside a container is not the same identity as UID 1000 on the TrueNAS host, even though they share the same number.
To bridge this gap, TrueNAS uses UID/GID mapping: a translation layer that tells the host which host user corresponds to each container user. For most containers you do not need to configure this manually — the default behavior set by the ID Map Type for the container at creation time handles it automatically. The Map User/Group IDs screen is for cases where you need finer control, such as granting a specific host user access to data a container reads or writes.
By default (when ID Map Type is set to Default), TrueNAS shifts all container UIDs and GIDs into a private range on the host starting at 2147000001. This means container UID 0 (root) maps to host UID 2147000001, container UID 1 maps to 2147000002, and so on. No container process appears as a real user on the host, which prevents a compromised container from having any meaningful access to host resources.
The special host user truenas_container_unpriv_root (UID 2147000001) represents the container root on the host when using default ID mapping. To give a container running as root access to a host dataset, assign dataset permissions to truenas_container_unpriv_root — no mapping configuration is required.
You need to configure a custom mapping when:
- An application inside the container runs as a specific non-root UID (for example, UID 1000) and needs access to a TrueNAS dataset.
- You want a specific TrueNAS user account to own files the container creates on a shared dataset.
- You are sharing a dataset between a container and other services (like an SMB share) and need consistent ownership.
In these cases, you create a mapping that tells TrueNAS: when the container acts as UID X, treat it as host user Y.
Click Configuration on the Containers screen header and select Map User/Group IDs to open the Map User and Group IDs screen.
Select the Users or Groups tab to view and manage mappings for user or group accounts respectively.
Existing mappings appear in a table listing 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.
Choose how to map the ID:
- Select Map to the same UID/GID in the container to use the identical ID number inside the container (for example, host UID 1000 → container UID 1000).
- Disable it to assign a different container ID. Enter the UID or GID the container uses for this account — for example, 1000.
Click Set to save the mapping.
Changes apply immediately, though restarting the container might be required for them to take effect.
Only local TrueNAS users and groups are supported. Active Directory and other directory service accounts cannot be used for container ID mapping.
For example, if your container runs a service as UID 1000 and you want it to read and write to a TrueNAS dataset owned by the local user mediauser (host UID 3000):
- Create a mapping for the host user mediauser to the container UID 1000.
- Assign the dataset permissions to mediauser on the host.
- The container service running as UID 1000 can now access that dataset.
Incorrect or missing mappings cause permission denied errors when containers access mounted host paths.
Click Create New Container to open the Add Container configuration wizard.
The Add Container screen displays basic configuration fields and an Advanced Options button for additional settings.
To create a new container:
Enter a Name for the container.
(Optional) Enter a Description for the container.
(Optional) Select Autostart to automatically start the container when the system boots.
When you enable autostart, TrueNAS automatically starts the container during system boot after the containers service initializes, ensuring services are available immediately after system startup. During system shutdown, TrueNAS sends a graceful shutdown signal to the container, allowing applications to close properly and save data.
Click Browse Catalog to open the Select Image screen.
Search or browse to choose a Linux image. Click Select in the row for your desired image.
(Conditional) Select a Pool for the container. This field appears when no preferred pool is configured in global container settings.
(Optional) Click Advanced Options to configure additional settings:
Use CPU Configuration to bind the container to specific CPU cores (useful for performance-sensitive workloads or isolating container resources).
Use Time Configuration to set the container time zone (Local or UTC) and shutdown timeout (how long to wait for graceful shutdown before forcing termination).
Use Init Process to configure the init command, working directory, and user/group for the PID 1 process for the container. The default init command is
/sbin/init. Note: The init command cannot be changed after creation, but working directory, user, and group remain editable.Use ID Mapping to control how container UIDs and GIDs map to host UIDs and GIDs. This setting cannot be changed after the container is created. Options include:
- Default (recommended): Container root maps to the unprivileged host user truenas_container_unpriv_root. Provides security isolation for most workloads.
- Isolated: Assigns a unique UID/GID range to this container to prevent overlap with other containers. Use when multiple containers share access to the same host datasets.
- Privileged: Removes UID isolation — container UIDs map directly to host UIDs, including root. Required for nested container runtimes. See Running Nested Containers.
Use Environment Variables to define environment variables that are available inside the container.
Use Capabilities to control Linux capabilities (special permissions). Use DEFAULT for most containers (secure and functional) or ALLOW to grant all capabilities when containers need broad system access (reduces isolation). ALLOW is required for nested container runtimes. See Running Nested Containers.
Click Create to deploy the container.
Device configuration (network interfaces, USB devices, GPU devices, and file system mounts) is performed after container creation using the detail cards on the Containers screen.
See the following sections for device configuration procedures:
- Managing NICs for network interface configuration
- Managing USB Devices for USB device passthrough
- Managing GPU Devices for GPU hardware acceleration
- Configuring File system Devices for additional file system mounts
A nested container is a container that runs its own container runtime — for example, a TrueNAS container with Docker installed and running inside it. Nested container runtimes require direct UID mapping and full Linux capabilities, which means the container must be configured as privileged.
Privileged containers remove UID isolation between the container and the TrueNAS host. Container processes running as root have direct host root access.
Only use privileged containers for workloads that specifically require nested container support, and ensure the container image and its contents are trusted.
To create a container that supports a nested container runtime such as Docker:
Begin creating a container as described in Creating a Container.
Click Advanced Options.
Under ID Mapping, set ID Map Type to Privileged.
Under Capabilities, set Capabilities Policy to ALLOW.
Complete the remaining settings and click Create.
After the container starts, open a shell session from the Tools card and install the container runtime of your choice.
Created containers appear in a table on the Containers screen. The table lists each configured container, displaying its name, current status, autostart setting, and live resource metrics: CPU %, Memory MiB, and Disk I/O % Full Pressure. Metrics display N/A for stopped containers. 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 cards with information and management options for the selected container.
Apply actions to one or more selected containers on your system using Bulk Actions.
Use the dropdown to select Start All Selected, Stop All Selected, or Restart All Selected.
After selecting the container row in the table to populate the Details for Container cards, locate the General Info card.
Click Edit to open the Edit Container: Container screen.
The edit screen allows you to modify container settings after creation. You can change Name, Description, Autostart, and all Advanced Options settings.
Settings you cannot change after creation: The edit screen allows you to modify container settings after creation. You can change Name, Description, Autostart, and all Advanced Options settings.
- Pool: The storage pool cannot be changed after deployment
- ID Map Type: The UID/GID mapping mode is fixed at creation
- Init Process command: The init command is fixed, but Init Working Directory, Init User, and Init Group remain editable
For detailed information about each setting, see the Add Container Screen section in the UI Reference.
After selecting the container row in the table to populate the Details for Container cards, locate the General Info card.
Click Delete to open the Delete dialog.
Select Confirm to activate the Continue button. Click Continue to delete the container.
Use the USB Devices card to view and manage USB devices attached to the container. USB device passthrough allows containers to access USB peripherals as if they are physically connected.
Click Add to open a list of available USB devices. USB device passthrough allows containers to access USB peripherals as if they are physically connected.
USB devices appear in the list only if they are physically connected to the TrueNAS system and not currently allocated to another container or VM.
Use the GPU Devices card to attach GPU hardware to containers for graphics acceleration or computation tasks.
TrueNAS supports GPU passthrough for containers with the following GPU vendors:
- NVIDIA (Turing architecture and later) - Requires driver installation
- Intel - Native support (no drivers needed)
- AMD - Native support (no drivers needed)
For NVIDIA GPUs, you must install drivers before attaching the GPU to a container. Go to System > Advanced Settings to install NVIDIA drivers. See Advanced Settings Screen for detailed instructions.
Click Add to open a list of available GPU devices. Select a GPU from the list to attach it to the container.
GPU devices appear in the list only if:
- The physical GPU hardware is installed and detected by TrueNAS.
- The NVIDIA GPU drivers are installed via System > Advanced Settings.
- The GPU device is not currently allocated to another container or VM.
Use the Filesystem Devices card to mount additional host directories or datasets into the container. File system devices provide containers with access to TrueNAS storage for reading and writing data.
To add a file system device: File system devices provide containers with access to TrueNAS storage for reading and writing data.
Click Add in the Filesystem Devices card.
To add a file system device:Enter or browse to select the Host Directory Source. This is the directory or dataset path on the TrueNAS host that you want to mount into the container.
Enter the Container Mount Path. This is the mount point inside the container where the file system appears (for example, /mnt/data or /var/lib/appdata).
Click Save to create the file system device mount.
To edit or delete an existing file system device, click the icon and select Edit or Delete.
Use cases for file system devices:
- Mounting TrueNAS datasets for persistent container data storage
- Providing containers with access to shared media libraries
- Mounting configuration directories from the host Use cases for file system devices:
Use the NIC Devices card to view and manage network interfaces (NICs) attached to the container.
Each NIC displays the network interface name and MAC address (for example, br0 (aa:bb:cc:dd:ee:ff) or br0 (Default Mac Address)).
NIC modifications are restricted when there are pending network interface changes on the TrueNAS system. If you see a warning about pending changes, apply or revert those changes before modifying container NICs.
To add a NIC:
Click Add to open a dropdown with available network interfaces.
Select a NIC from the list to open the configuration dialog.
Configure the NIC settings:
- Use NIC Type to select the network interface type (virtio, macvlan, ipvlan, etc.).
- (Create only) Select Use Default Mac Address to automatically assign a MAC address.
- Use Mac Address to enter a custom MAC address, or leave empty to use the default.
- (virtio only) Select Trust Guest RX Filters to trust guest OS receive filter settings for better performance.
Click Add to attach the NIC to the container.
To edit or delete an existing NIC:
Stop the container if it is running. Click stop_circle to stop the container.
Click the icon next to the NIC.
Select Edit to modify the NIC settings, or Delete to remove the NIC.
Click Confirm to activate the Continue button. Click Continue to start the delete operation.
After selecting the container row in the table to populate the Details for Container cards, locate the Tools card. You can open a shell session directly from this card.
Click Shell to open a Container Shell session for command-line interaction with the container.
Containers Screens
The Containers screen allows users to add, edit, or manage Linux containers.
The Containers screen displays No Containers before you create the first container.
The Configuration dropdown opens options to configure global container settings:
- Settings opens the Settings screen to configure the preferred pool and default network.
- Map User/Group IDs opens the Map User and Group IDs screen to configure UID and GID mappings.
Create New Container at the top right of the screen opens the Add Container screen.
The Settings screen displays global options that apply to all containers, including an optional preferred storage pool and default network settings.
Preferred Pool specifies an optional default storage pool for container data. When no preferred pool is configured, TrueNAS prompts for pool selection at container creation.
Default Network settings configure global networking defaults for the containers service.
| Setting | Description |
|---|---|
| Bridge | Network bridge for containers. Automatic creates and manages a dedicated virtual bridge (truenasbr0) on the TrueNAS host, assigns container IP addresses via DHCP, and routes outbound traffic through the host via NAT. Default ranges are 172.200.0.0/24 (IPv4) and fd42:4c58:43ae::/64 (IPv6), configurable via IPv4 Network and IPv6 Network. Additional options show existing configured bridges. See Accessing NAS from VMs and Containers for more information. Custom bridge selection is not available on High Availability systems. HA deployments always use Automatic to prevent bridge STP issues that could interfere with controller failover. |
| IPv4 Network | (Displayed only when Bridge is set to Automatic) IPv4 address and subnet for the automatic bridge (for example, 192.168.1.0/24). Defaults to the system-assigned address when empty. At least one network (IPv4 or IPv6) must be configured. |
| IPv6 Network | (Displayed only when Bridge is set to Automatic) IPv6 address and subnet for the automatic bridge (for example, fd42:96dd:aef2:483c::1/64). Defaults to the system-assigned address when empty. At least one network (IPv4 or IPv6) must be configured. |
The Map User and Group IDs screen allows users to manually configure UID and GID mappings between the TrueNAS host and containers. It opens after clicking Configuration on the Containers screen header and selecting Map User/Group IDs.
Existing mappings appear in a table listing the user or group name, host ID, and container ID. delete Delete on a row removes that mapping.
Set creates the mapping. Changes apply immediately, though restarting the container might be required for them to take effect.
The Add Container screen displays basic configuration fields and an Advanced Options button for additional settings.
The basic settings are always visible and configure essential container properties.
| Setting | Description |
|---|---|
| Name | Required. Enter an alphanumeric name for the container. |
| Description | Specifies an optional description about the container or how it is used. |
| Autostart | Automatically starts the container when the system boots when selected. |
| Image | Specifies the operating system image file for the container. Browse Catalog opens the Select Image screen with available Linux image choices, with an option to search or browse to locate a desired image. |
| Pool | Specifies a storage pool for the container. Only shows when no preferred pool is configured in Settings. |
Advanced Options shows additional configuration settings.
The Storage settings only show when a preferred pool is configured in Settings.
| Setting | Description |
|---|---|
| Use Preferred Pool | Sets the selected pool as the preferred pool to store the container. Only shows when a preferred pool is configured. When selected, this container is stored on the configured preferred pool. When not enabled, the Pool dropdown shows a list of pools to choose from. |
| Pool | Sets a storage pool for the container to use. Only shows when Use Preferred Pool is deselected. |
The CPU Configuration settings bind the container to specific CPU cores.
| Setting | Description |
|---|---|
| CPU Set | Specifies CPU core numbers to allocate to the container (e.g., 0,1,2 or 0-3). Leave blank to allow the container access to all host CPU cores. |
The Time Configuration settings control container time zone and shutdown behavior.
| Setting | Description |
|---|---|
| Container Time | Sets the time zone for the container. Local uses the host system time. UTC uses Coordinated Universal Time. |
| Shutdown Timeout | Specifies the number of seconds to wait for the container to shut down gracefully before forcing termination. Default is 30 seconds. |
The Init Process settings configure the initialization process for the container.
| Setting | Description |
|---|---|
| Init Process | Specifies the init process command line. Default is /sbin/init. |
| Init Working Directory | Specifies the working directory for the init process. |
| Init User | Specifies the user to run the init process as. |
| Init Group | Specifies the group to run the init process as. |
The Environment Variables settings configure optional environment variables to run on boot or execute.
Add shows a set of environment variable fields each time you click it.
| Setting | Description |
|---|---|
| Name | Specifies the environment variable name (e.g., PATH, HOME). |
| Value | Specifies the value for the environment variable. |
The ID Mapping settings configure how user and group IDs (UIDs/GIDs) inside the container map to UIDs/GIDs on the TrueNAS host. This setting is available at container creation only and cannot be changed after the container is created.
| Setting | Description |
|---|---|
| ID Map Type | Sets the UID/GID mapping mode for the container from the options: |
Setting ID Map Type to Privileged removes all UID isolation between the container and the TrueNAS host. Container processes running as root have direct host root access. Use only when an application explicitly requires it and you understand the security implications.
Capabilities settings control Linux capabilities, which are special permissions that divide root privileges into distinct units.
Allows containers to perform specific privileged operations without granting full root access.
| Setting | Description |
|---|---|
| Capabilities Policy | Sets the default policy for container capabilities: |
Device configuration (network interfaces, USB devices, GPU devices, and file system mounts) is performed after container creation using the detail cards on the Containers screen.
See Containers Cards for information on configuring devices.
The Containers table lists each configured container name, current state, autostart setting, and live resource metrics: CPU %, Memory MiB, and Disk I/O % Full Pressure (shown as N/A when the container is stopped or metrics are unavailable).
Stopped containers show the option to start the container.
The Details for Container cards show information and management options for the selected container.
The restart_alt button restarts or the stop_circle button stops a running container.
The Stop Options window defines how the container stops:
- Wait for graceful stop - Sends a shutdown signal and waits indefinitely for the container to stop gracefully. Does not force kill the container.
- Wait for graceful stop, then force - Sends a shutdown signal and waits for the shutdown timeout (default 30 seconds) for the container. Force-kills the container if still running after the timeout expires.
- Force stop immediately - Immediately force kills the container without attempting graceful shutdown.
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.
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 cards display information and configuration options for the selected container.
The General Info card displays container configuration details including Description, Autostart, Dataset, CPU Set, Container Time, Shutdown Timeout, Init Process command, and Capabilities Policy. Init Working Directory, Init User, and Init Group also display when configured. It includes the Edit and Delete buttons for the container.
Delete opens the Delete dialog.
Edit opens an Edit Container: Container configuration screen populated with editable settings also found on the install wizard screen for the container.
The Delete dialog asks for confirmation to delete the selected container.
Confirm activates the Continue button. Continue starts the delete operation.
The USB Devices card displays USB devices attached to the container, allowing hardware passthrough for USB peripherals.
Add opens a list of available USB devices to attach to the container.
The GPU Devices card displays GPU hardware attached to the container for graphics or computation acceleration.
TrueNAS supports GPU passthrough for containers with the following GPU vendors:
| GPU Vendor | Driver Requirements | Notes |
|---|---|---|
| NVIDIA | Manual installation required | Supports Turing architecture and later. See Advanced Settings Screen for driver installation details. |
| Intel | Native support | No additional driver installation required. |
| AMD | Native support | No additional driver installation required. |
Add opens a list of available GPU devices. GPU devices only appear in the list if:
- The physical GPU hardware is installed and detected by TrueNAS
- The NVIDIA GPU drivers are installed via System > Advanced Settings
- The GPU device is not currently allocated to another container or VM
The Filesystem Devices card displays file system mounts that provide the container with access to host directories and datasets.
File system devices allow containers to read and write data to TrueNAS datasets or host paths.
Add opens fields to configure a new file system device mount.
| Setting | Description |
|---|---|
| Host Directory Source | Specifies the host source path for the file system to mount into the container. |
| Container Mount Path | Specifies the mount path inside the container where the file system appears, for example /mnt/data or /var/lib/data. |
For existing filesystem devices, the actions menu includes options to Edit or Delete the filesystem device.
See Configuring Filesystem Devices in the Containers tutorial for configuration procedures.
The NIC Devices card displays network interfaces (NICs) attached to the container.
Each NIC displays the network interface name and MAC address in the format: {interface_name} ({mac_address}). For example: br0 (aa:bb:cc:dd:ee:ff) or br0 (Default Mac Address).
NIC modifications are restricted when there are pending network interface changes on the TrueNAS system. If the card displays a warning about pending changes, apply or revert those network changes before modifying container NICs.
Add opens a menu with available network interfaces grouped by type.
The Add/Edit NIC Device dialog configures network interface settings for the container.
| Setting | Description |
|---|---|
| NIC Type | Sets the NIC type (virtio, macvlan, ipvlan, etc.). |
| Use Default Mac Address | Sets TrueNAS to automatically assign a MAC address. Only available when adding a new NIC. |
| Mac Address | Specifies a custom MAC address. Only shows while adding and when Use Default Mac Address is not selected. If editing a NIC, leave empty to use the default MAC address. |
| Trust Guest RX Filters | (virtio type only) When enabled, trusts guest OS receive filter settings for better performance. |
Add or Update applies the NIC configuration.
For existing NICs, the actions menu provides options to Edit or Delete the NIC.
NICs can only be modified when the container is stopped.
The Tools card provides quick access to the container shell.
Shell opens a Container Shell session for command-line interaction with the container. The shell is only available when the container is running.
The Edit Container: Container screen includes most settings from the Add Container Screen except Image, Pool, and ID Map Type.
Settings available in edit mode include Name, Description, Autostart, and all Advanced Options (CPU Configuration, Time Configuration, Init Process, Environment Variables, and Capabilities).
Note that the Init Process command field cannot be changed after creation, but Init Working Directory, Init User, and Init Group remain editable.
Device, disk, network, and other settings are configured via the Containers Cards on the Containers screen.
The screen has Basic settings (Name, Description, Autostart) visible by default, with an Advanced Options button to expand additional configuration sections.
For detailed field descriptions, see the Add Container Screen section. The Edit screen uses the same fields except Image, Pool, ID Map Type, and the Init Process command (none of which can be changed after creation).
Autostart in HA Environments
In High Availability configurations, containers with autostart enabled automatically restart on the new active controller after a failover. Ensure containers have static IP addresses configured to maintain network connectivity after failover. See Containers in High Availability Environments for details.
Virtual Machines
TrueNAS has built-in virtualization capabilities that allow running multiple operating systems on a single system. Virtual machines provide strong isolation between different operating systems and applications.
Creating and Managing 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.
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.
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.
Click Next.
Enter the CPU and Memory settings for your VM.
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.
Click Next.
Configure Disks settings.
Select Create new disk image to create a new zvol on an existing dataset.
Select Use existing disk image to use an existing zvol for the VM.
(Optional) Select Import Image to import an existing disk image file and convert it to a zvol for use by the VM.
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.
Click Next.
Configure Network Interface settings.
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.Click Upload to begin the upload process. After the upload finishes, click Next.
Specify GPU settings. When available, use a GPU previously isolated for VM use.
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.
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.
The VM options change when the VM is running.
Click device_hub Devices to open the Devices screen for that VM. Click the icon at the right of each listed device to see device options.
The devices for the VM display as a list.
Device notes:
- 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.
See Adding and Managing VM Devices for more information.
After creating the VM and configuring devices for it, click on the VM to expand it and show the options to manage the VM.
An active VM displays options for settings_ethernet Display and keyboard_arrow_right Serial 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 stop Stop to follow a standard procedure to do a clean shutdown of the running VM. Click power_settings_new Power 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 stop Stop button might not function as expected. The Running toggle and stop Stop 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.
To delete a VM, first stop it if it is running, then click delete Delete 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.
After configuring the VM in TrueNAS and an OS
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.
Upload the Debian Click Virtual Machines, then ADD to use the VM wizard.
Configure settings as needed. After creating the VM, start it. Expand the VM entry and click **Start**. 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. 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.Installing Debian OS Example
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.
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.
Adding and Managing VM 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.
The VM options change when the VM is running.
Click device_hub Devices to open the Devices screen for that VM. Click the icon at the right of each listed device to see device options.
The devices for the VM display as a list.
Device notes:
- 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 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 at the right of each device row, click Edit to open the Edit Device screen. Click Delete to open a delete confirmation dialog. t
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 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 don’t 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.
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 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 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 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.
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.
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.
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.
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 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.
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.
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.
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.
Virtual Machines Screens
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.
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.
The Delete Virtual Machine dialog shows options when deleting the VM and removing the VM configuration from your system.
| Setting | Description |
|---|---|
| Delete Virtual Machine Data | 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. |
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.
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.
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.
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.
The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.
The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.
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 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.
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.
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.
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.
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.
The Network Interface settings specify the network adapter type, MAC address, and physical network interface card associated with the VM.
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.
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.
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.
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
NIC Settings
VM network interface card settings show when Device Type is set to NIC.
| Setting | Description |
|---|---|
| Adapter Type | (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.
| Setting | Description |
|---|---|
| Zvol | 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.
| Setting | Description |
|---|---|
| Display Type | 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.
| Setting | Description |
|---|---|
| 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 |
| 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: |
| 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.
| Setting | Description |
|---|---|
| Controller Type | (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. |
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.
| Setting | Description |
|---|---|
| Destination Directory | 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: |
Apps
TrueNAS includes an application catalog for deploying and managing containerized applications.
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!
The TrueNAS Applications Market is the primary resource for app management tutorials and individual app deployment guides.
- For initial setup, storage configuration, app security, and support level definitions, visit Getting Started with Apps.
- For day-to-day tasks such as discovering, installing, and managing apps, visit Managing Apps.
- To search available applications and find app-specific tutorials and reference content, browse the Catalog.
This section contains UI reference documentation for the TrueNAS Apps screens and settings.
Apps Screens
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.
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.
After setting the pool, Apps Service Running shows on the screen header.
The Installed applications screen displays Check Available Apps before you install the first application.
Check Available Apps or Discover Apps opens the Discover screen.
Configuration on the Installed applications header displays global settings that apply to all applications.
- Choose Pool opens the Choose a pool for Apps dialog.
- Unset Pool shows after setting a pool for applications to use. It opens the Unset Pool dialog.
- Manage Container Images opens the Manage Container Images screen.
- Sign-in to a Docker registry opens the Docker Registries screen.
- Settings opens the Settings screen with four train options. Use to add or remove other trains to the one catalog of applications.
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.
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 location and iXvolume storage. Data in mounted host paths is not migrated.
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.
The Manage Container Images screen lists all container images downloaded on TrueNAS.
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 opens a side panel with options to download specific images to TrueNAS.
| Setting | Description |
|---|---|
| Image Name | Enter the full path and name for the specific image to download. Use the format registry/repository/image. |
| Image Tag | Enter the specific image tag string to download that specific version of the image. The default latest pulls whichever image version is most recent. |
| Docker Registry Authentication | Optional. Only needed for private images. |
| Username | User account name to access a private Docker image. |
| Password | User account password to access a private Docker image. |
Delete Delete in an image row or the Batch Operations section opens the Delete dialog. The dialog displays the selected image(s) to delete.
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.
The Docker Registries screen lists signed-in Docker registry records.
Add Registry opens the Create Docker Registry panel.
| Setting | Description |
|---|---|
| URI (Dropdown) | 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 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.
Check for docker image updates sets TrueNAS to check for docker image updates (default setting).
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.
Click on Application, Status, or Update on the table heading row to sort the table in ascending or descending order.
A yellow badge shows when an update is available. See Update Apps for more information on updating the application.
Search above the Applications table allows entering the name of an app to locate an installed application.
Selecting the checkbox to the left of Applications selects all installed apps and shows the Bulk Actions dropdown list.
The Bulk Action dropdown list allows you to apply actions to one or more applications installed and running on your system.
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.
Each app appears in a collapsible panel that displays the app name and current upstream version. Click the expand icon to view version details. A Version row appears when the upstream version changes. A Revision row shows the catalog revision change. A Version to be updated to dropdown appears for apps with multiple available revisions. A View Upstream Release Notes link appears when the app provides a changelog URL.
Click Update to begin updating the applications. Each app status changes to Stopped during the update and returns to Running when the update completes.
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.
The Application Info widget shows the name, Version (upstream application version), Revision (TrueNAS catalog revision), 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.
Edit opens an Edit Application configuration screen populated with editable settings also found on the install wizard screen for the application.
more_vert opens a dropdown containing the Update and Convert to custom app buttons.
Update opens a window for the application showing the current version and the new version the update installs.
Convert to custom app opens a Convert to custom app dialog to convert the installed application to a custom YAML app.
Web UI opens the application login or sign-up web page.
Roll Back opens the Roll Back dialog to revert an app to an earlier installed version.
Delete opens the Delete dialog. This deletes the application deployment but does not remove it from the catalog or train in TrueNAS.
The Delete dialog requires you to type the application name to confirm deletion.
Type the application name exactly as shown in the confirmation field. The Delete button remains disabled until the name is entered correctly.
Before clicking Delete, configure the following options as needed:
| Option | Description |
|---|---|
| Remove iXVolumes | Deletes hidden app storage from the apps pool. Only shown if the app has iXVolumes. |
| Force-Remove iXVolumes | Deletes app storage created on TrueNAS 24.04 and migrated to 24.10 or later. Only shown when Remove iXVolumes is selected. Removes both legacy Kubernetes and current Docker data for the application. Use with caution. |
| Remove Images | Prunes Docker images of the deleted app. Selected by default. |
Click Delete to remove the application.
Update shows on the Application Info widget after clicking Update All Selected on the Installed applications header. Both show only when TrueNAS detects an available update for an application. The application row on the Installed screen shows Update available when the upstream application version is changing, or Revision available when only the TrueNAS catalog revision is changing.
Update opens an update dialog showing the version change. When the upstream application version is changing, the dialog shows a Version row with the current and new upstream versions. The dialog always shows a Revision row with the current and new catalog revision numbers. When multiple catalog revisions are available, a Version to be updated to dropdown appears with options in the format Version: X / Revision: Y. A View Upstream Release Notes link appears when the app provides a changelog URL.
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 on the more_vert dropdown opens a dialog to convert an installed catalog application to a custom YAML application. Converting to a custom app allows direct editing of the YAML configuration file for the app using the Custom App Screens.
Convert to custom app is a one-time, permanent operation. When converted, a custom application cannot be converted back to a catalog version.
Cancel closes the dialog without converting the application.
Confirm enables the Convert button.
Convert begins the conversion process.
Roll Back on the more_vert dropdown opens a dialog to revert an application to the snapshot of an earlier installed version.
The Version dropdown contains available app versions for roll back. The version numbers displayed are the Revision of the app in the TrueNAS catalog, equivalent to the Revision displayed on the Application Info widget. This is the catalog revision, not the upstream 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.
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 Shell Shell button opens the Container Shell screen.
The Volume Mounts button opens the Volume Mounts dialog.
The View Logs Logs button also opens the Pod Logs screen for the app.
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.
Each Pod Log screen includes a banner with the Application Name, Pod Name and Container Name.
Use the logs to help troubleshoot problems with your container pods.
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.
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.
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.
The breadcrumbs at the top of the screen header show links to the previous or the main applications screen. Click a link to open that 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.
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.
See Install Custom App Screens for more information.
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.
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
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!
Custom App on the Discover screen opens the Install Custom 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.
The Install Custom 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.
Settings are grouped into Application Name, Image Configuration, Container Configuration, Security Context Configuration, Network Configuration, Portal Configuration, Storage Configuration, and Resources Configuration sections.
Application Name has two required settings, Application Name and version. After completing the installation these settings are not editable.
Image Configuration settings specify the container image details. They define the image, tag, and when TrueNAS pulls the image from the remote repository.
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.
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.
Network Configuration settings specify network, ports, and DNS servers if the container needs a custom networking configuration.
See the Docker documentation for more details on host networking.
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.
The Portal Configuration settings configure the web UI portal for the container.
Click Add to display the web portal 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.
Settings Information
Click Add to display a block of storage configuration settings. Click again to mount an additional storage volume.
Select an option from the Type dropdown:
Host Path (Path that already exists on the system)
Use to configure a persistent host path.
| Setting | Description |
|---|---|
| Read Only | 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 |
| 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 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.
| Setting | Description |
|---|---|
| Read Only | 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 |
| 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. |
SMB/CIFS Share (Mounts a volume to a SMB share)
Use to mount an SMB share with a Docker volume.
| Setting | Description |
|---|---|
| Read Only | 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 |
| 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.
| Setting | Description |
|---|---|
| Read Only | 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 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.
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.
| Setting | Description |
|---|---|
| Name | 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. The file must include a services: key or an include: key pointing to an external Compose file that defines services. |
Click Save to initiate app deployment.
Reporting
TrueNAS has a built-in reporting engine that provides graphs and information about CPU, disk, memory, network, and other system metrics.
Configuring Reports
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.
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.
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.
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)
For more information on reporting exporter settings, see Add Reporting Exporter.
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.
Click Add to open the Add Reporting Exporter screen to configure a third party data reporting integration.
Enter a unique name for the exporter configuration in Name. When configuring multiple exporter instances, give each a distinct name.
Select the report object format from Type. At present, only GRAPHITE is available. The screen shows the exporter configuration fields.
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.
Reporting Screens
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.
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.
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.
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 System Uptime graph.
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.
Shows the ZFS ARC size graph with compressed physical ARC size.
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.
Add opens the Add Reporting Exporter screen.
Use the Add Reporting Exporter screen to configure third-party reporting integrations.
| Setting | Description |
|---|---|
| Name | 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.
| Setting | Description |
|---|---|
| Destination Ip | (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 (). |
See Adding a Reporting Exporter for guidance with configuring a Graphite exporter on TrueNAS.
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 EnterpriseEnterprise-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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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.
Update
Updating TrueNAS
TrueNAS updates system software from the System > Update screen. Updates can be installed from the update server or by uploading a local update file.
Update profiles control which TrueNAS releases the system checks for updates. Community Edition systems default to the highest profile available for the installed version. For example, a fresh install of a General release defaults to the General profile.
TrueNAS Enterprise systems ship with the Mission Critical profile set by default. Enterprise users can select General or Mission Critical only.
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 an update profile dropdown list.
Before upgrading to a new major version, update to the latest maintenance release of the current major version. See Upgrade Paths on the Software Status page for the supported paths from your current version, and the recommended versions table for guidance on which release to target.
The TrueNAS Update screen provides options to install updates from the update server or upload a local update file.
We recommend updating TrueNAS when the system is idle (no clients connected, no disk activity, etc.). The system restarts after an update. 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.
The Update Profile section on the Update screen controls which releases TrueNAS checks for updates. Change it only if you want to shift to a different release cadence.
TrueNAS has four distinct update profiles:
- Developer — Developer software with new features and bugs alike. Allows users to contribute directly to the development process.
- Early Adopter — Pre-release access to new features and functionality of TrueNAS software. Some issues might need workarounds, bug reports, or patience.
- General — Field-tested software with mature features. Few issues are expected.
- Mission Critical — Mature software that enables 24×7 operations with high availability for a very clearly defined use case. Software updates are very infrequent and based on need.
See the TrueNAS Software Status page for current recommendations by user type.
Enterprise users can select General or Mission Critical only. Community Edition users can select Developer, Early Adopter, or General.
The dropdown only shows profiles at or below the level of the currently installed version. A system on a General release profile can select General, Early Adopter, or Developer. A system on an Early Adopter release profile can select Early Adopter or Developer, but not General. Profiles above the current version level appear in the Other Profiles (Not Available) section and cannot be selected until the system runs a release at that profile level.
The Developer update profile uses a non-production train in active development. Do not use this profile unless you intend to keep the system permanently on early versions and are not storing critical data on it. Testers are encouraged to submit bug reports with debug files. For information on how to file an issue ticket, see Reporting an Issue.
To change the update profile:
- Go to System > Update.
- In the Update Profile section, select the desired profile from the Select an update profile dropdown.
- Click Apply.
- In the confirmation dialog, click Continue.
TrueNAS refreshes the update check after you apply the new profile.
If an update is available, it shows in the Update Available section on the Update screen.
Click Install Update to begin. The Save configuration settings from this machine before updating? window opens.
Select Export Password Secret Seed, then click Save Configuration.
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.
Manual update files are available from the TrueNAS Download page and Update Downloads. Use this option to install a specific build directly.
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 location from the Update File Temporary Storage Location dropdown. Select Memory Device to store the update file in system RAM during installation, or select a pool mount path to store it on disk if the system has limited memory available.
Click Apply Update to start the update process. A status window opens displaying installation progress. When complete, the system automatically Restarts.
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.
Updating TrueNAS Enterprise HA
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.
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.
If Stateful Failover is enabled in the SMB service configuration, TrueNAS blocks the update with an error. Go to System > Services, click edit Configure on the SMB row, expand Advanced Settings, and disable Stateful Failover. Re-enable it after both controllers are updated. See Enabling SMB Stateful Failover for details.
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.
- 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
sudocommands 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 Disable Password and click Save.
Finish the update by saving your updated system configuration file to a secure location and create a new boot environment to use as a restore point if it becomes necessary.
Update Screens
The Update screen provides options to update TrueNAS software from the update server or by uploading a local update file.
The Update screen shows the installed version, other installation or update options, and update profiles.
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.
This section shows the current TrueNAS release installed on the system. When autocheck is enabled, TrueNAS checks for available updates nightly. An update option appears only when the system detects an update for the selected profile. System is up to date shows when no updates are available to the profile set in Select an update profile.
If an update is available, the update version number and the Install Update button appear below the current release version. A release notes summary for the update version displays inline, followed by links to the full release notes and other resources.
Install Update starts the update process.
This section shows the Manual Update option.
The See the manual image installation guide link opens the TrueNAS Documentation Hub article with information on performing a manual upgrade.
Install opens the Manual Update screen.
Each profile changes the type of releases or updates available. Default profiles display a label identifying them on the Update screen. Each update profile and the description of software in each shows on the Update screen in the Available Profiles area.
Apply changes the profile to the selected option.
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. Available profiles differ by user type: Enterprise users see General and Mission Critical; Community Edition users see Developer, Early Adopter, and General.
Profile selections allow users to choose how conservative the software selection is based on the use case. The following table summarizes each profile and the intended users. See the TrueNAS Software Status page for current version recommendations by user type. See the Software Development Life Cycle for details on TrueNAS release stages.
| Profile | Description |
|---|---|
| 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 Enterprise users only. This profile is the most conservative release, offering mature software for 24×7 operations with high availability for a clearly defined use case. Software updates are very infrequent and based on need. |
| 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. |
The Save configuration settings from this machine before updating? window opens after clicking Install to the right of Manual Install.
Export Password Secret Seed includes password hashes used for system authentication. It does not store user login passwords. The secret seed decrypts 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, SMB users have NT hashes stored in the configuration database. When a configuration file is restored without the secret seed, encrypted fields are set to empty values. This breaks services that depend on the missing data, such as SMB via local accounts and apps.
Save Configuration downloads the system configuration file. Store the configuration file in a secure location that is regularly backed up.
The Manual Update screen opens after saving the system configuration settings.
Current Version shows the TrueNAS release version running on the system.
Choose File opens a browser window to locate the downloaded update file.
The Update File Temporary Storage Location dropdown lists Memory Device and a mount path entry for each pool available on the system. Select Memory Device to store the update file in system RAM during installation, or select a pool mount path to store it on disk if the system has limited memory available.
Apply Update starts the installation.
General Settings
TrueNAS General Settings provide options for GUI configuration, localization, NTP servers, support licensing, and email configuration.
Configuring General Settings
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 card 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.
Enterprise-licensed systems display a contextual banner based on the system support tier and contract status. Silver/Gold tier systems with proactive support not yet configured show a Set up Proactive Support banner with an Enable button. When proactive support is already active, a Manage button appears in the license info list to update contact settings. For information on configuring proactive support, see Adding a License and Proactive Support.
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.
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.
Issue Reporting Example
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.
Bug reports are created in the publicly visible TrueNAS Jira project.
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.
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.
The GUI card 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.
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.
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.
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.
For more information about what usage data is collected, see the TrueNAS Data Collection Statement.
To show real-time console messages at the bottom of the browser window, select Show Console Messages.
Localizing the TrueNAS system consists of changing the UI language and the keyboard layout to support the selected language and setting the time zone to match where the TrueNAS server is located. To set date and time formats, go to the top toolbar Settings > Preferences screen.
To change the Web UI on-screen language and set the keyboard to work with the selected language, click Settings on the Localization card 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.
The Email card displays information about the 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.
Adding a License and Proactive Support
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.
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.
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.
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.
Select one of the three Send Mail Method options:
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.
To set up SMTP service as the system email send method, you need the outgoing mail server and port number for the email address.
Select the SMTP radio button.
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.
To set up the system email using Gmail OAuth, use the TrueNAS web UI to log in to your Gmail account.
Select GMail OAuth.
Click on Log In To GMail. The GMail Authorization window opens.
Click Proceed to open the Sign in with Google window.
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.
Click Send Test Email to verify you receive an email.
Click Save.
To set up the system email using Outlook OAuth, use the TrueNAS web UI to log in to your Outlook account.
Select Outlook OAuth.
Enter the email address that sends the alerts in From Email and the name that appears before the address in From Name.
Click Log In To Outlook. The Outlook Authorization window opens.
Click Proceed to open the Sign in window.
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.
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 Alerts icon at the top right of the screen to open the Alerts panel. Click on the settings icon and then on Alert Settings.
Locate Email under Alert Services, select the 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.
General Settings Screen
The General Settings screen has four cards that show current general system settings and include buttons for related actions and configuration options. The cards are:
Community systems show the same cards, but are not eligible for Enterprise support options or licenses. Enterprise systems show an image of the system model.
The Support card shows system information and provides access to support resources and actions. All systems show three buttons in the card header:
- File Ticket opens a feedback/report issue window where users can provide feedback or report an issue and save/attach a system debug file.
- Save Debug starts downloading a system debug file to the local machine.
- Add License (or Update License after a license is applied) opens the License screen. Requires Full Admin role.
The Support card for TrueNAS Community Edition shows a banner with a link to the TrueNAS forums for community support, followed by system information including the OS version, system product, CPU model (if detected), memory, and system serial number (if configured).
A links row at the bottom of the card provides quick access to Documentation, Forums, and Licensing information.
The Support card on the General Settings screen for Enterprise systems displays license details including contract type, expiration date, model, system serial, licensed serials, features, and any additional hardware. Licensed systems with recognized hardware display a product image at the top of the card.
The This is a production system toggle, which shows only on TrueNAS Enterprise systems, appears alongside the Model field in the license info list. Enabling it opens the Update Production Status dialog.
The Support card displays a contextual banner depending on the system’s license tier and support configuration:
- Contract expiring soon — Shows when an active support contract expires within 14 days. Displays the number of days remaining and the expiration date, with a Contact Us link to renew.
- Set up Proactive Support — Shows for Silver/Gold tier systems where proactive support is available but not yet enabled. Click Enable to open the Proactive Support configuration screen.
- Need help? Looking for support? (Bronze tier) — Shows for systems where proactive support is not included. Provides an Explore your options link to review available support plans.
When proactive support is active, the license info list includes a Proactive Support: Enabled row with a Manage button to update contact configuration.
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.
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.
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 experience 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 on our forum link opens the TrueNAS Community forum.
Submit sends the report to TrueNAS.
The License screen opens after clicking either Add License or Update License on the Support card on the General Settings screen. It allows pasting a copy of your license into the form and saving it.
Reload Now reloads the page.
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 card 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.
Silver/Gold coverage customers can enable proactive support. This feature automatically emails TrueNAS when certain conditions occur in a TrueNAS system.
Click Enable in the Set up Proactive Support banner, or Manage in the proactive support row (when already enabled), to open the proactive support configuration screen.
Primary Contact and Secondary Contact fields specify the customer name, title, and contact information.
Enable TrueNAS Proactive Support and Save notifies the TrueNAS team that the system is configured for proactive support.
The GUI Settings screen shows configuration settings for the TrueNAS web interface.
The Localization card shows the current time zone and console keyboard map settings for the TrueNAS system. Provides access to a configuration screen to customize settings.
Settings opens the Localization Settings configuration screen.
The Email card 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:
- SMTP shows standard SMTP configuration settings.
- GMail OAuth shows the Gmail configuration options.
- Outlook OAuth shows Outlook configuration options.
The Email Options screen for the SMTP option shows standard email configuration settings.
Send Test Mail generates a test email to confirm that the system email settings entered work correctly.
Save stores the email configuration and closes the Email Options screen.
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
TrueNAS Advanced Settings provide configuration options for console, scheduled tasks, hardware resources, security, and system logging.
Configuring 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), NVIDIA drivers, system access sessions, allowed IP addresses, audit logging, and global two-factor authentication. Enterprise systems with SED drives and the appropriate license also see the self-encrypting drive option. Enterprise systems also see the security options (STIG and FIPS).
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
Enterprise-licensed systems include configuration options for STIG and FIPS security, and failover when the system is a High Availability system.
The Audit card 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.
Click Configure to open the Audit configuration screen and to manage storage and retention policies for audit logs.
Use Add on the Tunable card to add a tunable that configures a kernel module parameter at runtime.
The Add Tunable screen shows the settings.
Select the tunable type from the Type dropdown list. There are three options:
- SYSCTL - Linux kernel parameters (called sysctl variables) that tune low-level kernel behavior across networking, memory management, virtual memory, file descriptors, security hardening and more that affect the entire system. Sysctl tunables configure kernel module parameters while the system runs and generally take effect immediately. Best used for general system performance, network stack, memory pressure, security hardening (e.g., against SYN floods:
net.ipv4.tcp_syncookies=1). Variables persist across system remboots if set in config files.Enter a sysctl loader value in Value. - UDEV - UDEV rules, which are dynamic device manager configurations that run with when the kernel detects hardware events (e.g, disk plugged in, USB device attached, block device created). Variables are applied per device or per subsystem. They are ideal for hardware-specific tuning, especially disks/SSDs in ZFS pools e.g., forcing consistent I/O scheduler, readahead, or queue depth on pool drives to avoid defaults that hurt ZFS performance.They are permanent when the rule file exists, and rules re-apply automatically on device add/remove operations.
- ZFS - OpenZFS module parameters for the ZFS kernel module on Linux. They control ZFS-specific behavior like ARC caching, compression, I/O scheduling, prefetching, recordsize limits and more. Use for fine-tuning ZFS performance, memory usage (AREC/L2ARC), compression, dedup, scrub/resilver behavior, and I/O patterns. They only apply to ZFS filesystem/modules. Runtime changes are lost on reboot or module reloads.
Enter the variable name in Variable, the value for the variable in Value, and a short description in Description. See examples below for each tunable type.
Type: SYSCTL
Variable: net.core.somaxconn
Value: 1024
Description: Increase max pending connections for better network handling under load.
Type: UDEV
Variable: ACTION==“add|change”, KERNEL==“sd[a-z]”
Value:1
Description: Set I/O scheduler to deadline on all rotational disks.
Type: ZFS
Variable: zfs_arc_max
Value: 17179869184 (that is 16 GiB in bytes; calculate as desired RAM cap x 10243)
Description: Cap ZFS ARC at 16 GiB to leave headroom for apps/VMs.
Select Enabled. Disabling the tunable does not delete the variable.
Click Save.
The NTP Servers card 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.
Storage card 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.
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.
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 priority, clear the checkbox and click Save.
The Replication card 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.
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.
The Access widget shows a list of all active sessions, including the current logged-in user session and the time it started.
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. It opens the Terminate session dialog. Click Confirm then Continue to end other sessions. This does not terminate the currently logged-in administration user session.
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.
The Start session time shows the configured token duration for the current session (default is 300 seconds, or 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.
To change settings, click Configure to open the Access Settings screen, where you can add a login banner.
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.
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.
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.
The NVIDIA Drivers widget allows you to install or remove NVIDIA GPU drivers on your system. NVIDIA GPU support is required for containers that use NVIDIA GPUs for graphics acceleration or computation.
Click Configure to open the NVIDIA Drivers configuration screen.
To install NVIDIA drivers:
- Select Install NVIDIA Drivers.
- Click Save.
Installing NVIDIA drivers requires the system to use the production kernel. If Enable Debug Kernel is selected, NVIDIA driver installation fails. Disable the debug kernel before installing NVIDIA drivers.
After installation completes, NVIDIA GPU devices become available for assignment to containers. To verify installation, check that your GPU devices appear in the container GPU device selection list.
To uninstall the drivers:
- Deselect Install NVIDIA Drivers.
- Click Save.
Containers using NVIDIA GPUs cannot start after driver removal.
See NVIDIA Drivers Card in the UI Reference for detailed field descriptions.
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.
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 card.
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.
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.
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.
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.
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.
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.
The Save Configuration dialog opens.
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.
The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS configuration file.
If you do not save the secret seed by downloading the system config file, various services can break due to missing information. Without the secret seed, encrypted fields are set to empty values. For example, SMB via local accounts and apps. Always select the option to save the secret seed when downloading the system config file!
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.
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.
TrueCommand provides an easy solution for users who want to schedule an automatic remote backup of the system configuration file:
- Set up TrueCommand.
- Add their TrueNAS system.
- Create and schedule the configuration file backup.
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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 Cron Jobs
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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.
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 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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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.
Managing Init/Shutdown Scripts
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before creating and executing script 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.
Click Add to open the Add Init/Shutdown Script configuration screen.
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 runs using dash(1).
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.
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.
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.
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later) that requires an active SED license. 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.
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive card.
Click Configure to open the Self-Encrypting Drive configuration screen.
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!
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 for a confirmed SED to expand the row. Click Edit to open the Edit Disk screen.
Enter the password in the SED Password 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.
Select Clear SED Password to clear the existing password, and click Save. Reopen the Edit Disk screen to enter and save a new password.
Repeat this process for each SED and any SEDs added to the system in the future.
See Managing Self-Encrypting Drives (SED) for more information.
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Isolated GPU Device(s) widget on the System > Advanced Settings screen shows configured isolated GPU device(s).
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.
Select the GPU device(s) to isolate from the dropdown list.
Click Save.
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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!
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.
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.
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.
Select Enable Two Factor Authentication Globally, then click Save.
If you want to enable two-factor authentication for SSH logins, select Enable Two Factor Authentication for SSH before you click Save. SSH 2FA only applies to users who configured a 2FA secret and are using password-based authentication.
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.
Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure. Clear the Enable Two Factor Authentication Globally checkbox and click Save.
If you want to enable 2FA again, go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure.
Select Enable Two Factor Authentication Globally, then click Save. To change the system-generated Secret, go to Credentials > Two Factor Auth and click Renew 2FA Secret.
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 going to Credentials > Two Factor Auth, or by clicking the Settings icon on the top toolbar and selecting Two-Factor Authentication (this option only appears when Global 2FA is enabled).
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:
Go to Credentials > Two Factor Auth to open the Two Factor Auth screen.
If Global 2FA is not enabled, the screen displays a warning message. You can still configure your personal 2FA settings, but they do not take effect until a system administrator enables Global 2FA.Click Configure 2FA Secret to view the QR code and setup options. The screen displays the unique key with a copy to clipboard button so you can configure 2FA using a non-camera method if necessary.
Scan the QR code using your authenticator app or manually enter the unique key. To generate a new QR code, click Renew 2FA Secret.
Your 2FA is now configured. You need to enter codes from your authenticator app when logging in.
If you prefer not to set up 2FA at this time, see Skipping 2FA Setup.
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.
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 going to Credentials > Two Factor Auth.
The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.
Users can remove their personal 2FA configuration without disabling global 2FA:
- Go to Credentials > Two Factor Auth.
- 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
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.
For detailed step-by-step instructions, see Managing Users - Clearing Two-Factor Authentication for a User.
The Clear Two-Factor Authentication button only appears for users who have 2FA configured. If you do not see the button, the user has not set up 2FA.
Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.
The login screen adds another field for the randomized authenticator code. If this field is not immediately visible, try refreshing the browser.
Enter the code from the mobile device (without the space) in the login window and use the admin username and password.
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.
Confirm that you set Enable Two Factor Authentication for SSH in System > Advanced Settings > Global Two Factor Authentication.
Ensure the user configured a 2FA secret (see Enabling 2FA above).
Go to Credentials > Users and edit the desired user account. Select SSH password login enabled, then click Save.
Go to System Settings > Services and click the SSH Start 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.
Users without a configured 2FA secret can use password-based SSH without providing a 2FA code, even when global SSH 2FA is enabled.
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.
install-dev-toolsis 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.
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.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any 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.
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.
Enterprise-licensed systems include configuration options for STIG and FIPS security, and failover when the system is a High Availability system.
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 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.
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.
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.
The Console card 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.
Configure opens the Console configuration screen.
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.
The Syslog card 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.
Configure opens the Syslog configuration screen.
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.
The Audit card 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.
Click Configure to open the Audit configuration screen and manage storage and retention policies
The Kernel card shows options for configuring the Linux kernel installed with TrueNAS.
The Cron Jobs card 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.
Add opens the Add Cron Job configuration screen.
Click on any job listed in the card 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.
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.
The Init/Shutdown Scripts card displays No Init/Shutdown Scripts configured until you add either a command or script; then the card lists the scripts configured on the system.
Add opens the Add Init/Shutdown Script configuration screen. Any script listed is a link that opens the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
Init/Shutdown Scripts lets users schedule commands or scripts to run at system startup or shutdown.
The Tunable card shows the existing sysctl settings on the system.
Add to add a tunable that configures a kernel module parameter at runtime.
The Add Tunable configuration screen allows setting up tunables to configure Linux kernel parameters at runtime, UDEV rules for detected hardware, or ZFS module parameters for the ZFS kernel module on Linux.
The NTP Servers card 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 card opens the Add NTP Server screen.
Storage card 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.
It also shows the resilivering priority setting.
Configure opens the Storage Settings configuration screen.
The Storage Settings screen shows the current system dataset and resilvering priority.
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.
The Replication card 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.
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.
The Access widget shows a list of all active sessions, including the current logged-in user session and the time it started.
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. It opens the Terminate session dialog. Click Confirm then Continue to end other sessions. This does not terminate the currently logged-in administration user session.
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.
The Start session time shows the configured token duration for the current session (default is 300 seconds, or 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.
To change settings, click Configure to open the Access Settings screen, where you can add a login banner.
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.
Logout Dialog
Extend Session resets the token counter. If the button is not clicked, TrueNAS terminates the session automatically and returns to the login screen.
Configure opens the Access Settings screen.
The Access Settings screen allows users to configure a login banner. Login Banner sets a text message that the system shows before the TrueNAS login splash screen displays. Continue on the banner screen, closes the screen before it 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.
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.
The Allowed IP Addresses card 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.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later) that requires an active SED license. 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.
The Self-Encrypting Drive (SED) card shows when the system has self-encrypting drives and is licensed for SED.
Configure opens the Self-Encrypting Drive configuration screen.
The Self-Encrypting Drive configuration screen allows users to set the ATA security user and create a SED global password.
The Isolated GPU Device(s) card displays any isolated graphics processing unit (GPU) device(s) configured on your system.
Configure opens the Isolated GPU PCI Ids screen, which allows users to isolate additional GPU devices.
The Isolate GPU PCI IDs card 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.
The NVIDIA Drivers card shows the current NVIDIA driver installation status. NVIDIA GPU support is required before containers or VMs can use NVIDIA GPUs for graphics acceleration or computation.
Configure opens the NVIDIA Drivers configuration screen.
| Setting | Description |
|---|---|
| Install NVIDIA Drivers | Allows installing NVIDIA GPU drivers on the system. When disabled, allows removing installed drivers. Requires the system to use the production kernel — if Enable Debug Kernel is selected in the Kernel Card, driver installation fails. Installing requires you to disable the debug kernel before installing NVIDIA drivers. |
After installation completes, NVIDIA GPU devices become available for assignment to containers and VMs. Containers using NVIDIA GPUs cannot start after driver removal.
The Global Two Factor Authentication card shows the status of global two-factor authentication, the tolerance window, and the status of two-factor authentication for SSH sessions. It provides access to the configuration screen that allows you to set up two-factor authentication (2FA) for your system.
The card displays the following information:
| Field | Description |
|---|---|
| Global 2FA | Shows whether Global 2FA is enabled or disabled. |
| Tolerance Window | Shows the current tolerance window value. |
| Two Factor Authentication for SSH | Shows whether 2FA for SSH is enabled or disabled. |
Configure opens the Global Two Factor Authentication configuration screen.
The System Security card 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.
Settings opens the System Security configuration screen.
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. |
The Failover card 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.
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.
| Setting | Description |
|---|---|
| Enable Automatic Failover | 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 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
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.
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 - Shows 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.
Boot environments do not share all system information. TrueNAS carries over the central database and configuration elements into a new environment during an update, but other state changes made in one environment do not appear in another.
Changes in a new boot environment do not exist in older environments. Similarly, changes made while booted into an old environment do not propagate forward into new boot environments.
The isolation among different boot environments means that frequent switching between environments can lead to configuration divergence and missing audit information. Because of this, we recommend that you only revert a boot pool upgrade if the new version introduces a problem or to recover from a broken configuration if the system console or IPMI is unavailable.
TrueNAS automatically saves the previous release during upgrades and keeps the last two boot environments by default. TrueNAS recommends keeping three to four boot environments for production systems.
Industry best practices recommend keeping the current running release and one to two previous stable releases for quick rollback if necessary. Remove older boot environments unless there is a specific rollback reason.
Consider the following when deciding whether to remove boot environments:
- Keep older releases for 30 to 90 days until you have confidence in the current release.
- Remove older releases when boot pool space is limited (<20% free remaining). Each boot environment typically uses 2-5GB. Consider setting up a system alert when boot pool capacity reaches 70-80%.
- Remove releases that no longer receive security updates. Keep the most recent version with security patches.
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.
Click Confirm, and then click Activate.
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.
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 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.
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.
The boot environment action list removes the Keep option and adds Unkeep.
This makes the boot environment subject to automatic deletion if the TrueNAS updater needs space for an update.
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.
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
By default, TrueNAS creates a new boot environment when you update or reinstall the system, and changes made in a previous boot environment do not automatically appear in a new environment after updates or reinstallation. 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 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
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.
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.
Click the to open the Actions options. Click Replace, select the device from the Member Disk dropdown, and then click Save.
Click the to open the Actions options for a device.
Click Attach, then select a device from the Member Disk dropdown.
Select Use all disk space to use the entire capacity of the new device.
Click Save.
You can initiate a manual data integrity check (scrub) of the operating system device at any time.
On the System > Boot screen, click Scrub Boot Pool to open the Scrub dialog.
Click Confirm and then Start Scrub.
Boot Screens
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.
Boot environments do not share all configuration information. Updates create a new environment and carry forward core configuration, but other state changes do not propagate across 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. |
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 vertical ellipsis next to a device displays two options, Attach or Replace.
Each boot pool environment listed expands to show the disk name where the environment resides. The shows two options, Replace and Attach.
Replace opens the Replace window.
Attach opens the Attach window.
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.
Use all disk space enables the specified disk to use the entire capacity of that new device.
Save makes the change and closes the window.
The Replace window settings, accessed from the Boot Status screen, specify a replacement device for the current boot environment device.
Member Disk shows a dropdown list of devices to select.
Save makes the change and closes the window.
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.
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.
Delete opens the Delete window.
Services
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.
Configuring FTP Service
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.
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.
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.
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.
Configuring NFS Service
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.
Configuring SMB Service
The Services > SMB screen displays after going to the Shares screen, finding the Windows (SMB) Shares section, and clicking + Config Service. Alternatively, you can go to System > Services and click the edit icon for the 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 from these services when unconfigured with enabled Active Directory or LDAP active.
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.
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.
Microsoft is deprecating NTLM network authentication in a staged process. Windows 11 version 24H2, Windows Server 2025, and later versions have removed NTLMv1 network authentication. See Upcoming changes to NTLMv1 in Windows 11 version 24H2 and Windows Server 2025 for more information. Microsoft also plans to disable all NTLM authentication by default in a future major Windows release. See Advancing Windows Security: Disabling NTLM by Default for more information.
Enterprise and Active Directory deployments are not affected by either change. TrueNAS SMB deployments that use Active Directory rely on Kerberos authentication and are unaffected by these changes. Active Directory remains the recommended configuration for business and enterprise SMB deployments.
Home and workgroup deployments that use local TrueNAS accounts are affected as follows:
- The NTLMv1 Auth setting in the TrueNAS SMB service has no effect for Windows 11 (version 24H2 and later) or Windows Server 2025 clients, which no longer send NTLMv1. This setting might still be relevant for legacy or non-Windows devices that use NTLMv1.
- Windows clients using NTLMv2 (standard for workgroup and local account SMB access) currently connect without issue. These clients lose SMB access when Microsoft enforces the full NTLM disable-by-default in a future Windows release. macOS, Linux, older Windows versions, and network-attached devices such as printers and MFPs are not affected. When that change takes effect, re-enabling NTLM in Windows security policy is a temporary workaround.
TrueNAS plans to add improved authentication support for home and workgroup users in a future release, dependent on upstream development in Samba.
Enter any notes about the service configuration in Description.
For more advanced settings, see SMB Services Screen.
Click Save.
Start the SMB service.
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.
For more information on Windows SMB-client side transport encryption, see Windows SMB Signing Policies.
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.
Configure filtering to audit only necessary operations.
Use Watch List to specify which groups should have their SMB operations audited. Use Ignore List to exclude specific groups from auditing.
- 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.
Configuring 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, you may need to 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.
Configuring SNMP Service
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.
See SNMP Service Screen for setting information.
Port UDP 161 listens for SNMP requests when starting the SNMP service.
Click to view or download a static copy of the TrueNAS 27 MIB file.
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
Example (replace mytruenas.example.com with your system IP address or hostname):
PS C:\Users\tnuser> scp truenas_admin@mytruenas.example.com:/usr/local/share/snmp/mibs/* .\Downloads\
truenas_admin@mytruenas.example.com's password:
TRUENAS-MIB.txt 100% 11KB 112.0KB/s 00:00
PS C:\Users\tnuser>
Configuring SSH Service
The SSH service lets users connect to TrueNAS with the Secure SHell Transport Layer Protocol. When using TrueNAS as an SSH server, the users in the network must use SSH client software to transfer files with SSH.
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.
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.
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.
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.
Select Allow Password Authentication.
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 ValidationUsers 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.
When global 2FA is enabled with the SSH 2FA option, two-factor authentication applies only to users who meet all of the following conditions:
- The user configured a 2FA secret
- The user is using password-based SSH authentication (not key-based)
- Both global 2FA and SSH 2FA options are enabled in System > Advanced Settings
Users without a configured 2FA secret can use password-based SSH without providing a 2FA code, even when global SSH 2FA is enabled. Key-based SSH authentication is not affected by 2FA settings.
See Managing Global 2FA for more information.
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.
Configuring UPS Service
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.
Report UPS bugs and feature requests to the NUT project.
Connect the TrueNAS system to the UPS device. To configure the UPS service, go to System > Services, finding UPS, and click edit.
See UPS Service Screen for details on the UPS service settings.
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.
pollinterval = 10.Services Screens
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 Configure icon opens the service configuration screen.
The NFS service row has one additional View Sessions link that opens the NFS Sessions screen.
The SMB service row has two additional links:
- View Logs opens the Audit screen.
- View Sessions opens the SMB Status screen.
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 start or 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.
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.
To configure FTP, go to System > Services and find FTP, then click edit.
| Settings | Description |
|---|---|
| Port | Enter the port the FTP service listens on. |
| Clients | Enter the maximum number of simultaneous clients. |
| Connections | 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. |
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 | When selected, restricts all local users to their home directory regardless of group membership. This option increases security risk — chroot jails can be escaped if users have write access to their home directory, potentially exposing the broader filesystem. 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). Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security. |
| 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 |
| 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. |
| Auxiliary Parameters | Used to add additional proftpd(8) parameters. |
Bandwidth settings specify the space you want to allocate for local and anonymous user uploads and downloads.
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.
- dash (
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.
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.
There are a few different approaches for configuring and managing iSCSI-shared data:
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.
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. |
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:
- View Sessions opens the NFS Sessions screen.
- Configure icon opens the NFS Service screen.
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.
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.
| Setting | Description |
|---|---|
| Bind IP Addresses | Select IP addresses to listen to for NFS requests. Leave empty for NFS to listen to all available addresses. You must configure static IPs on the interface for them to appear on the dropdown list. |
| Calculate number of threads dynamically | Automatically sets the number of threads used by the kernel NFS server. |
| Specify number of threads manually | Shows after disabling Calculate number of threads dynamically. Enter an optimal number of threads used by the kernel NFS server. |
| Setting | Description |
|---|---|
| Enabled Protocols | Select NFSv3, NFSv4, or both. If NFSv4 is selected, NFSv3 ownership model for NFSv4 clears, allowing you to select or leave it clear. |
| NFSv4 DNS Domain | Select to use the value to override the default DNS domain name ofr NFSv4. Speicifies the domain idmapd.conf setting. |
| NFSv3 ownership model for NFSv4 | Becomes selectable after selecting NFSv4. Select when you need NFSv4 ACL support without requiring the client and the server to sync users and groups. Selecting this deactivates the Manage Groups Server-side option. |
| Require Kerberos for NFSv4 | Select to force NFS shares to fail if the Kerberos ticket is unavailable. |
| Setting | Description |
|---|---|
| mountd(8) bind port | Enter a port to bind mountd(8). |
| rpc.statd(8) bind port | Enter a port to bind rpc.statd(8). |
| rpc.lockd(8) bind port | Enter a port to bind rpc.lockd(8). |
| Setting | Description |
|---|---|
| Enable NFS over RDMA | Select to improve NFS performance and reduce CPU overhead. This setting requires an Enterprise licensed system with an RDMA capable NIC. |
| Allow non-root mount | Only select if required by the NFS client to allow serving non-root mount requests. |
| Manage Groups Server-side | This option allows 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. 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:
- View Logs opens the Audit screen.
- View Sessions opens the SMB Status screen.
- Configure icon opens the SMB Service screen showing the Basic Settings by default.
The SMB service screen displays setting options to configure TrueNAS SMB service settings to fit your use case.
Click Save or Cancel to close the configuration screen and return to the Services screen.
| 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. |
Microsoft is deprecating NTLM network authentication in a staged process. Windows 11 version 24H2, Windows Server 2025, and later versions have removed NTLMv1 network authentication. See Upcoming changes to NTLMv1 in Windows 11 version 24H2 and Windows Server 2025 for more information. Microsoft also plans to disable all NTLM authentication by default in a future major Windows release. See Advancing Windows Security: Disabling NTLM by Default for more information.
Enterprise and Active Directory deployments are not affected by either change. TrueNAS SMB deployments that use Active Directory rely on Kerberos authentication and are unaffected by these changes. Active Directory remains the recommended configuration for business and enterprise SMB deployments.
Home and workgroup deployments that use local TrueNAS accounts are affected as follows:
- The NTLMv1 Auth setting in the TrueNAS SMB service has no effect for Windows 11 (version 24H2 and later) or Windows Server 2025 clients, which no longer send NTLMv1. This setting might still be relevant for legacy or non-Windows devices that use NTLMv1.
- Windows clients using NTLMv2 (standard for workgroup and local account SMB access) currently connect without issue. These clients lose SMB access when Microsoft enforces the full NTLM disable-by-default in a future Windows release. macOS, Linux, older Windows versions, and network-attached devices such as printers and MFPs are not affected. When that change takes effect, re-enabling NTLM in Windows security policy is a temporary workaround.
TrueNAS plans to add improved authentication support for home and workgroup users in a future release, dependent on upstream development in Samba.
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.
| Setting | Description |
|---|---|
| UNIX Charset | 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:enable_smb1) |
| 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 |
| Local Master | Selected by default and determines if the system participates in a browser election. Leave cleared when the network contains an Active Directory or LDAP 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 link aggregation. |
| Enable Search (Spotlight) | Allows macOS clients to use Spotlight to search for file contents on SMB shares. Enables the TrueSearch indexing service, which indexes all enabled, non-encrypted SMB shares. Requires an Enterprise license or TrueNAS Connect configuration. When the setting is unavailable, a notice displays with a link to configure TrueNAS Connect. Encrypted datasets are not indexed. |
| Stateful Failover | Available in High Availability (HA) configurations with an Enterprise license. Maintains SMB session state across HA failover events. SMB clients recover existing connections without re-authentication after a controller failover. This setting is incompatible with Enable SMB1 support and with shares using the Multi-Protocol Share or Legacy Share purpose. |
| Setting | Description |
|---|---|
| Administrators Group | 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.
| 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. |
| 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. |
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.
The Basic Settings options display by default when you edit the SSH service.
| Setting | Description |
|---|---|
| TCP Port | 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. |
Advanced Settings include the General Options settings. Advanced settings specify bind interfaces, SFTP settings, ciphers and any additional parameters you want to use.
| Setting | Description |
|---|---|
| Bind Interfaces | 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.
Report UPS bugs and feature requests to the NUT project.
Click edit to open the Services > UPS configuration screen.
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
General Options setting specify required UPS mode and connection. These settings change based on the Master or Slave UPS mode setting.
| Setting | Description |
|---|---|
| Identifier | 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 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 specify the UPS shutdown mode, command, and timer for the UPS service.
| Setting | Description |
|---|---|
| Shutdown Mode | 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 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. |
| Description | Enter a description for this service. |
| Auxiliary Parameters (ups.conf) | Enter any extra options from ups.conf. |
| Auxiliary Parameters (upsd.conf) | Enter any extra options from upsd.conf. |
WebShare Service Screen
The WebShare service screen displays settings to configure the WebShare service.
| Icon | Description |
|---|---|
| Enable TrueSearch | Enables TrueSearch file indexing and search functionality. When enabled, the active WebShares are indexed for fast file searching. |
| Passkey | Configures passkey authentication for WebShare. Options are: Required - Users must use passkeys. Enabled - Users see passkeys as an option. Disabled - Turns off passkey authentication. |
Shell
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 Size remove 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.
This section provides keyboard navigation shortcuts you can use in Shell.
| Action | Keyboard/Command | Description |
|---|---|---|
| Scroll up | Up arrow | Scroll up through previous commands. |
| Scroll down | Down arrow | 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. |
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.
Shell Screen
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 Size remove 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 icon, then click the 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.
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.
| 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 Splunk On-Call. |
| 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.
Use the Edit Alert Service screen to modify settings for a service. Select the icon for the service to display the Edit Alert Service screen.
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Settings
| Setting | Description |
|---|---|
| AWS Region | Enter the AWS account region. |
| ARN | Topic Amazon Resource Name (ARN) for publishing. For example, arn:aws:sns:us-west-2:111122223333:MyTopic. |
| Key ID | Enter the access key ID for the linked AWS account. |
| Secret Key | Secret access key for the linked AWS account. |
Click here for more information
Select E-Mail from the Type dropdown list to display email authentication settings.
Settings
| Setting | Description |
|---|---|
| Override Admin Email | Sets an email address to override the default email address for the admin account. When left blank, the email address for the admin account is used. |
Click here for more information
Select InfluxDB from the Type dropdown list to display InfluxDB authentication settings.
Settings
| Setting | Description |
|---|---|
| Host | Enter the InfluxDB host name. |
| Username | Enter the user name for this service. |
| Password | Enter the password for the user on this service |
| Database | Enter the name of the InfluxDB database. |
| Series | Enter the InfluxDB time series name for collected points. |
Click here for more information
Select Mattermost from the Type dropdown list to display Mattermost authentication settings.
Settings
| Setting | Description |
|---|---|
| Webhook URL | Enter or past the incoming webhook URL associated with this service. |
| Username | Enter the Mattermost user name. |
| Channel | Enter the name of the channel to receive notifications. Entering a channel overrides the default channel in the incoming webhook settings. |
| Icon URL | Enter the icon file to use as the profile picture for new messages. For example, https://mattermost.org/wp-content/uploads/2016/04/icon.png. Requires configuring Mattermost to override profile picture icons. |
Click here for more information
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
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. |
| API URL | Leave empty for default (OpsGenie API). |
Click here for more information
Select PagerDuty from the Type dropdown list to display PagerDuty authentication settings.
Settings
| Setting | Description |
|---|---|
| Service Key | Enter or paste the integration/service key for this system to access the PagerDuty API. |
| Client Name | Enter the PagerDuty client name. |
Click here for more information
Select Slack from the Type dropdown list to display Slack authentication settings.
Settings
| Setting | Description |
|---|---|
| Webhook URL | Paste the incoming webhook URL associated with this service. |
Click here for more information
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
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?. |
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Settings
| Setting | Description |
|---|---|
| Bot API Token | Enter the Telegram Bot API Token How to create a Telegram Bot. |
| List of chat IDs | 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. |
Click here for more information
Select Splunk On-Call from the Type dropdown list to display Splunk On-Call authentication settings.
Settings
| Setting | Description |
|---|---|
| API Key | Enter or paste the Splunk On-Call API key. |
| Routing Key | Enter or past the Splunk On-Call routing key. |
Use the Category dropdown list to display alert settings for each category.
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Audit alert settings apply to the audit and verification services on your TrueNAS system.
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Directory Service alert settings apply to the directory services configured on your TrueNAS.
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only display 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 alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.
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.Click here for more information
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) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Network alert settings apply to network interfaces configured on your TrueNAS.
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
You can customize alert settings for when a deprecated service configuration is detected or a deprecated service is running, and when Fibre Channel HBAs are added or replaced. You can also customize alerts for iSCSI issues: IP addresses bound to an iSCSI portal are not found, iSCSI authorized access has invalid characters or leading/trailing whitespace, and iSCSI discovery authorization is set to global, has multiple mutual CHAP, or is merged. For NFS, you can customize alerts for when NFS services cannot bind to specific IP addresses using 0.0.0.0, an NFS export entry is blocked, host or network lists are excessively long, share references to hosts cannot be resolved, and NFS start is blocked by entries in /etc/exports.d. For SMB, you can customize alerts for when NTLMv1 authentication is attempted in the last 24 hours, SMB1 connections to the TrueNAS server are performed in the last 24 hours, an SMB share audit configuration contains invalid groups, an SMB share path has unresolvable issues, SMB shares use an incorrect recordsize value for Veeam Fast Clone, and an SMB user is missing a required password hash. You can also set alerts for when a share is unavailable because it uses a locked dataset.Click here for more information
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
You can customize alert settings for when a dataset exceeds standard or critical quotas, a pool has new available feature flags, pool space usage exceeds 85, 90, or 95 percent, and pool status is not healthy. You can also change alert settings for when a scrub pauses, too many snapshots exist on the system or on a specific dataset.Click here for more information
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.
You can customize alert settings for when an API key is revoked, API or SSH login failures occur, the admin user is overridden, administrator account activity is detected, the boot pool is unhealthy, core files are detected, and the running system version does not match the selected update profile. You can also change alert settings for when a failover event or fencing causes a system reboot, a Gmail OAuth configuration is discarded, NTP health checks fail, a GPU configuration update requires a reboot, the system is not ready for Kdump, and system mocking endpoints are in use. For TrueCommand, you can customize alerts for when an API key is pending confirmation or disabled by iX Portal, and when the TrueCommand container or service fails a scheduled health check. You can also set alerts for when unencrypted datasets are detected within encrypted datasets and when an update is available.Click here for more information
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub, and snapshot tasks scheduled on your TrueNAS.
You can customize alert settings for when cloud backup or cloud sync tasks fail, a cloud provider is removed, VMWare snapshot creation or deletion fails, VMWare login fails, replication fails or succeeds, rsync tasks fail or succeed, a scrub fails to start or starts, snapshot tasks fail, and when a task is unavailable because it uses a locked dataset.Click here for more information
TrueNAS Connect Service alert settings apply to the TrueNAS Connect service on your TrueNAS system.
UPS alert settings apply to a UPS connected to your TrueNAS.
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 |
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.
Audit
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).
TrueNAS includes a manual page with more information on the VFS auditing functions.
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 include authentication, method call, and sudo accept/reject events.
SMB events are omitted by default from the System > Audit screen. To view these audit results, go to System > Services and click receipt_long Audit 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.
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).
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 Edit 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 Audit 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.
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.
Configure filtering to audit only necessary operations.
Use Watch List to specify which groups should have their SMB operations audited. Use Ignore List to exclude specific groups from auditing.
- 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.
Configuring 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, you may need to 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.
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.
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.
Audit Screen
TrueNAS auditing logs record all operations performed by a session, user, or service (SMB, middleware).
The Audit screen lists all session or user events, facilitating comprehensive monitoring.
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.
TrueNAS includes a manual page with more information on the VFS auditing functions.
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.
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.
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.
Those interested in purchasing compatible TrueNAS appliances can click here to compare options or get a request a quote from a product specialist.
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.
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 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 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.
Click on a disk to show drive details and stats.
Larger TrueNAS Enterprise system images include a front and rear view of the chassis. The screen opens showing the front view by default.
Rear changes the image to the rear view of the system chassis. Front switches to the front view.
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.
API Reference
The TrueNAS REST API was deprecated in TrueNAS 25.04 and is removed in TrueNAS 26. Systems still using the REST API must migrate to the WebSocket API before upgrading.
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.
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.
TrueNAS API documentation is available in several ways:
In the web interface, click laptop My API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen. Click API Docs 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.
User-linked API access keys allow administrators to configure per-user access to the TrueNAS API. Keys are revocable and expire automatically on a preset date when configured to do so.
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
User-linked API keys allow for better integration of TrueNAS into third-party solutions. Use this as a reference for projects that require direct TrueNAS integration.
Always back up and secure keys. TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware. API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account. A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys. TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport. A revoked API key cannot be used until it is reset. Resetting generates a new key-string.
Remember to update clients to use the new key.
See Managing API Keys for more information.
TrueNAS Security Reports
See the TrueNAS Security Hub to get the latest responses to TrueNAS-related security advisories.
TrueNAS Security Best Practices are also available.