TrueNAS 26 (Early)

Early Release Documentation - TrueNAS 26

TrueNAS 26 brings many new features and improvements to the TrueNAS experience.

Annual Release Cadence and Simplified Versioning

TrueNAS 26 introduces an annual release cadence with simplified version numbering. Instead of fish-themed code names and multi-digit version strings, releases now use straightforward numbers like “26.1”. TrueNAS 26 receives feature packs, security updates, and hotfixes throughout the year, providing more predictable upgrade cycles and extended testing periods for both the engineering team and end users.

WebShare with TrueSearch

WebShare provides browser-based file access without requiring SMB or NFS client mounting on user systems. Users can browse, upload, download, and manage files directly from a web browser, with support for folder creation, filtering, snapshot timeline viewing, shareable links, and hidden file toggling. WebShare is configured through TrueNAS Connect and requires a dataset and at least one local user account with WebShare access enabled.

When TrueSearch is enabled in the WebShare service configuration, all active shares are indexed for fast file searching by filename, content, or file type. Encrypted datasets are excluded from indexing. Passkey authentication options provide flexible access control for WebShare users.

Containers

Containers, introduced as an experimental feature in TrueNAS 25.04, are fully supported in TrueNAS 26. Containers provide lightweight, isolated Linux environments that share the host kernel while maintaining their own file system, processes, and network configuration, using fewer system resources than virtual machines while starting quickly and scaling efficiently.

TrueNAS 26 extends container support to Enterprise systems with High Availability (HA) configurations, enabling container failover between controllers. HA container failover requires a static IP configuration.

Users migrating from TrueNAS CORE who previously relied on custom Jails can use containers as a supported migration path. See Containers for configuration details.

SMB Stateful Failover

TrueNAS 26 introduces stateful SMB HA failover for Enterprise systems with High Availability (HA) configurations. When enabled in the SMB service configuration, TrueNAS maintains SMB session state across controller failover events, allowing SMB clients to recover existing connections without re-authentication after a failover. See Enabling SMB Stateful Failover for configuration details.

SMB Spotlight Search

TrueNAS 26 adds Spotlight search support for SMB shares, allowing macOS clients to use Spotlight to search file contents directly on TrueNAS SMB shares. Spotlight search is enabled per share in the SMB service configuration.

OpenZFS 2.4

TrueNAS 26 integrates OpenZFS 2.4, which introduces new capabilities including hybrid pool support for combining flash and HDD storage, physical block rewriting, and dynamic gang header improvements. See OpenZFS Feature Flags for details on newly added feature flags.

Linux Kernel 6.18

TrueNAS 26 ships with Linux Kernel 6.18, enabling support for new hardware and receiving long-term maintenance and security updates from the upstream kernel project.

API Changes

TrueNAS 26 removes the deprecated REST API and modernizes the JSON-RPC 2.0 WebSocket API with improved authentication methods, including SCRAM-SHA-512 mutual authentication for API keys.

See API Changes for migration guidance.

26 Featured Content

Getting Started Guide
Release Notes
Community Hardware Guide
Software Install
Migrating from CORE

Networking
Storage Management
Data Protection
Shares
TrueNAS Apps Marketplace

System Settings
Dashboard
Credentials
Datasets

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.

⎙ Download or Print: View all TrueNAS Getting Started articles as a single page for download or print.
TrueNAS 26 Version Notes: Highlights, change log, and known issues for TrueNAS 26 releases.
Feature Deprecations: Notes about TrueNAS features deprecated in the latest nightly releases.
TrueNAS Hardware Guide: Provides information on system hardware and minimum requirements (CPU, memory, etc.). Covers storage considerations, media, controllers, device sizing and cooling, SAS expanders.
Installation Instructions: Guides users (including Enterprise customers) with first-time TrueNAS installations.
Migrating from CORE: Instructions for migrating from FreeBSD TrueNAS CORE to Linux-based TrueNAS versions.
Third-Party Data Migration: Provides data migration instructions for users wanting move data from a third-party NAS solution to the TrueNAS system using the Syncthing Enterprise app.
Configuration Instructions: Configuring TrueNAS after install.
Getting Support: Guides for getting assistance with TrueNAS issues.
User Agreements: Legal statements about using TrueNAS and other general software notices.

Enterprise Deployment Guide

TrueNAS Enterprise
This Table of Contents is a specific article arrangement that guides deploying TrueNAS Enterprise hardware purchased from the TrueNAS team.
User Agreements
TrueNAS EULA
Software Development Life Cycle
TrueNAS Data Collection Statement
Installation Instructions
Preparing for UI Configuration (Enterprise)
Installing
Using the Console Setup Menu
Migrating Instructions
Migrating from TrueNAS 13.0
Configuration Instructions
First Time Login
Configuring using the UI
Setting Up Storage
Setting Up Data Sharing
Backing Up TrueNAS
Configuring Virtualization and Apps

TrueNAS 26 Version Notes

Notable Changes and Known Issues

Upgrading TrueNAS

Component Versions and ZFS Feature Flags

	26-BETA.2	26-BETA.1
Linux Kernel	6.18.23	6.18.13
OpenZFS	2.4.1	2.4.1
Docker Engine	29.0.4	29.0.4
NVIDIA Driver	590.44.01	590.44.01

Feature Flag	GUID	Notes
`block_cloning_endian`	com.truenas:block_cloning_endian	Corrects ZAP entry endianness issues in the Block Reference Table (BRT) used by block cloning. Read-only compatible.
`dynamic_gang_header`	com.klarasystems:dynamic_gang_header	Enables larger gang headers based on pool sector size. Not read-only compatible; must be manually enabled.
`physical_rewrite`	com.truenas:physical_rewrite	Enables physical block rewriting that preserves logical birth times, reducing incremental send stream sizes. Read-only compatible.

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 26 and features deprecated in 26 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 26 and features deprecated in 26 for future removal. Plan migrations immediately to avoid disruptions during upgrades.

Features Removed in 26

REST API

Deprecated: 25.04 Removed: 26

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.

The TrueNAS REST API has been fully replaced by the versioned JSON-RPC 2.0 Websocket API.

Migration Path:

Review current API integrations and identify all REST API calls.
Review the Websocket API documentation to identify replacement endpoints.
Update all scripts and integrations to use Websocket API endpoints.
Test thoroughly in a non-production environment.
Deploy updated integrations before upgrading to 26.

Impact: Systems still using the REST API must migrate to the Websocket API before upgrading to 26. REST API endpoints do not function in 26 and later.

JSON-RPC API Methods

pool.is_upgraded

Deprecated: 25.10 Removed: 26

The pool.is_upgraded method, which reported whether a pool had all ZFS feature flags enabled, is removed in TrueNAS 26. No direct replacement is provided. Scripts that need to inspect pool feature flag state can use pool.query and read the returned feature flag information.

pool.ddt_prefetch

Deprecated: 25.10 Removed: 26

The pool.ddt_prefetch method, which prefetched deduplication table (DDT) entries for a pool, is removed in TrueNAS 26. Use pool.prefetch instead, which prefetches both DDT and Block Reference Table (BRT) metadata in a single call.

Deprecated Features (Removal in Future Versions)

JSON-RPC API Methods

Legacy Authentication Methods

Deprecated: 26 Planned Removal: 27

The auth.login and auth.login_with_api_key methods are deprecated and scheduled for removal in TrueNAS 27. Migrate to auth.login_ex:

Replace auth.login with auth.login_ex using mechanism="PASSWORD_PLAIN". For two-factor authentication, follow with auth.login_ex_continue using mechanism="OTP_TOKEN".
Replace auth.login_with_api_key with auth.login_ex using mechanism="API_KEY_PLAIN" (or mechanism="SCRAM" for stronger mutual authentication).

Removing the legacy auth.login and auth.login_with_api_key entry points does not affect API_KEY_PLAIN or the other non-SCRAM mechanisms on auth.login_ex, which remain supported beyond TrueNAS 27.

See the SCRAM Authentication primer for guidance on implementing SCRAM in custom API clients and migrating pre-TrueNAS 26 API keys to the optimized precomputed format.

Pool Scrub Methods

Deprecated: 26 Planned Removal: TBD

The pool.scrub.run and pool.scrub.scrub methods are deprecated. Use zpool.scrub.run to start, stop, or pause pool scrub operations. A removal version is not yet defined.

system.advanced `consolemsg` Attribute

Deprecated: 26 Planned Removal: TBD

The consolemsg attribute on system.advanced.config and system.advanced.update is deprecated. Use the ui_consolemsg attribute on system.general.config and system.general.update instead. A removal version is not yet defined.

config.save `pool_keys` Parameter

Deprecated: 26 Planned Removal: TBD

The pool_keys parameter on config.save is deprecated and already ignored — passing it has no effect on TrueNAS configuration backups. The parameter remains accepted for backward compatibility. A removal version is not yet defined.

Additional Resources

See the 26 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.

Minimum Hardware Requirements

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

Storage Considerations

The heart of any storage system is the symbiotic pairing of the file system and physical storage devices. The ZFS file system in TrueNAS provides the best available data protection of any file system at any cost and makes effective use of spinning-disk storage, all-flash storage, or a mix of both. ZFS is prepared for the eventual failure of storage devices and is highly configurable to achieve the perfect balance of redundancy and performance to meet any storage goal. A properly configured TrueNAS system can tolerate multiple storage device failures and recreate its boot media with a copy of the configuration file.

Storage Device Quantities

TrueNAS can manage many storage devices as part of a single storage array. With more enterprise-level tuning, TrueNAS can manage up to 1,250 drives in a single storage array.

Storage Media

Choosing storage media is the first step in designing the storage system to meet immediate objectives and prepare for future capacity expansion.

TrueNAS does not officially support T10-DIF drives. Users on our forums have developed a workaround for using T10-DIF drives in TrueNAS, but using unsupported storage devices imposes data-loss risks.

Storage Solutions

Storage Device Sizing

Pool layout (the organization of LUNs and volumes, in TrueNAS/ZFS parlance) is outside of the scope of this guide. The availability of double-digit terabyte drives raises a question TrueNAS users 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.

Storage Device Burn-In

Spinning disk hard drives have moving parts that are highly sensitive to shock and vibration and wear out with use. Consider pre-flighting every storage device before putting it into production, especially:

Start a long HDD self-test (smartctl -t long /dev/). After the test completes (could take 12+ hrs):

Check the results (smartctl -a /dev/)
Check pending sector reallocations (smartctl -a /dev/ | grep Current_Pending_Sector)
Check reallocated sector count (smartctl -a /dev/ | grep Reallocated_Sector_Ct)
Check the UDMA CRC errors (smartctl -a /dev/ | grep UDMA_CRC_Error_Count)
Check HDD and SSD write latency consistency (diskinfo -wS for FreeBSD-based or iostat or fio for Linux-based TrueNAS systems) Unformatted drives only!
Check HDD and SSD hours (smartctl -a /dev/ | grep Power_On_Hours)
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.

Storage Controllers

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)

SAS Expanders

A direct-attached system, where every disk connects to an interface on the controller card, is optimal but not always possible. A SAS expander (a port multiplier or splitter) enables each SAS port on a controller card to service many disks. You find SAS expanders only on the drive backplane of servers or JBODs with more than twelve drive bays. For example, a TrueNAS JBOD that eclipses 90 drives in only four rack units of space is not possible without SAS expanders. Imagine how many eight-port HBAs you need to access 90 drives without SAS expanders.

While SAS expanders, designed for SAS disks, can often support SATA disks via the SATA Tunneling Protocol or STP, 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.

Storage Device Cooling

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.

Memory, CPU, and Network Considerations

Memory Sizing

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.

Error Correcting Code Memory

Electrical or magnetic interference inside a computer system can cause a spontaneous flip of a single bit of RAM to the opposite state, resulting in a memory error. Memory errors can cause security vulnerabilities, crashes, transcription errors, lost transactions, and corrupted or lost data. So RAM, the temporary data storage location, is one of the most vital areas for preventing data loss.

Error-correcting code or ECC RAM detects and corrects in-memory bit errors as they occur. If errors are severe enough to be uncorrectable, ECC memory causes the system to hang (become unresponsive) rather than continue with errored bits. For ZFS and TrueNAS, this behavior virtually eliminates any chances that RAM errors pass to the drives to cause corruption of the ZFS pools or file errors.

To summarize the lengthy, Internet-wide debate on whether to use error-correcting code (ECC) system memory with OpenZFS and TrueNAS, most users strongly recommend ECC RAM as another data integrity defense. However:

Some CPUs or motherboards support ECC RAM but not all
Many TrueNAS systems operate every day without ECC RAM
RAM of any type or grade can fail and cause data loss
RAM failures usually occur in the first three months, so test all RAM before deployment.

Central Processing Unit (CPU) Selection

Choosing ECC RAM limits your CPU and motherboard options, but that can be beneficial. Intel^® limits ECC RAM support to workstation and server motherboards. The 13th generation of their consumer CPUs, such as the Core i5 and i7, support ECC as long as they are paired with a workstation motherboard chipset, such as the W680. Refer to Intel ARK for a full list of Intel CPUs with ECC support.

Which CPU to choose can come down to a short list of factors:

An underpowered CPU can create a performance bottleneck because of how OpenZFS compresses and encrypts (optional) data and performs checksums.
A higher-frequency CPU with fewer cores usually performs best for SMB-only workloads because of Samba, the lightly-threaded TrueNAS SMB daemon.
A higher-core-count CPU is better suited for parallel encryption and virtualization.
A CPU with AES-NI encryption acceleration support improves the speed of the file system and network encryption.
A server-class CPU is recommended for power and ECC memory support.
A Xeon E5 CPU (or similar) is recommended for software-encrypted pools.
An Intel Ivy Bridge CPU or later is recommended for virtual machine use.

Watch for VT-d/AMD-Vi device virtualization support on the CPU and motherboard to pass PCIe devices to virtual machines. Be aware if a given CPU contains a GPU or requires an external one. Also note that many server motherboards include a BMC chip with a built-in GPU. See below for more details on BMCs.

SHA Extensions for x86 instruction set architecture

SHA Extensions in the x86 instruction set architecture support Secure Hash Algorithm family hardware acceleration.

Intel Goldmont (and later), Ice Lake (and later), and Rocket Lake (and later), as well as AMD Zen (and later) processors support the SHA instruction set.

Remote Management: IPMI

As a courtesy to further limit the motherboard choices, consider the Intelligent Platform Management Interface or IPMI (a.k.a. baseboard management controller, BMC, iLo, iDrac, and other names depending on the vendor) if you need:

Remote power control and monitoring of remote systems
Remote console shell access for configuration or data recovery
Remote virtual media for TrueNAS installation or reinstallation

TrueNAS relies on its web-based user interface (UI), but you might occasionally need console access to make network configuration changes. TrueNAS administration and sharing use a single network interface by default, which can be challenging when you upgrade features like LACP aggregated networking. The ideal solution is to have a dedicated subnet to access the TrueNAS web UI, but not all users have this luxury. The occasional visit to the hardware console is necessary for global configuration and system recovery. The latest TrueNAS Mini and R-Series systems ship with full-featured, HTML5-based IPMI support on a dedicated gigabit network interface.

Power Supply Units

The top criteria to consider for a power supply unit (or PSU) on a TrueNAS system are:

Power capacity (in watts) for the motherboard and the number of drives it must support
Reliability
Efficiency rating
Relative noise
Optional redundancy to keep critical systems running if one power supply fails

Select a PSU rated for the initial and a future load placed on it. Have a PSU with adequate power to migrate from a large-capacity chassis to a fully-populated chassis. Also, consider a hot-swappable redundant PSU to help guarantee uptime. Users on a budget can keep a cold spare PSU to limit their potential downtime to hours 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.

Uninterruptible Power Supplies

TrueNAS allows the system to communicate with a battery-backed, uninterruptible power supply (UPS) over a traditional serial or USB connection to coordinate a graceful shutdown in the case of power loss. TrueNAS works well with APC brand UPS, followed by CyberPower. Consider budgeting for a UPS with pure sine wave output. Some models of SSD can experience data corruption on power loss. If several SSDs experience simultaneous power loss, it could cause total pool failure, making a UPS a critical investment.

Ethernet Networking

The network in Network Attached Storage is as important as storage, but the topic has a few key points:

Simplicity - Simplicity is often the secret to reliability with network configurations.
Individual interfaces - Faster individual interfaces such as 10/25/40/100GbE are preferable to aggregating slower interfaces.
Interface support - Intel and Chelsio interfaces are the best-supported options.
Packet fragmentation - Only consider jumbo 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.

High-Speed Interconnects

Higher-band hardware is becoming more accessible as the hardware development pace increases and enterprises upgrade more quickly. Home labs can now deploy and use 40 GB and higher networking components. Home users are now discovering the same issues and problems with these higher speeds found by Enterprise customers.

Use optical fiber over direct attached copper (DAC) cables for the high-speed interconnects listed below:

10Gb NICs: SFP+ connectors
25Gb NICs: SFP28 connectors
40Gb NICs: QSFP+ connectors
100Gb NICs: QSFP28 connectors
200Gb NICs: QSFP56 connectors
400Gb NICs: QSFP-DD connectors

Use optical fiber for any transceiver form factors mentioned when using fiber channels. Direct attached copper (DAC) cables can create interoperability issues between the NIC, cable, and switch.

Virtualized TrueNAS

Finally, 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
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial set up and configuration of their systems.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

The installation process covers installing TrueNAS using an iso.

TrueNAS uses DHCP to provide the initial system IP address. After that, either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the TrueNAS UI to make network changes and complete the initial configuration.

Finally, it covers backing up your system configuration to a file and saving an initial system debug file.

Installation Articles

Preparing for TrueNAS UI Configuration: Provides information on what you need to complete the TrueNAS configuration using the TrueNAS UI.

Preparing for TrueNAS UI Configuration (Enterprise): Provides information on what you need to complete the TrueNAS Enterprise configuration using the TrueNAS UI.

Preparing for TrueNAS UI Configuration (Home Users): Provides information on what home users need to complete the TrueNAS configuration using the TrueNAS UI.

Installing TrueNAS: Provides the TrueNAS iso file installation instructions for physical hardware and virtual machines. Describes the iso verification process using an OpenPGP encryption application.

Installing TrueNAS Enterprise (HA): Provides a sequential process to complete the installation of a TrueNAS Enterprise (HA) dual controller NAS system using an iso file and the TrueNAS UI.

Using the Console Setup Menu: Provides information on using the Console Setup menu after installing TrueNAS from the iso file to configure network settings.

Preparing for TrueNAS UI Configuration

Users installing and configuring TrueNAS on their own servers should follow the instructions in this article to prepare for their deployment.

For support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.

If you are not the administrator responsible for network access in your company, contact your network administrator for assistance. If your company obtains network hardware and support from an Internet or cable service provider, contact them for assistance with where to obtain this information.

Physical Access

When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration. An additional USB port is required when using a USB storage device to install TrueNAS from an .iso file.

IPMI Access

Intelligent Platform Management Interface (IPMI) servers provide access to servers and allow remote users to install software and configure or administrate systems at the console level, or as though you are in the room with the server when you are working remotely. Ensure IPMI is properly configured for secure remote management of TrueNAS servers.

To provide for remote administration of your TrueNAS system, assign access through an IPMI server to the TrueNAS server. To make this possible assign an IP address to use for access and set up administrator credentials (user name and password) to access the TrueNAS IPMI connections.

Network Access

TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.

To configure your TrueNAS server to work with your network, you need:

DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.

If you obtained network equipment and Internet service access from either an Internet or cable service provider, contact their support departments for assistance with network addresses.

SMTP Access

Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection. TrueNAS uses either SMTP to send mail from TrueNAS to administrator or designated individual email addresses for system alert notifications.

If you do not know this information and do not have a network administrator in your company, or if you are a home user, contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.

Directory Service Access

This section does not apply to small companies with very few users or home deployments of TrueNAS.

TrueNAS works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap. Active Directory and LDAP configuration settings have similar requirements.

Active Directory

Provide the following information to configure TrueNAS Active Directory access:

Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow TrueNAS to communicate with the server)
List of trusted domains TrueNAS should allow

LDAP

Provide the following information to configure TrueNAS LDAP access:

Host name where the LDAP sever is located and where TrueNAS accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for TrueNAS to use for authentication

Advanced Directory Services

When configuring Kerberos and/or IDmap, you might need to provide:

Kerberos realm and keytab information
IDmap schema information

Preparing for TrueNAS UI Configuration (Enterprise)

TrueNAS Enterprise
TrueNAS Enterprise customers, or those that purchased systems and service contracts from iXsystems, should use the information in this article to prepare for their TrueNAS system deployments.
The TrueNAS Enterprise Support department provides assistance with the configuration areas documented in this section.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Required Access and Information

Because there are many possible scenarios for network configurations, this section covers the basics of the access and information required to configure TrueNAS to work in your network environment. If you are the individual tasked with installing and configuring the TrueNAS server but are not responsible for network services in your company, contact your network administrator to request they provision and verify new IP address assignments and provide the other information for access.

Physical Access

IPMI Access

The Intelligent Platform Management Interface (IPMI) provides a way for system administrators to remotely access their TrueNAS system. Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server. TrueNAS Enterprise systems sold by iXsystems provide IPMI network ports, but other hardware might not have IPMI ports.

iXsystems requires access through your IPMI server to access the TrueNAS server to provide remote administration support. To make this possible:

Assign an IP address to the IPMI port of each controller in the TrueNAS array. If you have a High Availability (HA) system, the server is equipped with two controllers so assign two IP addresses, one for each controller.
Create and provide administrator credentials (user name and password) for access to the TrueNAS IPMI connections. Configure the administrator credentials to access both IP addresses assigned to the HA system controllers.

Network Access

To configure your TrueNAS server to work with your network, you need:

DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.

If you have an HA system with two controllers, you must assign a total of three IP addresses:

A virtual IP for access to the UI when either controller is active
An IP address for the primary network port on controller A
An IP address for the primary network port on controller B

TrueNAS Enterprise Support can assist you with any questions you have with these network requirements. Provide the information listed to iXsystems when requested to expedite configuring your system network settings.

The failover feature on TrueNAS Enterprise platforms with High Availability (HA) can malfunction in network environments that heavily use the Spanning Tree Protocol (STP). When configuring or troubleshooting HA failover, if TrueNAS HA failover does not function properly, investigate STP use in the network and consider disabling STP on network switch ports connected to the TrueNAS platform.

SMTP Access

Have your network administrators provide the SMTP addresses to allow TrueNAS to send emails from your network.

Directory Service Access

TrueNAS works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap. Active Directory and LDAP configuration settings have similar requirements. Additionally, consider implementing two-factor authentication (2FA) for enhanced security when authenticating users against Active Directory or LDAP directory servers.

Active Directory

Provide the following information to configure TrueNAS Active Directory access:

Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow TrueNAS to communicate with the server)
List of trusted domains TrueNAS should allow

LDAP

Provide the following information to configure TrueNAS LDAP access:

Host name where the LDAP sever is located and where TrueNAS accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for TrueNAS to use for authentication

Advanced Directory Services

When configuring Kerberos and/or IDmap, you might need to provide:

Kerberos realm and keytab information
IDmap schema information

Preparing for TrueNAS UI Configuration (Home Users)

Users installing and configuring TrueNAS on their home server should follow the instructions in this article to prepare for their deployment.

For support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.

Physical Access

IPMI Access

Intelligent Platform Management Interface (IPMI) servers provide a way for system administrators to remotely access and control systems. Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server. Home users with compatible hardware have the option to use an IPMI connection to remotely administer their system over the Internet.

To make this remote access possible you need an IPMI capable system or service:

Assign an IP address to access to the controller in the TrueNAS system.
Set up your administrator credentials (user name and password) for access through the TrueNAS IPMI connections.

Network Access

To configure your TrueNAS server to work with your network, you need:

DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed.
DNS name sever IP addresses in your network (TrueNAS can accommodate up to three name server IP addresses).
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network.
Main domain name or the domain name for the portion of your network where the TrueNAS server is deployed.
Host name you want to use if not using the default-assigned host name in TrueNAS (truenas).
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP).
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.

Home users obtaining network equipment and Internet service access from either an Internet or cable service provider can contact the provider support departments for assistance with network addresses.

SMTP Access

Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection. TrueNAS uses SMTP to send mail from TrueNAS to either the administrator or designated individual email addresses for system alert notifications.

Contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network. Consider utilizing two-factor authentication (2FA) for enhanced security when accessing SMTP servers for email delivery from TrueNAS.

Installing TrueNAS

After you download the .iso file, you can start installing TrueNAS!

This article describes verifying the .iso file, then installing TrueNAS using that file, and selecting the type of installation as either on physical hardware or a virtual machine (VM).

TrueNAS Enterprise
TrueNAS Enterprise customers should receive their systems already installed and ready for UI configuration. If any issues require you to install or re-install TrueNAS, contact TrueNAS Enterprise Support for assistance.
Enterprise customers with High Availability (HA) systems should not attempt to re-install their systems on their own. The dual controller install process is complicated and the risk of causing serious network issues is high. Contact TrueNAS Enterprise Support for assistance!
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

ISO Verification

The iXsystems Security Team cryptographically signs TrueNAS .iso files so that users can verify the integrity of their downloaded files. This section demonstrates how to verify an .iso file using the Pretty Good Privacy (PGP) and SHA256 methods.

Performing PGP ISO Verification

You need an OpenPGP encryption application for this method of ISO verification.

Click here for the verification process.

Obtain an OpenPGP encryption application to use. There are many free applications available. The OpenPGP group provides a list of available software for different operating systems at https://www.openpgp.org/software/. The examples in this section show verifying the TrueNAS .iso using gnupg2 in a command prompt, but Gpg4win is also a good option for Windows users.
To verify the .iso source, go to https://www.truenas.com/download-tn-scale/, expand the Security option, and click PGP Signature to download the Gnu Privacy Guard signature file. This file can be a (.gpg) or a (.sig) file. Open the PGP Public key link and note the address in your browser and Search results for string.

Use one of the OpenPGP encryption tools mentioned above to import the public key and verify the PGP signature.

Go to the .iso and the .iso.gpg or .iso.sig download location and import the public key using the keyserver address and search results string:

user@ubuntu /tmp> gpg --keyserver keys.gnupg.net --recv-keys 0xc8d62def767c1db0dff4e6ec358eaa9112cf7946
gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
gpg: key 358EAA9112CF7946: public key "IX SecTeam <security-officer@ixsystems.com>" imported
gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
gpg: Total number processed: 1
gpg:               imported: 1
user@ubuntu /tmp>

Use gpg --verify to compare the .iso and the .iso.gpg or .iso.sig files:

user@ubuntu /tmp>  gpg --verify TrueNAS-SCALE-21.04-ALPHA.1.iso
gpg: Signature made Thu May 27 10:49:02 2021 EDT using RSA key ID 12CF7946
gpg: Good signature from "IX SecTeam <security-officer@ixsystems.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: C8D6 2DEF 767C 1DB0 DFF4  E6EC 358E AA91 12CF 7946
user@ubuntu /tmp>

This response means the signature is correct but still untrusted.

Go back to the browser page that has the PGP Public key. Open and manually confirm that the key is issued for IX SecTeam <security-officer@ixsystems.com> (iX Security Team) on October 15, 2019, and is signed by an iXsystems account.

Using SHA256 Verification

SHA256 verification uses the checksum to validate/verify the file. The SHA256 checksum file for each TrueNAS release is published alongside the .iso file on the TrueNAS Download page and in the TrueNAS software CDN.

Click here for the verification process.

The command to verify the checksum varies by operating system:

BSD: use command sha256 isofile
Linux: use command sha256sum isofile
Mac: use command shasum -a 256 isofile

Freeware or online checksum utilities are available for Windows users.

The value produced by running the command must match the value in the .iso.sha256 checksum file for your release. Different checksum values indicate a corrupted installer file that you should not use.

Installing TrueNAS

You can install TrueNAS on either physical hardware or a virtual machine.

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.

Installing on Physical Hardware

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.

Preparing the Install File

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.

Writing the TrueNAS installer to a USB stick on Linux

To write the TrueNAS installer to a USB stick on Linux, plug the USB stick into the system and open a terminal.

Start by making sure the USB stick connection path is correct. There are many ways to do this in Linux, but a quick option is to enter the command lsblk -po +vendor,model and note the path to the USB stick. This shows in the NAME column of the lsblk output.

Next, use the dd command to write the installer to the USB stick.

Be very careful when using dd, as choosing the wrong of= device path can result in irretrievable data loss!

Enter this command dd status=progress if=path/to/.iso of=path/to/USB in the CLI.

If this results in a permission denied error, use the command sudo dd with the same parameters and enter the administrator password.

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.

Using Ventoy

Ventoy is an open-source tool TrueNAS users can use when creating a bootable USB or other local drive for an ISO image file when installing TrueNAS. After installing Ventoy on a USB or local drive, users can copy the install media multiple times onto this same device with the Ventoy executable file. Ventoy provides a directory tree that allows users to browse to or select the iso .

How does Ventoy work?

The Ventoy executable, Ventoy2Disk.exe, is installed on a device such as a USB drive or a local drive. The Ventoy executable creates partitions formatted with the exFAT file system on the device. It creates a master boot record (MBR) layout on the disk.

The default MBR layout consists of a minimum of three partitions:

Part 1 - Main partition of 32 GB to 33 MB for the ISO or other file types.
Part 2 - EFI system partition (ESP) of 32 MB, for the EFI boot and to hold the Ventoy files.
Part 3 - MBR and gap partition of 1 MB, to hold the bootloader in Legacy BIOS system.

Ventoy 1.0.14, allows preserving 2 GB of space at the bottom of the disk where users can create part 3 or 4 during the Ventoy installation process. To create this space in Windows, use the Option > Partition Configuration option. In Linux, use the -r tag with the Ventoy install string.

Ventoy offers several ways to install their executables and to create bootable media. Always use the default method but if you experience issues, try these alternatives to the default mode:

Default Ventoy2Disk.exe, to create bootable media on a USB drive

Alternative methods:

Ventoy LiveCD for Windows
Ventoy Vlnk for Windows and Linux
Ventoy Memdisk mode for Windows and Linux
Ventoy Grub2 mode for Linux

Ventoy2Disk.exe Installations

To install Ventoy on a USB drive, download the installation package. After extracting the Ventoy2Disk.exe file, run it. If using Windows GUI mode, select the device and click Install or Update when updating Ventoy on the drive to a later release.

Ventoy allows using Windows CLI to install the executable file. Refer to Ventoy documentation for more information. After installing Ventoy on the USB drive, copy the TrueNAS iso to the USB. When updating to a new TrueNAS release or clean-installing from an iso, copy the new iso to the USB with Ventoy installed.

Ventoy writes data to a USB drive during the installation and upgrades to the installed version. It writes directly to the physical sector and modifies the MBR and partition table. Because of this, Windows systems might experience failures when using the Ventoy2Disk.exe executable to install Ventoy even after several retry attempts of unplugging and reinserting the USB does not resolve the issue.

Linux systems that use the dd command do not experience the failures instances in Windows installations.

Why does Ventoy fail this way in Windows systems? Ventoy relies on modifying the MBR and partition table during installation, but Windows restrictions on modifying these components impact this operation. The process Ventoy uses can be easily affected by other programs such as anti-virus software, system active protection processes, and others.

Ventoy provides two methods to get around the Windows system issue:

Creating a vtsi file
Using LiveCD

Creating a VTSI File

Enable Option > Generate VTSI File and click Install in the Ventoy UI to create a VentoySparseImg.vtsi file instead of writing to the disk. After creating this file, use Rufus (3.15 or greater) to write the vtsi file to the disk to complete the installation of Ventoy. This requires only selecting the corresponding disk and the vtsi file and leaving the other options in Rufus set to default values.

Rufus only supports USB or removable HDD with a USB interface. A local HDD is not supported. To use the removable HDD pres Alt+F to show the drive option.

The vtsi file can only be written to the corresponding disk but cannot be written to other disks.

Ventoy LiveCD Installations

Ventoy LiveCD is only for Windows users, and only necessary when the Ventoy2.Disk.exe fails to install or upgrade.

The Ventoy LiveCD option provides several options for installing the Ventoy executable and adding a TrueNAS iso.

Option 1 - Download Rufus and write VentoyLiveCD ISO to the USB drive.
Option 2 - Format the USB drive with FAT32 and extract the LiveCD files to the USB drive
Option 3 - Use VMWare to create a VM and add the USB drive as a disk in the VM

After installing Ventoy LiveCD to a device, copy the TrueNAS iso to the USB drive.

Option 1 requires downloading Rufus, then use Rufus to write the iso to the USB drive. After adding Ventoy LiveCD to the USB drive copy the TrueNAS release iso to the USB drive.

Insert the USB into a USB port on the TrueNAS server as described in the installation instructions.

Option 2 requires formatting the USB drive in FAT32 type by system command or third-party tool. In Windows systems, USB drives with large capacity might not have a FAT32 formatting option. In this case, create a small partition using diskpart and specifying a partition size of 4 GB, then format that partition with FAT32. After formatting the USB drive, extract the Ventoy LiveCD files to the USB drive.

Option 3 is the best option when installing an iso in a VM. It requires VMWare to create a VM with a default configuration, and then delete the default drive before adding the USB drive as a disk for the VM.

VentoyVlnk.exe Installation

Ventoy supports booting image files such as iso files from a local disk through Vlnks. A VLnk is a file link in Ventoy that is similar to a softlink that creates a pointer or shortcut to the iso location. Vlnks allow Ventoy to boot an image file such as an iso file stored on a local disk rather than copying that iso to the USB drive with Ventoy installed on it. This is particularly useful when dealing with large image files where there is limited space on the USB drive. it saves time and space on the USB drive.

Ventoy offers Windows and Linux methods to create Vlnks. In Windows, Use the VentoyVlnk.exe to generate the Vlnk file by selecting the image on the local disk. In Linux, run a script like VentoyVlnk.sh with a command like sudo bash VentoyVlnk.sh -vc path/to/image.iso to create the Vlnk file.

Vlnks can be used with Ventoy plugins, or like regular image files.

For TrueNAS, store the iso file on a local disk or network-connected drive apart from the USB drive where the VentoyVlnk.exe is installed. Using VentoyVlnk.ext installed on a USB drive, create the Vlnk and specify the path to the iso file location. Ventoy creates the Vlnk shortcut to the file (for example, filename.vlnk.iso) and location on the USB drive. Ventoy uses the Vlnk to locate and boot from the original image file at the local drive location. The TrueNAS system needs access to the location specified in the path, the local disk (or network disk) location.

If security requirements do not allow using Vlnks to a network disk, store the iso on a local disk on the TrueNAS server and create the Vlnk on the USB drive where VentoyVlnk.exe is installed.

Create a Vlnk file for the image file stored on a local disk. You can create the link file in the same directory as the VentoyVlnk.exe file. You cannot specify the name of the vlnk file created by the VentoyVlnk.exe but you can use command-line mode to change it by entering VentoyVlnk.exe -s. A prompt allows you to save the path after selecting the iso. Or use VentoyVlnk.ex -i filename.iso -o linkname.vlnk.iso to directly generate the Vlnk file; and no other interactions are nessesary.

Next copy the Vlnk file to the Ventoy USB and boot from it. You can put the Vlnk file in the root directory or a subdirectory.

Observe the rules in the Ventoy documentation for naming Vlnk files.

To resolve issues with booting files in a local disk, refer to Browse/Boot Files in Local Disk.

Memdisk Mode Installation

Ventoy Memdisk mode is an alternative to the default Ventoy mode when Legacy BIOS modes have problems. When booting, Ventoy normal mode only reads the iso file and just the content needed for boot. Ventoy Memdisk Mode loads the whole ISO image file into memory and boots it.

Activate Ventoy Memdisk mode by pressing Ctrl+d to switch from default to Memdisk mode. Press Ctrl+d again to return to default mode.

Only iso and some IMG files are supported. ISO file size is limited in Memdisk mode (usually less than 1 GB). TrueNAS iso files typically fall under the 1 GB upper limit.

To use Memdisk mode, after installing Ventoy2Disk.exe on a USB drive and copying the iso with one of the available methods, press Ctrl+d before selecting the iso file in the Ventoy boot menu. To return to default mode, press Ctrl+d again.

GRUB2 Installation

Ventoy GRUB2 mode is an alternative for booting Linux iso files, and supports Legacy BIOS and UEFI. It uses a different mechanism to boot an ISO file. It emulates the iso file as a CDROM to boot it. Ventoy GRUB2 is like booting a CD with an optical drive except the physical drive is not there.

The system motherboard firmware must support this, especially in UEFI mode. If the BIOS firmware is non-standard, Ventoy can have problems booting an ios file.

Only use GRUB2 mode if you experience problems with the default Ventoy mode. Ventoy GRUB2 can only be used to boot Linux iso files that contain a grub2 configuration file. TrueNAS iso files have a grub2 configuration file for booting that is required to use Ventoy GRUB2 mode.

To enter GRUB2 mode, press Ctrl+r. Press again to return to default mode.

Using Rufus

Rufus is a Windows program that allows you to create a bootable USB drive from an ISO file.

Rufus supports most Linux and Windows operating systems, including TrueNAS. For a list of supported ISO, see the Rufus non-exhaustive list.

How does Rufus work?

Rufus formats and erases all data from the USB drive. Transfer any files you want to keep off the drive before using Rufus.

Rufus usually auto-detects the USB drive, but you can manually select the drive in the Devices field of the Rufus UI. In most cases, the USB drive shows as No_Label.

Rufus allows selecting the iso file from a file browser.

To use Rufus on a Mac, create a Windows VM on your Mac, then create the bootable USB drive with Rufus.

To create a bootable USB with Rufus:

Download the package from the Rufus downloads page.
Open Rufus by double-clicking on Rufus. Downloaded files are in your Downloads folder.
Insert a USB drive in any free USB port on the system.
Locate and select the iso file to populate the Boot Selection field. Click SELECT and select the ISO file.
Check the settings and adjust any to suit your use case.
Enter a name for the volume Rufus creates in Volume Label.
Click START.

For more information on this tool, refer to Rufus documentation or the user guide.

Using TINU

TINU is an open-source tool to create bootable MacOS installers. It creates bootable MacOS installers capable of running Apple MacOS. The program uses a GU for the createinstallmedia executable found in any MacOS installer app. This allows you to easily create MacOS install media without using the command line or Disk Utility, and it detects and prevents the most common errors when creating bootable MacOS installers

Follow the instructions provided in the GUI to begin creating the bootable media.

This program works with every MacOS installer app with the creteinstallmedia executable inside its internal resources folder. The program does not require special preparation, requirements are:

A computer that runs MacOS X Yosemite or later
A drive or partition to turn into a MacOS installer, of at least 8 GB (some MacOS releases require 9 GB or 12 Gb)
A copy of a “.ap” MacOS/Mac OS x installer

To use:

Download a copy of the TINU app
Launch the program and follow the instructions in the GUI.

Installing From the Device Media

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.

Using the TrueNAS Installer

If you are doing a clean install from the TrueNAS .iso file as part of migrating from a different TrueNAS version, or to recover from a serious issue that requires you to re-install TrueNAS from the .iso, have your network configuration information ready to use after the installation completes. Also have your TrueNAS system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered TrueNAS clean-install system.

After the system boots into the installer, follow these steps.

TrueNAS Installer Instructions

Select Install/Upgrade.
Figure 13: Console Setup Screen
Select the desired install drive.
Figure 14: Destination Media Screen
Select Yes to proceed with a clean installation of TrueNAS from the .iso. This erases the contents of the selected drive!
Figure 15: Install Warning Screen
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.
Figure 16: Authentication Method Screen
Next, enter a password for the new truenas_admin user.
Figure 17: Admin Password Screen
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.
Figure 18: Legacy Boot Screen
Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.

After following the installation steps, restart the system, and then remove the install media.

Troubleshooting

If the system does not boot into TrueNAS, there are several things you can check to resolve the situation:

Check the system BIOS for an option to change USB emulation from CD/DVD/floppy to hard drive. After making the change it still does not boot, check to see if the card/drive is UDMA compliant.
Check to see if the system BIOS supports UEFI with BIOS emulation. If not, check for an option to boot using legacy BIOS mode.

If the system starts to boot but hangs with this repeating error message: run_interrupt_driven_hooks: still waiting after 60 seconds for xpt_config, go into the system BIOS and look for an onboard device configuration for a 1394 Controller. If present, disable that device and try booting again.

If the burned image fails to boot and you burned the image using a Windows system, wipe the USB stick before trying a second burn using a utility such as Active@ KillDisk. Otherwise, the second burn attempt fails as Windows does not understand the partition written from the image file. Be very careful to specify the correct USB stick when using a wipe utility!

Installing on a Virtual Machine

Because TrueNAS is built and provided as an .iso file, it works on all virtual machine solutions (Proxmox, VMware, VirtualBox, Citrix Hypervisor, etc). This section describes installing on a VM using VMware Workstation Player on Windows.

Minimum Virtual Machine Settings

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.

Networking Checks for VMWare

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.

Installing on a Generic Virtual Machine

The procedure for creating a TrueNAS VM is the same for most hypervisors.

Generic VM Installation Instructions

Create a new virtual machine as usual, taking note of the following:
- Point a bootable CD/DVD device in the virtual hardware to the TrueNAS installer image (this is usually an .iso).
- Configure the virtual network card to allow your network to reach it. Bridged mode is optimal, as it treats the network card as if it is plugged into a simple switch on the existing network.
- Identify the OS you plan to install on the VM. This is required by some products. The ideal option is Debian 11 64 bit. If not available, try options like Debian 11, Debian 64 bit, 64 bit OS, or other.
- Install in BIOS mode for VMWare hypervisors.
- Ensure the VM has sufficient memory and disk space. For TrueNAS set to at least 8 GB RAM and 20 GB disk space. Not all hypervisors allocate enough memory by default.
Boot the VM and install TrueNAS as usual.
After the installation completes, shut down the VM instead of restarting, and disconnect the CD/DVD from the VM before restarting the VM.
After restarting into TrueNAS, install VM tools if applicable for your VM, and if they exist for Debian 11, or ensure they loaded on boot.

Installing Using VMWare Player 15.5

This example describes installing TrueNAS using VMWare Player 15.5.

Installation Instructions

Open VMware Player and click Create a New Virtual Machine to enter the New Virtual Machine Wizard.

Install the disk image file.
Select the Installer disk image file (.iso) option, click Browse…, and upload the TrueNAS .iso downloaded earlier.
Name the virtual machine.
You can change the virtual machine name and location.
Specify the disk capacity.
Specify the maximum disk size for the initial disk. The default 20GB is enough for TrueNAS.
Next, select Store virtual disk as a single file.
Review the virtual machine configuration.
Review the virtual machine configuration before proceeding. By default, VMware Player does not set enough RAM for the virtual machine.
Click Customize Hardware… > Memory. Drag the slider up to 8GB and click Ok.
Power on the machine after creation if desired. Select Power on this virtual machine after creation.

Adding Virtual Disks

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.

Adding Virtual Disk Instructions

After creating the virtual machine, select it on the virtual machine list and click Edit virtual machine settings.
Click Add… and select Hard Disk. Select SCSI as the virtual disk type.
Select Create a new virtual disk. Specify the maximum size for this additional virtual disk. This disk stores data in TrueNAS. If desired, allocate the disk space immediately by setting Allocate all disk space now.
Select Store virtual disk as single file.
Enter a name and choose a location for the new virtual disk.

Repeat this process until enough disks are available for TrueNAS to create ideal storage pools. This depends on your specific TrueNAS use case. See Pool Creation for descriptions of the various pool (“vdev”) types and layouts.

Using the TrueNAS Installer

Just as with installing TrueNAS on physical hardware, complete the installation in the VM by booting into the TrueNAS installer.

Using the TrueNAS Installer in a Virtual Machine

Select the virtual machine from the list and click Play virtual machine. The machine starts and boots into the TrueNAS installer.

Select Install/Upgrade.
Figure 19: Console Setup Screen
Select the desired install drive.
Figure 20: Destination Media Screen
Select Yes to proceed with a clean installation of TrueNAS from the .iso. This erases the contents of the selected drive!
Figure 21: Install Warning Screen
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.
Figure 22: Authentication Method Screen
Next, enter a password for the new truenas_admin user.
Figure 23: Admin Password Screen
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.
Figure 24: Legacy Boot Screen
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)

TrueNAS Enterprise
Installing TrueNAS on High Availability (HA) systems is complicated and should be guided by Enterprise-level support. Contact TrueNAS Enterprise Support for assistance whenever attempting to install TrueNAS on Enterprise HA hardware.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/
Do NOT use Linux or CLI commands to recover or clean-install the TrueNAS iso file or configure any initial configuration settings! Incorrect use of CLI commands can further disrupt your system access and can potentially do greater damage to your system. Proceed at your own risk.

Installing TrueNAS for an Enterprise (HA) System

This article outlines a procedure to do a clean install of a TrueNAS Enterprise High Availability (HA) systems using an iso file.

HA systems are dual controller systems with the primary controller referred to as controller 1 (sometimes also as controller A) and controller 2 (or controller B).

For best results, we recommend executing this procedure on both controllers at the same time. You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.

Alternately, install and configure controller 1 while keeping controller 2 powered off. When controller 1 is completely configured, power on controller 2 to install TrueNAS and restart the controller. When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.

TrueNAS includes features and functions to help with completing the configuration process after installing and getting access to the TrueNAS web interface. This includes utilizing numerous high availability (HA) features to ensure data integrity and availability.

Preparing for a Clean Install

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.

Overview of the Installation Procedure

For best results, we recommend executing this procedure on both controllers at the same time. You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off. When controller 1 is completely configured, power on controller 2 to install TrueNAS and restart the controller. When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.

There are two ways to install the HA dual controller system to ensure controller 1 comes online as the primary controller:

Install both controllers simultaneously beginning with controller 1, then immediately starting the install on controller 2.
Installing each controller individually to specific points in the installation process.

Simultaneous installation must start with controller 1, so it comes online first. Installing each controller individually follows a particular method to ensure controller 1 comes online as the primary controller.

The sections in this article cover the primary steps as a simultaneous installation:

Download the iso file from the TrueNAS website and prepare the USB flash drives if not using IPMI for remote access.
Log into your IPMI system using the network address assigned to controller 1, and then establish a second connection with controller 2 in a new browser session.
Install TrueNAS using the iso file and select the Fresh Install option. Install on controller 1, then immediately begin installing on controller 2 in the other IPMI session to simultaneously install TrueNAS on both controllers.
Disable DHCP, then enter the network settings to controller 1 using the Console Setup Menu. Enter the IP address and netmask assigned to controller 1, then enter the global network settings for host name, domain name, and nameservers.
Use the TrueNAS UI for system configuration as it has safety mechanisms in place to prevent disrupting network access that could require you to repeat the clean install to access your system. However, if you are experienced with the Console Setup Menu and are using it to configure network settings you can configure the rest of the controller 1 network settings with the Console setup menu.
Log into the TrueNAS UI for controller 1 to sign the EULA agreement and apply the system HA license.
Disable failover to configure the rest of the network settings and edit the primary network interface on controller 1, and then enable failover.
Complete the minimum storage requirement by adding or importing one pool on controller 1.
Sign in using the Virtual IP (VIP) address.
With controller 2 powered up, on controller 1 sync to peer to complete the install and make controller 2 the standby controller.

The sections that follow describe these steps in detail.

Overview of the Alternative Installation Process

This process of installing each controller sequentially has two methods:

Install and configure controller 1 up to the point where you are ready to sync to controller 2. When complete, install controller 2 and restart. After the console setup menu displays, switch back to controller 1 and sync to peer. This synchronizes the completed configuration from controller 1 to controller 2 and keeps controller 1 designated as the primary controller. Or
Begin installing controller 2 immediately after installing controller 1. When controller 2 finishes installing, power it off and keep it powered down. When finished configuring controller 1, power up controller 2 and wait for it to finish booting up. Switch back to controller 1 and sync the configuration to controller 2.

This section provides an overview of the alternative method to clean install an HA system with controller 2 powered off while installing and configuring controller 1. These steps are nearly identical to the section above but controller 2 is either powered off or not installed while you install and configure controller 1.

Use either the prepared USB flash drive inserted into a USB port for controller 1 or log into an IPMI session and install TrueNAS on controller 1. Finish the installation and allow controller 1 to complete its first boot.
Use either the prepared USB flash drives inserted into a USB port for controller 2 or log into an IPMI session for controller 2 to install TrueNAS. When the installation finishes, power down controller 2.
Configure the required network settings on controller 1 with the Console setup menu.
Log into controller 1 using the IP address assigned to controller 1. Apply the HA license, sign the EULA, and complete the UI configuration to the point where you are ready to sync to peer on controller 1, but do not sync yet.
Power up controller 2 and wait for it to complete the boot process.
Log into controller 1, go to System > Failover, and click Sync to Peer. This synchronizes controller 2 with controller 1 and restarts controller 2. Controller 2 becomes the standby controller when it finishes restarting.

Downloading the TrueNAS Install File

Download the .iso file.

If you are remote to the system and are installing through an IPMI connection you do not need to save the .iso file to a USB flash drive.

If you are physically present with the TrueNAS system, burn the .iso file to a USB flash drive and use that as the install media.

Using IPMI to Install the ISO on a Controller

Use this process to install the iso file on both controller 1 and controller 2. Best practice is to begin the install on controller 1, then immediately begin the install on controller 2.

Installing ISO Steps

Enter the IP address assigned to the controller 1 IPMI port into a web browser and log into your IPMI system with admin credentials.
Select Remote Control > iKVM/HTML5 to open the Console Setup window.
IPMI interfaces can vary but they generally have options for Remote Control and iKVM/HTML5 to open a console session on the platform.
Install the .iso file. Select the Virtual Media > CD-ROM image option in your IPMI system.
a. Enter the IP address of where you downloaded the .iso file into Share Host. You might need assistance from your Network or IT department to obtain this address.
b. Enter the path to the .iso file. For example, if you stored the file in an iso folder enter /iso/TrueNAS-SCALE-22.12.1.iso in Path to Image.
c. Click Save, then Mount. You should see the .iso file under Device 1 or the device name your IPMI configures.
Return to the Remote Control > iKVM/HTML5 window opened in step 2. Either use your keyboard or open the keyboard in the window then:
a. Type 8 to restart controller 1 (also repeat for controller 2), and type y to confirm and restart.
b. As the system restarts, be prepared to hit the F11 key when you first see the TrueNAS Open Storage splash screen. Alternatively, you can start clicking on the F11 key on the online keyboard until you see the TrueNAS Installer screen.
c. Select the UEFI: ATEN Virtual CDROM device from the boot list. The bootstrap loader begins. When it ends the TrueNAS installer opens.

Using the TrueNAS Installer

If you are doing a clean install from the TrueNAS .iso file to recover from an issue that requires you to re-install TrueNAS from the .iso, have your network configuration information ready to use for controller 1 after the installation completes. Do not configure network settings on controller 2. Also have your TrueNAS system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered TrueNAS clean-install system.

TrueNAS Installer Steps

Select Install/Upgrade.
Figure 1: Console Setup Screen
Select the desired install drive.
Figure 2: Destination Media Screen
Select Yes to proceed with a clean installation of TrueNAS from the .iso. This erases the contents of the selected drive!
Figure 3: Install Warning Screen
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.
Figure 4: Authentication Method Screen
Next, enter a password for the new truenas_admin user.
Figure 5: Admin Password Screen
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.
Figure 6: Legacy Boot Screen
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 .iso file on both controller 1 and 2 and finishing the TrueNAS Installer process, use the Console setup menu to configure the required network settings on controller 1, so it can access the TrueNAS UI. TrueNAS single controller systems use the DHCP-assigned IP address for the primary network interface to access the UI to complete the rest of the network and other configuration settings. However, HA systems with dual controllers must use static IP addresses.

To allow controller 1 to access the UI, you must disable DHCP and add the controller 1 static IP address and netmask as an alias on the primary network interface, and then enter the network settings for host name, domain name, default gateway, and the name servers (1 and 2). You can configure the rest of the HA global network settings in the TrueNAS web UI.

To use the Console setup menu to configure required network settings on controller 1:

Type 1 and then press Enter to open the Network Interfaces screen.
Figure 8: 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.
Figure 9: Select Primary Network Interface
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.
Figure 10: Update Network Configuration for HA

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 nameserver2	The 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.

Configuring Settings in the TrueNAS UI

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.

Applying the HA License

TrueNAS UI Enterprise customers see the End User License Agreement (EULA) screen the first time they log in. Sign the agreement to open the main TrueNAS Dashboard. Apply the system license next.

Go to System > General Settings and click Add License on the Support widget. Copy your license and paste it into the License field, then click Save License. The Reload dialog opens. Click Reload Now. Controller 1 restarts, and displays the EULA for controller 2. Sign the EULA agreement for controller 2, and add the license.

The controller 1 and 2 (or a and b) serial numbers display on the Support widget on the System > General Settings screen.

Configuring Network Settings

Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready, click Sync to Peer to haveTrueNAS apply settings to controller 2.

TrueNAS Enterprise (HA) systems use three static IP addresses for access to the UI:

VIP to provide UI access regardless of which controller is active. If your system fails over from controller 1 to 2, then fails back over to controller 1 later you might not know which controller is active.
IP for controller 1. Do not use DHCP to assign the IP address! If enabled, DHCP assigns an IP to the primary network interface on non-HA systems. Disable DHCP, and then manually enter the Controller 1 static IP address your network administrator assigned for this controller.
IP for Controller 2. Manually enter the second IP address assigned for this controller.

Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.

TrueNAS safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes. This is to prevent users from breaking their network connection in TrueNAS.

To configure network settings on controller 1:

Disable the failover service. Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure. Select Enable Automatic Failover to clear the checkmark, then select Default TruNAS Controller to enable it, and then click Save to disable failover.
Go to System > Network and click Settings to edit the global network settings. Add the controller and virtual host names and update any other network settings.
Edit the primary network interface to add failover settings. Click on the more_vert to the right of the the primary interface eno1, and select Edit to open the Edit Interface screen for this interface.
Figure 11: Edit Network Interface Settings
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.
Figure 12: Edit Failover Setting
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.
Figure 13: Re-Enable Failover

Adding the Storage Pool

Create or import a storage pool from a backup. You must have at least one storage pool on controller 1. After saving the storage pool, controller 2 automatically restarts. Wait until it comes back online before syncing controller 1 with controller 2.

For more information on how to create a new pool click here. For more information on how to import a pool click here.

Syncing Controller 1 and 2

Turn the failover service back on. Go to System > Services locate the Failover service and click edit.
Select Disable Failover to clear the checkmark and turn failover back on, then click Save. The system might restart. Use IPMI to monitor the status of controller 2 and wait until the controller is back up and running.
Log out of the controller 1 UI, and log in using the VIP address.
Sync controller 1 and 2. With controller 2 powered on, but not configured, from controller 1 click Sync To Peer. Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation. This sync controller 2 with controller 1 which adds the network settings and pool to controller 2.
Figure 14: Failover Sync To Peer

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.

Figure 15: Main Dashboard for HA Systems

Troubleshooting HA Installation

The failover feature on TrueNAS Enterprise platforms with High Availability (HA) can malfunction in network environments that heavily use the Spanning Tree Protocol (STP). When configuring or troubleshooting HA failover, if TrueNAS HA failover does not function properly, investigate STP use in the network and consider disabling STP on network switch ports connected to the TrueNAS platform.

If controller 2 comes online as the primary and controller 1 as the standby, you installed and configured the controllers incorrectly.

Go to System > Failover, clear the Default TrueNAS Controller option, and click Save. The system restarts and fails over to the current standby controller (in this case, to controller 1).
Log back into the UI with the VIP address. Go to System > Failover and select Default TrueNAS Controller to make controller 1 the primary controller.
Select Sync to Peer. TrueNAS makes controller 2 the standby controller and syncs the configuration on controller 1 to controller
Click Save.

Using the Console Setup Menu

The Console Setup menu displays at the end of the iso installation process and after the system boots up. You can access this menu to administer the TrueNAS system if it has a keyboard and monitor.

By default, TrueNAS does not display the Console Setup menu with SSH or web shell connections. The admin user, the root user (if enabled), or another user with administrator or root-level permissions can start the Console Setup menu by entering this command:

/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](/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](/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.

Figure 2: TrueNAS Console Setup Menu Edit Interface

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.

Figure 3: TrueNAS Console Setup Menu Edit Interface Settings

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.

Figure 4: TrueNAS Console Setup Menu Edit Network Settings

Enter 3 to display the Static Route Settings screen to set up static routes. You can also add static routes in the web UI.

Figure 5: TrueNAS Console Setup Menu Static Routes

Configuring Required Network Settings

TrueNAS uses DHCP to assign the IP address required to access the TrueNAS UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.

If you do not plan to use the DHCP-assigned network addresses provided by TrueNAS, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.

TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.

All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure TrueNAS.

To use the Console Setup menu to change the network interface IP address:

Type 1 and then press Enter to open the Configure Network Interfaces screen.
Use either Tab or the arrow keys to select the interface to use as your primary network interface if you have more than one interface installed and wired to your network.
Enter in the IP address, then use either Tab or the arrow keys to move through the menu and down to select Save, and then press Enter. After saving, enter q to return to the main Console Setup menu.

To configure the default gateway, host name, domain and DNS name severs using the Console Setup menu type 2 and then press Enter to open the Network Settings screen.

To configure network settings in the TrueNAS UI, enter the IP address displayed on the Console Setup menu screen in a browser URL field and press Enter. Log in with the admin user name and password set for the administration user during the iso installation process, and then go to Network to edit an interface or global network configuration settings.

Configuring Home User Network Settings

Home users have a few options to allow Internet access using TrueNAS:

Use 8.8.8.8 as the DNS nameserver address
Use your ISP provider DNS servers (contact them for assistance with these addresses)
Use 1.1.1.1 for Cloudflare
Use 9.9.9.9 for Quad9

Changing the Administrator Password

TrueNAS has implemented administrator account logins as replacements for the root user. The truenas_admin user account is the default account, and the root password is now disabled by default. If you migrate from FreeBSD- to Linux-based TrueNAS releases and need to upload the previous system configuration file, the root user password is not disabled but you must recreate the truenas_admin (or an admin) user account and disable the root password to comply with FIPS-compliance standards and security hardening practices.

Existing TrueNAS systems migrating from earlier TrueNAS release with the admin user retain this administrator account. Only a clean install using a TrueNAS 24.10 iso creates the truenas_admin administrator account. Both the earlier admin and new truenas_admin accounts have the same permissions and privileges. You can change the admin user password in the UI or from the Console Setup menu. You can set and enable the root user password in the UI, but for security hardening, we recommend leaving it disabled.

Changing an admin user (or root if you have not created the admin user) password disables 2FA (Two-Factor Authentication) 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.

Resetting the System Configuration

Caution! Resetting the configuration deletes all settings and reverts TrueNAS to default settings. Before resetting the system, back up all data and encryption keys/passphrases! After the system resets and restarts, you can go to Storage and click Import Pool to re-import pools.

Enter 5 in the Console Setup menu, then enter y to reset the system configuration. The system restarts and reverts to default settings.

Completing your System Setup

After setting up network requirements, log into the web UI to complete your system setup by:

[Completing network configuration] (/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 iso for the latest maintenance release of the target major version, then follow the migration instructions in Performing a Clean Install or use the UI update screen or download a manual update file then follow the instructions in Updating to 24.04 to move from the FreeBSD-based to the Linux-based version of TrueNAS.

TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.

Preparing to Migrate: Guides FreeBSD-based TrueNAS users through preparation elements and steps before beginning the one-way FreeBSD- to Linux-based TrueNAS migration process.
Community Migrations: Provides instructions for TrueNAS community users to migrate from FreeBSD- to Linux-based TrueNAS versions. Migration methods include using an ISO or manual update file.
Enterprise Migrations: Instructions for TrueNAS Enterprise users to migrate from FreeBSD- to Linux-based TrueNAS software.
Component Naming: Provides information on disk and interface naming changes related to the change from FreeBSD to Linux-based storage and sharing in TrueNAS.
(obsolete) ZFS Feature Flags Removed: (obsolete) Provides legacy information for users of a deprecated ZFS feature flag merged into TrueNAS 22.02 and removed in 22.12.

Preparing to Migrate

Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.
Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available release version, 13.0-U6.7 (or 13.3-U1.2 for community users), before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.

TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.

What can or cannot migrate?

Although TrueNAS attempts to keep most of your configuration data when migrating, some items do not transfer. These are the items that do not migrate:

Microsoft OneDrive Cloud Sync credentials and tasks. OneDrive compatibility is not available in TrueNAS.
FreeBSD GELI encryption. If you have GELI-encrypted pools on your system that you plan to import, you must migrate your data from the GELI pool to a non-GELI encrypted dataset or zvol before migrating.
Malformed certificates. TrueNAS validates the system certificates when a system migrates. When a malformed certificate is found, TrueNAS generates a new self-signed certificate to ensure system accessibility.
Plugins and jails. Save the configuration information for your plugin and back up any stored data. After migrating, add the equivalent application using the Apps option. If your plugin is not listed as an available application, use the Custom App option to add it and import data from the backup into a new dataset for the application.
NIS data.
System tunables.
ZFS boot environments.
SMB auxiliary parameters. As of TrueNAS 23.10 (Cobia), the Auxiliary Parameters option is no longer available in the UI as a configurable option. We recommend removing any auxiliary parameter settings before migrating.
AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
netcli utility. A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI. By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.
SAS multipath is not supported.
TrueNAS 13 account names beginning with a number are not supported in TrueNAS 24.04. Usernames must begin with a letter or an underscore. Before attempting migration, review the local user accounts and rename or replace any accounts that begin with a numeric character (0-9).

TrueNAS 13.X and earlier support VMs with UEFI and GRUB bootloaders. TrueNAS 22.02 and later does not support the GRUB bootloader. VMs configured with the UEFI bootloader can migrate. VMs configured with the GRUB bootloader are unable to migrate.

It is important for all users to double-check the VM configuration and network interface settings before starting the VM.

If VMs need to access local NAS storage, you need to create a network bridge and assign it to the VM. Applications or sandboxes that need access to local storage within the container must use a bridge or mount a local storage location as a host path for the application.

Init/shutdown scripts transfer, but can break. Review them before use.

Preparing for Migration

Read this article before you attempt to migrate your FreeBSD-based system to a Linux-based TrueNAS version.

We strongly recommend not using USB flash drives or USB-attached drives for backups as these can have issues, including with recovering backed-up files. For more information on using USB drives and devices in general, read the Hardware Guide.
If you must use a USB-type device, verify you can access files on the device before you migrate.

TrueNAS Enterprise
We strongly encourage Enterprise customers to contact Support for assistance moving from a FreeBSD-based (13.3 or earlier) to a Linux-based (22.12 or newer) TrueNAS version, especially customers with HA systems using iSCSI shares or fibre channel. Enterprise customers should not attempt to migrate their HA systems with iSCSI or fibre channel on their own! Enterprise systems with iSCSI and fibre channel deployments require complex, special preparation and migration steps executed before and after migration to ensure data integrity. Please contact Support for assistance!

Upgrade your system to either the latest 13.0 or 13.3 release. TrueNAS Enterprise-licensed (or community systems that haven’t switched to 13.3) systems on 12.0x or earlier should upgrade to the latest 13.0 release before migration. Community users with 13.3 installed should update to the latest maintenance release of that version before migration. Either major version can use the iso upgrade method for migration.
Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from TrueNAS 12.0x or earlier releases! If you do not migrate from GELI to ZFS encryption before upgrading to 13.0-U6.2 (or newer) or migrating to TrueNAS 24.04 (or newer), you permanently lose access to the data in the GELI-encrypted pool(s).
Verify the root user is not locked. Go to Accounts > Users, select the root user, and click Edit to view current settings and confirm Lock User is not selected.
Write down, copy, or take screenshots of settings to duplicate after migrating or use in the event of a post-upgrade/migration issue. Use the checklist below to guide you through this step:
System dataset - Identify your system dataset. If you want to use the same dataset for the system dataset after migrating, note the pool and system dataset. When you set up the first required pool after migrating, import this pool first.
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.

TrueNAS Enterprise
Enterprise customers using iSCSI with ALUA or fibre channel ports should contact Support for assistance with migrating their systems. These features require careful configuration to avoid data corruption or loss of data.

After completing the steps listed above that apply to your existing system, download the latest TrueNAS ISO file and save it to your computer. See Software Releases for currently recommended update paths to make sure you download and migrate to and from the correct TrueNAS versions. Burn the iso to a USB drive (see Installing on Physical Hardware) when upgrading a physical system.

Deprecated Services

The built-in services listed in this section are available in 13.0 but deprecated in 22.12.3 (Bluefin) and removed in later TrueNAS releases. They require attention before attempting to migrate to 24.04 or later.

Each of the sections has information that can help you determine the best steps forward to secure any critical data before attempting to migrate. They provide details on transitioning from that service to an application with the functionality of the deprecated service.

TrueNAS has apps you can deploy as replacements for these services. TrueNAS provides the option to force an upgrade without converting deprecated services to apps. The force option is not recommended for the S3 service as forcing the upgrade results in losing access to and the ability to recover the MinIO S3 data.

See Bluefin Deprecated Services for more information.

Migrating from DDNS Service

Review and write down or take screenshots of your Dynamic DNS service provider, domain, IP address, port number, URL, and credential (username and password) settings to use when you reconfigure in a replacement app. If establishing a new provider, create the user account before proceeding. Otherwise, use the existing provider details.

To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user. Note the UID and GID for this new user to enter in the application configuration screen.

Install a replacement application, such as DDNS-Updater, using the service settings from your notes.

Migrating from OpenVPN Service

Review your OpenVPN client and server service settings. Take note of all certificates, device type, port, protocol, TLS crypt authentication, and additional parameter settings to use in a replacement app.

A configured certificate should migrate, but as a precaution, record the certificate authority (CA) and certificate settings, and make a copy of the private and public keys the CA and certificate uses.

Install a replacement application, such as WG Easy, using the service settings from your notes.

Migrating from Rsync Service

Review your rsync and module service settings. Take note of all host path, access mode type, number of simultaneous connections, user and group IDs, allow and deny host addresses, and any auxiliary parameter settings.

Before you configure a new rsync application like Rsyncd, validate that it is needed. When rsync is configured externally with SSH or using an rsync task in Data Protection > Rsync Tasks, and when Rsync Mode is set to SSH, the deprecated rsync service is not used or necessary for rsync to function.

Install a replacement application such as Rsync Daemon using the 13.0 service settings from your notes. TrueNAS 24.10 suggests other applications to consider other than the Rsync Daemon application.

Migrating from TFTP Service

Review your TFTP service settings. Take note of all directory, host, auxiliary parameter, permission, and credential (username and password) settings.

To grant access to a specific user (and group) other than using the default admin user UID and GID, add the new non-root administrative user. Note the UID and GID for this new user to enter in the application configuration screen.

To use a specific dataset or storage volume for files, create a new dataset before installing the application. Install the replacement application, such as TFTP Server (TFTP-HPA), using the service settings from your notes.

Migrating from WebDAV Service and Shares

Disable both the WebDAV share and service. Also, disable the Start Automatically option to prevent the service from re-enabling after a system restart.

Review any existing WebDAV service authentication settings. Take note of all IP addresses, port numbers, URLs, and credentials (username and password).

Remove any existing WebDAV shares. Go to Shares > WebDAV and use Edit to view any existing configurations. Take note of the share name, path, and read-only settings. Delete the WebDAV share configuration.

In Bluefin: To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user for the share(s). Note the UID and GID for this new user to enter in the application configuration screen.

After disabling the WebDAV service and clearing any existing share configurations from the Shares > WebDAV screen in Bluefin, install the WebDAV application to recreate your shares using the service settings from your notes. Use the webdav user and group in control, and the UID and GID (666) in the application.

Community Migrations

Migration Overview

This article provides information and instructions for migrating non-Enterprise FreeBSD-based TrueNAS versions (13.0 or 13.3) to Linux-based TrueNAS (22.12 and later).

TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.
The process requires an extended maintenance window, requires executing steps in the correct order to prevent issues with system configuration and operation, and additional system review post-migration to catch and correct any configuration issues.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Migration Preparation

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.

Migration Methods

Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.
Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available release version, 13.0-U6.7 (or 13.3-U1.2 for community users), before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.

TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.

For all migration methods, you must upgrade to the latest maintenance release of TrueNAS 13.0 or 13.3 before attempting to migrate. See Software Releases to confirm the latest version.

Performing a Clean Install

To migrate directly from TrueNAS 13.0 or 13.3 to the latest TrueNAS Community Edition release (24.10 or later), perform a clean install using an iso file for the target version. After obtaining a file from the Software Releases page or Download TrueNAS Community Edition follow the instructions in Installing TrueNAS to install TrueNAS Community Edition.

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.

Updating to 24.04

You can migrate from TrueNAS 13.0 or 13.3 to 24.04 using either the update train method or a manual update file. After migrating, you can follow the standard update process to step through each major release until you reach the latest version.

Select Update Train

This method is only available for non-Enterprise community systems.

To migrate to TrueNAS 24.04 using the UI Update screen and Train selector:

Go to System > Update
From the Train dropdown, choose the latest stable TrueNAS release, 24.04 (Dragonfish) or newer.
Review the TrueNAS migrations warning and verify the system is ready to migrate before confirming and continuing.
When the latest update for that chosen TrueNAS release is loaded, click Apply Pending Update or Download Updates to begin the update process documented in Updating TrueNAS. It is strongly recommended to download the system configuration backup prior to starting the update.
After the system installs the update and restarts, log in and review the system configuration to ensure the migration was successful.

Manual Update

To migrate to TrueNAS 24.04 using the UI Update screen and a TrueNAS 24.04 update file:

If this process fails, retry using the iso file method above.

Confirm that the system is on the latest public release of TrueNAS 13.0 or 13.3.
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.
Figure 1: Install the Manual Upgrade
Click SAVE CONFIGURATION to download a backup file that can restore the system configuration in the event something goes wrong with the migration.
Figure 2: Save the Config file
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.
Figure 3: Settings for the Manual Upgrade
Then click APPLY UPDATE.
After the update completes, restart the system if it does not restart automatically.
Figure 4: Restart to Finish

Restoring Configuration

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.

Do I need to upload a config file?

Uploading a config file after a TrueNAS migration or fresh install makes it easy to migrate most system settings with one click.
However, you can choose to manually recreate the previous configuration if desired or if some part of the previous configuration causes conflicts with a later TrueNAS version.

If you choose to manually recreate settings, carefully document your original configuration and ensure each setting is recreated exactly. For example, re-creating a user account named bob after migration does not restore access to existing datasets for the bob user account unless the new account uses the same UID or you manually update the dataset ACLs to grant access.

Recreating the Admin User Account

Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.

The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations. Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin). Configure appropriate administrative privileges for each admin account. Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user. If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete. See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s). Go to Credentials > Users, click on the user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.

Enterprise Migrations

TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.

The process requires:

Backing up critical data.
An extended maintenance window.
Executing the migration process in a precise order.
Additional system configuration to update network interfaces and add new administrator accounts.

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
Email	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.

Disks

TrueNAS 13.3 or earlier utilizes a numerical listing of drives in a system.

ComponentNamingDrivesCore

TrueNAS 22.12 or newer uses a lettered format for drive identification.

ComponentNamingDrivesSCALE

TrueNAS 22.12 or newer still labels NVMe drives with a numeric value.

Interfaces

TrueNAS 13.3 or earlier enumerates interface names using interface drivers, such as igb for Intel devices, followed by a number. TrueNAS 13.3 or earlier Enterprise systems use ix followed by a number.

NetworkInterfacesScreen

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.

NetworkInterfacesWidget

TrueNAS 13.3 or earlier identifies bonded interfaces or link aggregations with lagg followed by a number (lagg1). TrueNAS 22.12 or newer uses bond followed by a number (bond1).

See the Products section for lists of the default port names for each platform.

(obsolete) ZFS Feature Flags Removed

This content is obsolete and no longer relevant to TrueNAS users. Please refer to major version release notes for updates concerning ZFS feature flags.

Third-Party Data Migration

Users of TrueNAS 24.04 (Dragonfish) or newer can migrate data from a third-party NAS solution onto TrueNAS using the Syncthing Enterprise application. The Syncthing Enterprise application can mount remote SMB shares in a manner that preserves relevant metadata. TrueNAS 24.10 (Electric Eel) also adds migration support for SMB alternate data streams (ADS), used to store application-specific metadata.

Syncthing Overview

TrueNAS Enterprise
Third-party data ingest is available to TrueNAS Enterprise customers with TrueNAS 24.04 (Dragonfish) and newer deployed, as well as the appropriate applications license. TrueNAS Enterprise Support staff are available to assist with deploying the Syncthing Enterprise Application and migrating data. Please contact TrueNAS Enterprise Support to learn more and schedule a time to deploy the app and begin migration.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Before You Begin

Data migration from a third-party NAS requires advanced configuration of both the remote source and TrueNAS target.

Ensure the source NAS supports the SMB protocol version 3 or newer. Older versions of the SMB protocol are not supported.
Plan for one-way migration of data from the source to the TrueNAS target. Remote shares must be mounted read-only. Read-write configuration or bidirectional synchronization is not supported.
Configure both source and target systems with directory services and synchronize accounts.
All accounts referenced in NFSv4 ACLs and Windows Security Descriptors must be available on the TrueNAS server.
The remote NAS must not have any security information that references local NAS accounts rather than domain accounts. Remove ACL entries that reference local accounts or non-domain users and groups before migration.
Mounting a remote NAS for data ingest purposes without a common identity source and agreement in place for handling local accounts is an unsupported configuration.

Process Overview

The process of setting up data migration from an external NAS to TrueNAS consists of:

Installing two instances of the Syncthing Enterprise app, configuring the first instance to ingest data from the external source and the second instance to write data to a local dataset on the target system.
Creating the target dataset for the data ingest on TrueNAS.
Configuring a Syncthing marker folder on the remote source.
Connecting the two Syncthing instances and initiating data sync.

Setting Up Data Migration

Install the first instance of the Syncthing Enterprise app on TrueNAS.
a. Go to Apps > Discover Apps, locate the Syncthing enterprise app widget.
Figure 1: Syncthing Enterprise App Widget
Ensure the widget reflects the Enterprise train version of the app. If the Enterprise version is not available, add the Enterprise train to the TRUENAS catalog.
Adding Enterprise Train Apps
Click on the widget to open the Syncthing details screen.
Figure 2: Syncthing Enterprise 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.
Figure 3: Additional Storage - SMB Share
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.
Figure 4: Add Folder - General
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.
Figure 5: Settings - INGEST
Enter a clear identifying name, such as INGEST, and click Save.
Create a new dataset on TrueNAS to be the target for the data ingest, for example, /mnt/tank/ingest. This dataset serves as the migration destination for both Syncthing instances.
Click Advanced Options and set ACL Type to SMB/NFSv4. Set ACL Mode to Restricted.
```
These ACL settings are required on the migration target dataset. If using an existing dataset, verify these settings are configured before proceeding.
```
Install the second instance of the Syncthing Enterprise app on TrueNAS.
a. Go to Apps > Discover Apps, locate the Syncthing enterprise app widget. Ensure the widget reflects the Enterprise train version of the app.
b. To avoid name conflicts, use a unique name to indicate this Syncthing instance is writing to a local dataset. For example Syncthing-migrate.
c. Accept the defaults in Version, Syncthing Configuration, and User and Group Configuration.
d. Disable Host Network under Network Configuration. Use non-default ports for this Syncthing instance that differ from the configured ports on the first instance.
e. Select ixVolume (Dataset created automatically by the system) or configure an existing host path for Syncthing Home Storage under Storage Configuration.
f. Select Host Path (Path that already exists on the system) from the Type dropdown for Additional Storage. Enter or browse to select the Host Path for the target dataset created in step 3.
Figure 6: Additional Storage - Host Path
g. Click Install.
The Installed Applications screen displays both Syncthing instances.
Figure 7: Installed Applications
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.
Figure 8: Settings - MIGRATE
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.
The address requires // after tcp:. Entering tcp:*ip*:*port* without the slashes fails with a misleading error.
Figure 9: Add Device - Advanced
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.
Figure 10: Edit Folder - Sharing
Click Sharing and select the migrate instance. Click Save.
Syncthing begins syncing data from the remote source to the ingest dataset on TrueNAS.

Configuration Instructions

This section provides instructions for users that are configuring TrueNAS for the first time.

TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial set up and configuration of their systems.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

After completing the installation process, you can either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the TrueNAS UI to make network changes and complete the initial configuration.

Configuring your system includes:

Setting up your first pool
Setting up data sharing
Setting up backup for the system and your stored data

Configuration Articles

Logging In for the First Time: Describes the web interface, logging in to the TrueNAS web interface for the first time, changing from root to the admin user, and navigating through the UI.

Configuring TrueNAS Using the UI: Provides a sequential process to complete the initial configuration using the TrueNAS UI.

Setting Up Storage: Provides basic instructions for setting up your first storage pool and dataset or zvol.

Setting Up Data Sharing: Provides general information on setting up basic data sharing on TrueNAS.

Backing Up TrueNAS: Provides general information and instructions on setting up data storage backups, saving the system configuration and initial system debug files, and creating a boot environment.

Configuring Virtualization and Apps: Provides general information on setting up virtual machines and applications in TrueNAS.

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.

Web Interface Access

TrueNAS automatically creates several ways to access the UI, but you might need to adjust the default settings for your network environment.

By default, a fresh install of TrueNAS provides a default address for logging in to the web interface. To view the web interface IP address or reconfigure web interface access, either connect a monitor and keyboard to your TrueNAS system or connect with IPMI for out-of-band system management.

When powering on a TrueNAS system, the system attempts to connect to a DHCP server from all live interfaces to access the web UI. On networks that support Multicast Domain Name Services (mDNS), the system can use a host name and domain to access the TrueNAS web interface. By default, TrueNAS uses the host name and domain truenas.local. To change the host name and domain in the web interface, go to Network and click Settings on the Global Configuration widget.

To access the web interface using an IP address, either use the DHCP-assigned IP address displayed at the top of the Console Setup menu after installing TrueNAS or use the static IP address you assigned using the Console Setup menu.

TrueNAS Enterprise
TrueNAS Enterprise (HA) systems have specific network configuration requirements. Installing TrueNAS on High Availability (HA) systems and configuring networking is complicated and should be guided by Enterprise-level support. Contact TrueNAS Enterprise Support for assistance whenever attempting to install TrueNAS on Enterprise HA hardware or configure network settings.
Refer to the Preparing for TrueNAS UI Configuration (Enterprise) and Installing TrueNAS Enterprise (HA) for information on installing HA system and configuring networking.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Logging Into the TrueNAS UI

Use a computer with access to the same network as the TrueNAS system. Enter the host name and domain or IP address assigned to the primary network interface in a web browser to connect to the TrueNAS web interface.

The browser used to access the TrueNAS UI can impact the quality of your user experience. We generally recommend using Firefox, Edge, or Chrome.

Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.

The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations. Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin). Configure appropriate administrative privileges for each admin account. Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user. If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete. See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s). Go to Credentials > Users, click on the user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.

With the implementation of administrator accounts, the root user is no longer the default administrator username.

Based on the method used to install TrueNAS, you can be presented with different first-time login scenarios, each described below.

Clean Installing TrueNAS

When installing TrueNAS from an iso file, and based on the authentication method selected in step 4 of the TrueNAS installer process, you can see a different sign-in screen for the web UI and need to use different login credentials.

Selecting 1. Administrative user (truenas_admin) opens the standard TrueNAS sign-in screen where you enter the new truenas_admin username and password created during installation. The root user password is disabled by default. We recommend this option, as it creates the required administrative user and disables the root user password, and which brings the system into compliance with FIPS security hardening standards.
The root user still exists but with the password disabled by default, which means only the truenas_admin user can log into the system. You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Selecting 2. Configure using Web UI opens a TrueNAS sign-in screen with two options. Select the option to either create the admin or root user and password.
If creating and logging in as the admin user, after logging in you must immediately disable the root user password to comply with FIPS security hardening standards.
If creating and logging in as the root user, after logging in you must create the admin user and then immediately disable the root user password to comply with FIPS security hardening standards. The root user still exists but with the password disabled by default, which means only the admin user can log into the system. You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.

Upgrading from TrueNAS Early Releases

Early Linux-based releases of TrueNAS (Angelfish and pre-22.12.3 Bluefin release) use the root user credentials to log into the system. After upgrading from an earlier release, use the existing root user credentials to log into TrueNAS.

After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.

The root user still exists but with the password disabled by default. This means only an administrative user can log into the system.

You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.

Migrating/Upgrading from FreeBSD- to Linux-based TrueNAS Versions

TrueNAS Enterprise
Customers with a TrueNAS Enterprise High Availability (HA) system should review Migration Preparation, Enterprise HA Migrations, and consult with TrueNAS Enterprise Support prior to migrating.

For non-HA systems, there are two possible scenarios when migrating:

Clean installing TrueNAS using the iso file and then uploading the previous configuration file.
Using the 13.0 (or 13.3 for community users) Update UI option to upgrade.

If performing a clean install using the TrueNAS iso file, after installing TrueNAS and uploading the configuration file, your network settings get overwritten by the config file, so you cannot use the new IP address and admin user to access to the web UI. Use the previous address and root credentials to access the UI. See TrueNAS Migrations for instructions on recovering the new network settings and access to the UI, and recreating the administrator account.

If using the Update UI option, log into TrueNAS with the existing root user credentials.

After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.

The root user still exists but with the password disabled by default. This means only an administrative user can log into the system.

Logging In as Truenas_Admin

After setting up the truenas_admin user from one of the scenarios documented above, enter truenas_admin and the password to log in.

To modify user credentials, go to Credentials > Users, click anywhere on the user row, then click Edit. For more information, see Managing Users.

Logging In as Root

If logging in with the root user credentials, enter root as the user and the root password.

After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.

The root user still exists but with the password disabled by default. This means only an administrative user can log into the system.

Follow the directions in Managing Users to create an administration user with all required settings. For environments requiring specific configurations, such as non-AD environments or those using LDAP, ensure that your admin user is properly set up to manage all aspects of the system.

Creating an Administrator Account at First Log in

If you selected the installation option 2. Configure using Web UI, the sign-in screen shows two authentication methods. One allows you to log in as root or you can create the administration account.

Figure 2: TrueNAS Login Set Up Authentication Method

Select either the Administrative user or Root user (not recommended) option, then enter the password to use with that user.

If you choose Root user (not recommended) as the TrueNAS authentication method, go to the Credentials > Users screen and create the admin account immediately after you enter the UI. Enter the admin user name and password, make sure the password is enabled, and click Save. After setting up the admin user, click on the root user and then click Edit. Disable the root user password and then click Save. This brings the system into compliance with FIPS system security-hardening standards.

Troubleshooting Accessing the Web UI

If you cannot remember the administrator password to log in to the web interface, connect a keyboard and mouse to the TrueNAS system and open the Console Setup menu to reset the administrator account password.

UI is not accessible by IP address

If the user interface is not accessible by IP address from a browser, check the following:

If the browser configuration has proxy settings enabled, disable them and try connecting again.
If the page does not load, ensure a ping reaches the TrueNAS system IP address. If the IP address is in a private range, you must access it from within that private network.

UI displays but seems unresponsive

If the web interface displays but seems unresponsive or incomplete:

Make sure the browser allows cookies, Javascript, and custom fonts from the TrueNAS system.
Try a different browser. We recommend Firefox, Edge, or Chrome.

If the UI becomes unresponsive after an upgrade or other system operation, clear the site data and refresh the browser (Shift+F5).

Introducing the TrueNAS Dashboard

After logging in for the first time, the main system Dashboard screen displays. The Dashboard shows different system information cards (widgets) with basic information about the installed version, systems component usage, network traffic, and configured pools or storage usage. The dashboard includes configurable widgets that include a text-only Custom widget and an Apps widget you can configure to monitor your installed applications.

TrueNAS Enterprise users with an iXsystems-provided server also see an image of the system in the System Information widget. Click on the system image to open the System > View Enclosure screen.

The Dashboard for non-Enterprise systems displays the TrueNAS logo on the System Information widget.

To customize the dashboard , click Configure to put the Dashboard into configuration mode. Use the drag bar to move widget groups to new positions on the screen. Click Add to create new widgets or the Edit option in the widget group to change the look or information included in a widget.

Figure 4: Dashboard in Configuration Mode

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.

Searching UI Fields

Click the Search UI bar or type Ctrl + / to select the UI global search.

Entering a Query

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.

Navigating Results

Select a screen result under UI to go to the matching screen within the TrueNAS UI. For example, select Shares 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 SMB Add SMB Share to locate to the Add button on the SMB screen.

Figure 9: Global Search Result - Element

TrueNAS indicates the selected element with a glow effect.

Searching TrueNAS Documentation

Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub. TrueNAS opens a new browser tab to display documentation search results for the query.

Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.

TrueNAS

The TrueNAS logo returns to the Dashboard from any other screen.

Send Feedback

TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.

To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window. Alternatively, go to System > General Settings and click File Ticket on the Support widget.

Rating a UI Screen

Click Rate this page to send feedback on a UI page. You can include a screenshot of the current page and/or upload additional images with your comments. You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.

Reporting an Issue

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.

Reporting an Issue - Enterprise Licensed Systems

TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Figure 14: TrueNAS Enterprise Bug Report Form
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.

Figure 20: TrueNAS Connect Dialog Connected

Click Open TrueNAS Connect to open the TrueNAS Connect management interface. Click 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 info 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 assignment 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 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 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 notifications 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 settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.

Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you. See Alerts Settings Screens for more information.

TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.

Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.

Alerts Admonitions

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 account_circle icon opens a dropdown list of options to change passwords, modify two-factor authentication settings (when configured), create and manage API keys, access the TrueNAS documentation, and to log out of the TrueNAS UI.

Change Password

Click on the Change Password dialpad 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.

Figure 27: Change Password - Full Control Admin

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.

Figure 28: Change Password - Share and Readonly Admins

Click on the visibility_off icon to display entered passwords. To stop displaying the password, click on the visibility icon.

My API Keys

Click on My API Keys laptop to go to the User API Keys screen. API keys identify an outside resource or application without a principal. For example, when adding a new system to TrueCommand if you are required to add an API key to authenticate the system. Use this function to create an API key for this purpose.

Click API Docs to access the API documentation portal with information on TrueNAS API commands.

See API Keys for more information on adding or managing API keys.

Guide

Click on Guide library_books to open the TrueNAS Documentation Hub in a new tab.

Log Out

Log Out logs the current user out of the TrueNAS UI, but does not power off the system. The Read-Only Admin and Sharing Admin roles only have access to the Log Out option.

Power Options

Click the Power power_settings_new button to open the dropdown list of power options. Restart logs you out of the TrueNAS UI and restarts the server. Shut Down logs you out of the TrueNAS UI and powers off the system as though you pressed the power button on the physical server.

TrueNAS Enterprise
Please consult your specific hardware documentation to find notes about possible hardware-specific controls for power-on or off behaviors.

With the implementation of administrator roles, the power options are locked based on the level of privileges for the administrator role. The full administrator has access to both power options, but read-only and sharing admin roles do not. The power options that show a lock icon indicate the function is not permitted.

Managing Sessions

To monitor and manage all active sessions, go to System > Advanced Settings and locate the Access widget.

Next Steps

With access to the TrueNAS web interface and all the management options, you can begin configuring your system!

Configuring TrueNAS Using the UI

TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support after their system(s) arrive to receive additional guidance on the next steps.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

TrueNAS users should follow the instructions provided below to complete the initial system setup and configuration.

Use the information mentioned in the installation preparation instructions article for your TrueNAS installation type (Enterprise, non-Enterprise, or home use) to configure your network, SMTP, or directory service settings.

Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.

After logging into TrueNAS, you can begin configuring TrueNAS using the web interface.

Enterprise Licenses and Proactive Support

TrueNAS Enterprise
Applying Enterprise Licenses
TrueNAS Enterprise customers should contact Support to obtain their TrueNAS system license information. To apply the license information, go to the System > General Settings screen and use the Update License option on the Support widget (system information card).
Setting up Proactive Support
TrueNAS Enterprise customers with Silver or Gold Coverage support contracts can configure proactive support.
Customers with appropriate support contracts can configure Proactive Support after they apply their system license, and after acknowledging and signing the End User License Agreement (EULA).
After entering your system license, the Proactive Support option shows on the Support widget on the System > General Settings screen.

Setting Up Networking

TrueNAS uses DHCP to assign the IP address required to access the TrueNAS UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.

TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide to TrueNAS Support when they guide you through your configuration.

All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure TrueNAS.

We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the TrueNAS UI to configure your network interfaces and other network configuration settings. The TrueNAS UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS if you make a mistake with network interface settings.

If you are unfamiliar with network services, devices, or configurations, you can find more information here to help guide you through this important and required configuration area.

TrueNAS Enterprise
You must disable failover in the UI on TrueNAS Enterprise HA systems to add or change any network setting. Complete network changes and test them, then re-enable failover.

Adding Network Interfaces

Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (bond) or network bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance. However, ethernet network topology allows only one interface to communicate at a time. Additionally, both interfaces must handle broadcast messages since they are listening on the same network. This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation configured with Link Aggregation Control Protocol (LACP). A single link aggregation (bond) interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups. LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network. If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.

If your system has more than one network interface card (NIC) connected to your internal network (wired to your router or Internet access point), you can add an interface in TrueNAS. DHCP is only available for a single interface; all other physical interfaces must be manually configured with static IP addresses.

TrueNAS allows configuring virtual network interfaces such as a bridge, link 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.

Adding Aliases or Static IP Addresses

Static IP addresses and aliases provide support for various network applications.

TrueNAS Enterprise
TrueNAS Enterprise HA systems use a virtual IP (VIP) to maintain access to the UI when the system fails over to the standby controller. This VIP address might experience a minor blip at failover, but you do not need to log in with the standby controller IP address to gain access to the UI after a failover.

The Add Interface screen allows configuring a network interface with a static IP address or adding an alias IP address. For more information on when to use an alias or a static IP address, see Managing Interfaces.

Setting Up Storage

TrueNAS requires at least one storage pool. We recommend creating the required pool, then planning the rest of your storage needs before adding sharing, container applications, virtual machines, or storing data. When planning your data storage, consider the type of data sharing you want to do, any container applications you might want to deploy, and how you want to organize stored data.

The storage creation process begins with creating a pool, then adding datasets or zvols as needed. Creating your initial storage is explained here.

Setting the System Dataset

TrueNAS assigns the root (parent) dataset of the first created pool as the system dataset. If your system has enough disks to add more pools, you can change the system dataset to a root dataset of another pool.

Setting Up Shares

After setting up system storage, configure data sharing using one of the sharing protocols available in TrueNAS.

These articles provide more information on the three built-in share types available in TrueNAS and configuring data sharing:

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.

Configuring System Services

Configure and enable the services based on what is deployed on your TrueNAS system.

TrueNAS Enterprise
TrueNAS Enterprise HA systems should enable and configure the failover service.

Configuring Services

Configure and enable these services based on your TrueNAS system needs:

SSH service

Set the service to allow SSH login for administration users (admin or, if also enabled, the root user) on all TrueNAS systems. All TrueNAS systems that need SSH access should enable SSH service as part of the initial UI configuration, but this is an area of security vulnerability. To security-harden your system, do not enable SSH and leave it activated at all times. Enable the service when SSH access is needed and then disable it until needed again.

SSH User Validation
Users must have a home directory and shell access to log in with SSH.

Failover service on TrueNAS Enterprise High Availability (HA) systems

The failover service enables an HA system to fail over to the standby system controller after a disruption to the primary controller. This service is not included in non-Enterprise and non-HA systems.

Enterprise customers should not change failover settings or the service on their own, except when disabling failover to make network settings changes. Contact TrueNAS Enterprise Support for assistance before making changes to other failover settings.

When adding data sharing, the system prompts you to enable the appropriate sharing service as part of the configuration and setup process.

If your installation includes a UPS, configure and enable the UPS service.

Exiting Configuration Screens Without Saving

TrueNAS allows exiting a configuration screen without saving, but asks if you want to exit without saving before closing it. After opening a configuration screen and changing or entering a setting, when you click away from the screen or on the X at the top right of the screen, a dialog opens and asks if you are sure you want to exit the screen.

To close without saving, click Yes or No to continue making changes or entering values.

Setting Up Backup Solutions

After completing your initial system configuration and before beginning day-to-day operations, we recommend configuring the system and data storage backup methods. The best practice for critical data is to use more than one solution or method to back up your data in case one method fails. Recommended minimum system backup options:

Save 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.

Why should I save the secret seed?

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 break due to the missing information. Examples are SMB via local accounts and apps. Always select the option to save the secret seed when downloading the system config file!

Note, the secret seed does not store local users passwords in any form, only a hash of the password sufficient for authentication. Hashed passwords are not encrypted.

What happens if I do not save the secret seed? You might be prompted to enter a default password or reset the password. The UI should allow users to log into the system with their current password but might be prompted to enter a new password. Users can connect a keyboard and monitor to the system and enter a new password if they cannot log into the web UI or reset the current password.

Is there a default password for the system? Enterprise users are issued a password to enter if prompted for such a password after the system resets. Community users are not issued a default password and the system does not generate a default password for this purpose. If you cannot log into the UI with the current administration password, connect a keyboard and monitor to the system server to reset the password.

After logging into the system, recheck all system settings to verify the configurations are correct, and then test to verify the system is working as desired. When complete and the system is operating per the desired configuration, download and save the system configuration with the secret seed option selected and keep it in a secure location.

It is a best practice to always save the secret seed with the system configuration file after making system configuration changes to have a current backup copy to use should the need arise.

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.

TrueNAS Enterprise
For Enterprise customers with High Availability (HA) systems, the HA restore process requires recovering both controllers. Contact TrueNAS Enterprise Support for assistance before attempting to recover your system. If you choose to restore access to the active controller 1 and the TrueNAS UI, contact TrueNAS Enterprise Support for assistance with properly recovering your second standby controller.
Enterprise HA customers should not start issuing CLI commands to recover the system!
Contact TrueNAS Enterprise Support after restoring access to controller 1 to request further assistance and before taking actions that can disrupt or damage system access and might result in a complete reinstall to recover.
Contact TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Data Storage Backup Solutions

After saving system configuration and debug files, we recommend setting up data storage backups using any or all of the following methods:

Taking regular snapshots or creating periodic snapshot tasks
Setting up replication to another system (remote replication)
Adding a cloud storage provider service and setting up a cloud sync task

You can take single snapshots or schedule periodic snapshot tasks to capture changes to stored data without the storage overhead that comes with backing up through data replication, or you can use one of the replication options TrueNAS provides.

Another option is to create a cloud storage service provider account and then let TrueNAS manage the backups to that account. Use the Backup Credentials screen Cloud Credentials to add authentication credentials for a supported cloud service provider, and go to Data Protection to schedule a Cloud Sync Tasks that regularly backs up your storage data to the cloud.

Having a secondary backup solution for critical data is a best practice! When backing up critical data to a cloud service provider, consider backing up the data to a remote server or a secondary cloud storage service as a protection against unforeseen failures with the primary backup solution.

Checking System Alert Settings and Services

You can view system alerts, configure an alert service, and enter an email account to receive alerts from TrueNAS from the Alerts screen accessed by clicking the Alerts icon on the top toolbar.

Configuring Alerts

The alert icon on the top toolbar shows a red circle with a number in it if TrueNAS encounters a configuration error or exceeds a threshold that you set (such as a temperature or a usage level). The number indicates how many new alerts occurred. Click on the alert icon to open the Alerts panel.

The Alerts panel Settings (gear) icon opens the Alert Settings screen where you configure the alert types and thresholds. The system email option opens a configuration screen where you enter an address to receive messages for a system event triggered by an alert.

Click Alert Settings to configure an alert service such as PagerDuty or customize alert settings such as type and threshold for triggering an alert.
Click Email to assign an email address to receive system alert notifications.

TrueNAS Enterprise
The Alert Settings screen includes access to Enterprise HA setting options that customize HA-related event thresholds that produce alerts or send emails.
Enterprise systems with FIPS and STIG enabled include alert settings to customize the event thresholds that produce alerts or send emails.

Setting Up Directory Services

TrueNAS allows configuring an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings. TrueNAS allows configuring either directory server but not both.

We do not recommend switching between directory services. This can result in configuration issues that can disrupt your system!
However, it is possible to change from one directory service to another. To migrate from LDAP to Active Directory, first, disable LDAP in TrueNAS, and then remove the current directory server settings. To change from Active Directory to LDAP, use the Leave Domain option, and then disable the service before attempting to configure and enable LDAP.

TrueNAS Enterprise
TrueNAS Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the information customers provide, but do not configure customer Active Directory system settings.

Non-enterprise users can find support for configuring directory services in the TrueNAS Documentation Hub tutorials or the community forums.

Using Enclosure Management

TrueNAS Enterprise
The TrueNAS main Dashboard displays an image of the TrueNAS system server on the System Information widget for TrueNAS Enterprise customers with compatible hardware. Click on the image to open the View Enclosure screen, or select the System > Enclosure option on the main menu navigation panel.
The View Enclosure screen provides details on system disks, pool and VDEV disks, disk hardware details, and disk status. Click on a drive to view disk details. If the TrueNAS system has an expansion shelf, the Enclosure screen also shows an image of the expansion shelf populated with disks.

If using TrueNAS on hardware not provided by TrueNAS, the System Information widget on the Dashboard displays the TrueNAS logo, and the System > Enclosure option does not exist on the menu navigation panel.

Using Applications in TrueNAS

TrueNAS shows a list of deployable applications on the Apps > Discover screen. See the TrueNAS Apps Market for information on deploying and managing apps, app catalogs and images, including custom apps, and specific catalog app resources.

Updating TrueNAS

You can update your system with an iso file using the system Console Setup menu or with an update file installed through the TrueNAS UI.

There are a few ways to find available updates for your instance of TrueNAS:

The Software Releases article in the TrueNAS Documentation Hub shows upgrade paths, and provides links to available releases and updates.
The main Dashboard > System Information widget shows when a TrueNAS update is available to download and install. Click the update option to open the System > Updates screen.
Go to System > Updates to check if an update is available.

For all update options and procedures using the TrueNAS UI see Updating TrueNAS.

Always save a system configuration file and a new boot environment for your current release and configuration before updating to a new incremental or full release.

It is also good practice to download a debug file before and after a system update.

Setting Up Storage

Now that you are logged in to the web interface, it is time to set up TrueNAS storage. These instructions describe a simple mirrored pool setup, where half the selected disks are used for storage and the other half for data protection. However, there are many configuration possibilities for your storage environment!

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.

Minimum Storage Requirements

At minimum, the system needs at least two disks of identical size to create a mirrored storage pool. While a single-disk pool is technically allowed, it is not recommended. The disk used for the TrueNAS installation does not count toward this minimum.

You can configure data backups in several ways and have different requirements. Backing data up in the cloud requires a 3rd party cloud storage provider account. Backing up with replication requires you to have additional storage on the TrueNAS system or (ideally) another TrueNAS system in a different location. This approach leverages persistent storage for overall data protection.

Setting Up Storage

Your system must have at least one storage pool configured.

After installing TrueNAS, enter the IP address assigned by DHCP (displayed in the Console Setup Menu) into a browser window to access the TrueNAS sign-in splash screen. Log in to TrueNAS.

Begin by configuring your first storage pool.

See Creating Storage Pools for more information on how to plan for and create pools in TrueNAS. If you want to create additional pools with other disks not assigned to a pool, you can do that now or as you have a need for them.

Creating a Storage Pool

Click Create Pool to open the Pool Creation Wizard.

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.
Figure 1: Pool Creation Wizard General Info
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 Enterprise
If 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.
Figure 2: Pool Creation Wizard General Info - SED
Enter and confirm the global SED password. This applies to all SED drives in the system.
1. (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.
Figure 3: Pool Creation Wizard Enclosure Options
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.
Figure 4: Enclosure Option Limit Pool to a Single 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.

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

<!-- comment out the setting automation tag {id="pool_create_auto-select"} -->

Figure 5: Pool Creation Wizard Data Screen

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children. If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.

Setting	Description
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.

Adding Datasets or Zvols

New pools have a root dataset that allows further division into new non-root parent and child datasets or into storage volumes (zvols). A dataset is a file system that stores data and has specific permissions.

A zvol is a virtual block device (like a virtual disk drive) that has a predefined storage size. Zvols are generally used with the iSCSI sharing protocol and also virtual machines (VMs) for their data storage needs.

To create a dataset or zvol, you can click Datasets on the main navigation panel or go to Storage and click Manage Datasets on the Usage widget for a specific pool to open the Datasets screen.

To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.

Select a dataset (root, parent, or child), then click Add Dataset.

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).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.

If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.

If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.

If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.

Click Save.

Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.

Organize the pool with as many datasets or zvols you need according to your access and data sharing requirements before moving data into the pool.

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.

Taking the Next Step

After you finish creating your initial pool and the datasets or zvols, you can continue building and organizing your TrueNAS pools and datasets or move on to configuring how the system shares data.

If you do not plan to set up data sharing, you can set up backup solutions for your system and stored data.

Setting Up Data Sharing

After setting up storage on your TrueNAS, it is time to begin sharing data! There are several sharing solutions available in TrueNAS, but in this article we discuss the options to create the share and dataset from the Shares screens.

When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.

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 SMB share users from Active Directory, or non-SMB share users from LDAP. The administration user can create a limited administration user with only the ability to manage shares. See Using Administration Logins for more information on administration roles.

To add non-SMB share users or edit users, go to Credentials > Users to add or edit the user(s). Click Add to create a new or as many new user accounts as you need.

Enter the values in each required field, verify SMB User is selected for SMB share users, then click Save. For more information on the fields and adding users, see Creating User Accounts.

By default, all new users are members of a built-in group called builtin_users. You can use a group to grant access to all users on the server or add more groups to fine-tune permissions for large numbers of users. This approach is particularly useful for high availability (HA) configurations and efficient data sharing across multiple users.

Why not just allow anonymous access to the share?

Anonymous or guest access to a share is possible, but it is a security vulnerability and not recommended for Enterprise or systems with more than one share administrator account. Using a guest account also increases the likelihood of unauthorized users gaining access to your data.

After creating the share user account(s), next create the share and dataset. For iSCSI shares, create the dataset then the share. You can create an SMB or NFS share while creating the dataset or create the dataset while creating the share.

This article provides instructions on creating the share and adding the dataset from Shares screens.

Setting up SMB Shares for Windows

For more detailed information on adding SMB shares, see Adding SMB Shares.

TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled. You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.

To set up a basic SMB share from the Add SMB screen:

Create the share and dataset.
a. Go to Shares, then click Add on the Windows (SMB) Shares widget to open the Add SMB configuration screen.
b. Populate the Path screen by either selecting the path to an existing dataset mount path, or entering the path to the dataset location. You can use an existing dataset or create a new dataset. To browse to the location, click on the to the left of mnt, and then at the pool to expand the options. Continue expanding until reaching the storage location of the existing dataset or where you want to create a new dataset for the share. Click on the exiting dataset to populate the field with the full path, or click Create Dataset to enter a name for a new dataset and the share.
Figure 8: Add SMB Path
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 9: File Explorer Folder Icons
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 share Edit Share ACL icon to open the Edit Share ACL screen.
Figure 10: SMB 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 share Edit Filesystem ACL icon to open the Edit ACL screen for the dataset.
Figure 11: Edit ACL Screen for Share 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.
Figure 12: File Explorer Enter SMB Credentials
c. Begin browsing the dataset.

Setting up NFS for Unix-Like Shares

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-common to any client systems that require them.
Create the NFS share and dataset.
a. Go to Shares, then click Add on the UNIX (NFS) Share Targets to open the Add NFS configuration screen.
b. Populate the Path screen by either selecting the path to an existing dataset mount path, or entering the path to the dataset location. You can use an existing dataset or create a new dataset. To browse to the location, click on the to the left of mnt, and then at the pool to expand the options. Continue expanding until reaching the storage location of the existing dataset or where you want to create a new dataset for the share. Click on the exiting dataset to populate the field with the full path, or click Create Dataset to enter a name for a new dataset and the share.
Figure 13: Add NFS Share Path
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 14: File Explorer Folder Icons
Clicking Create Dataset opens the Create Dataset dialog. Enter a name and then click Create. The system creates the share and dataset, and populates both the Path and share Name fields with the name given the dataset. The dataset name becomes the share name.
c. (Optional) Customize the share properties. You can make changes to any share using the Advanced Options option. For example, mapping users or groups, click Enable to set up audit logging.
d. Click Save. TrueNAS creates the share and the dataset.
e. Start the NFS service when prompted, or select the option to start the service if not prompted.
Access the dataset. On a Unix-like system, open a command line and enter command showmount -e {IPADDRESS} where {IPADDRESS} is your TrueNAS system IP address.
```
tmoore@ChimaeraPrime:~$ showmount -e 10.238.15.194
Export list for 10.238.15.194:
/mnt/pool1/testds (everyone)
```
Make a local directory for the NFS mount. Enter command sudo mkdir nfstemp/.
```
tmoore@ChimaeraPrime:~$ sudo mkdir nfstemp/
```
Mount the shared directory. Enter command sudo mount -t nfs {IPADDRESS:dataset path} where {IPADDRESS} is your system IP address and {:dataset path} is the full path displayed in step 3.b. above.
```
tmoore@ChimaeraPrime:~$ sudo mount -t nfs 10.238.15.194:/mnt/pool1/testds nfstemp/
```
From here, cd into the local directory and view or modify the files as needed.

Setting up 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.

Backing Up the System Configuration

After setting up TrueNAS, first, back up your system configuration by downloading the system configuration file.

In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file. Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations. See Using Administrator Logins for more information on admin account types.

Why should I save the secret seed?

Note, the secret seed does not store local users passwords in any form, only a hash of the password sufficient for authentication. Hashed passwords are not encrypted.

It is a best practice to always save the secret seed with the system configuration file after making system configuration changes to have a current backup copy to use should the need arise.

Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.

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.

Downloading the Initial System Debug File

After saving the system configuration, save an initial system debug file by going to System > General Settings and clicking Save Debug. After the download completes, save this initial debug file with your system configuration file.

Why download the initial system debug file? Downloading and storing the initial system debug after completing the system configuration is a recommended best practice to have a point of reference for your system if a problem arises. Save a debug file after a major system upgrade or reconfiguration to provide Support or Engineering if requested.

Create a Boot Environment

After installing and completing your system configuration, create a boot environment to use as a restore point.

If you lose access to the TrueNAS UI, you can establish an SSH session and restore it from the boot environment. You can clone the boot environment listed after the initial-install environment and rename the clone to something you recognize, such as the release number with date and time.

Backing Up TrueNAS Storage Data

TrueNAS has several options that allow you to back up data:

TrueCloud backup and cloud sync tasks require setting up a cloud service provider account and adding the credentials in TrueNAS before configuring and scheduling the tasks.

Replication requires setting up SSH credentials before configuring and scheduling the task. Rsync tasks can be configured with SSH credentials or set to use a module.

Using TrueCloud Backup or Cloud Sync

Cloud sync requires an account with a cloud storage provider and a storage location created with that provider, like an Amazon S3 bucket. TrueNAS supports major providers like Storj, Amazon S3, Google Cloud, Box, and Microsoft Azure, along with a variety of other vendors. These providers can charge fees for data transfer and storage, so please review the policies of your cloud storage provider before transferring your data.

Cloud sync and TrueCloud backup tasks can be configured to send, receive, or synchronize data with a cloud storage provider.

The simplest way to set up a TrueCloud backup task is using a Storj iX account. See Managing TrueCloud Backup Tasks for a full tutorial.

See Adding Cloud Credentials for information on connecting TrueNAS to other cloud storage providers.

Using Replication

Replication takes a moment-in-time snapshot of data and then copies that snapshot to another location. Snapshot technology typically uses less storage than full file backups and has more management and snapshot storage options.

Setting Up a Simple Replication Task

To create a simple replication task with the TrueNAS replication wizard:

Replication needs an existing periodic snapshot task** to run before the replication task runs or the replication task fails. You can define a periodic snapshot before manually configuring the replication task, or let the system create the snapshot task by selecting the replication wizard Replicate Custom Snapshots option. When using the wizard, TrueNAS automatically creates the periodic snapshot task and then runs the replication task.

Create a periodic snapshot task using the replication wizard Replicate Custom Snapshots replication option. If scheduling a task, TrueNAS creates the periodic snapshot task when it runs the replication task according to the scheduled time.
Create the replication task.

Go to Data Protection, and click Add on the Replication Tasks widget to open the Replication Task Wizard configuration screen.

Select the Source Location and Destination Location using the dropdown list options. You can back up your data on the same or a different system. If selecting A different system, you must have an SSH connection to that system. Have your destination and source information ready.

Set the Source and Destination paths, either enter the full path to the data you want to back up or click on the caret to the left of mnt and at the pool and dataset levels to expand the options. Click on the dataset or directory to narrow the backup down to that level.

The task name populates from the values in Source and Destination.

Select Replicate Custom Snapshots.

Click Next.

Define when to run this task.

Select the radio button for Run On a Schedule and select the schedule you want to use. Select Run Once to run the task manually. When using this option, you must have defined a periodic snapshot task. If running on a schedule, you do not need to pre-defined a snapshot task.

Select the radio button to specify the destination snapshot lifetime.

Click START REPLICATION. The task appears on the Replication Tasks widget with the status PENDING.

You can monitor created backup tasks from the Dashboard widget.

Configuring Virtualization and Apps

Configuring TrueNAS to work with virtualized features, such as virtual machines (VMs) and applications, is part of the setup process that, when optimized, takes advantage of the network storage capabilities that TrueNAS offers.

Before You Begin

This article assumes you have the latest release version of TrueNAS installed on your system. The following steps are a list of configuration prerequisites you have completed and are familiar with before beginning VM and application installations.

Network Configuration

The primary network interface is configured as part of the installation process. Go to Network > Global Configuration screen in the TrueNAS web UI to determine if the default gateway, host name, domain, and DNS name servers have been configured correctly. See Console Setup Menu Configuration for more information on network settings.

If VMs need to access local NAS storage, you need to create a network bridge and assign it to the VM. Applications or sandboxes that need access to local storage within the container must use a bridge or mount a local storage location as a host path for the application.

VLAN Configuration (Optional)

You can configure a virtual LAN (VLAN) to route traffic for your VMs. VLAN benefits include the reduction of broadcast traffic and the ability to group resources in different physical locations into a broadcast domain. VLANs virtually segment a network. Different VLANs can communicate with each other using layer 3 devices. See Setting Up a Network VLAN for more information on creating virtual LANs (VLAN).

Storage Configuration

Storage pool creation is part of the initial process of setting up storage. A TrueNAS dataset is a file system within a data storage pool. See Setting Up Storage to review storage pool creation and Adding and Managing Datasets for information on dataset configuration.

Shares Configuration

After creating the pool and datasets, set up shares to enable data access and sharing. Different types of data sharing methods are discussed in Setting Up Data Sharing. You should investigate more specific coverage of each share based on your use case.

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.

Directory Services Configuration

Certain directory services must be set up as part of SMB and NFS share configuration. See Active Directory Screen for a better understanding of how to configure Active Directory and Configuring Kerberos for an outline of required Kerberos information. For LDAP best practices see Configuring LDAP.

Virtual Machine and Container Configuration

TrueNAS includes built-in virtualization capabilities that enable you to run multiple operating systems and containerized applications on a single system, maximizing hardware utilization and consolidating workloads.

Virtual Machines

Virtual machines provide complete isolation by running full operating systems with dedicated virtualized hardware including network interfaces, storage, graphics adapters, and other components. VMs are ideal for running legacy applications, different operating systems, or services that require dedicated environments.

TrueNAS assigns a portion of system RAM and a new zvol to each VM. While a VM is running, these resources are not available to the host computer or other VMs.

Virtualization requires:

x86 machine running a recent Linux kernel
Intel processor with VT (Virtualization Technology) extensions, OR
AMD processor with SVM extensions (AMD-V)

Users cannot create VMs unless the host system supports these features.

Users with multiple GPUs who wish to pass a GPU to a VM must first isolate a GPU for VM use. One GPU is always required by TrueNAS.

See Virtual Machines for VM setup and management information.

Containers

Linux containers, powered by LXC, offer lightweight, isolated environments that share the host system kernel while maintaining separate file systems, processes, and network settings. Containers start quickly, use fewer system resources than VMs, and scale efficiently, making them ideal for deploying applications with minimal overhead.

Containers are lightweight and share the host kernel, requiring fewer resources than virtual machines. However, proper resource allocation ensures optimal performance and system stability.

You can leave CPU and memory settings blank to allow containers access to all available host resources, or configure specific limits based on your needs. Key considerations for container deployment:

Storage Pool: Containers require a storage pool for volume creation and image storage. SSD drives provide optimal performance.
CPU: No virtualization extensions required. Multiple containers run efficiently on fewer resources than equivalent VMs.
Memory: More efficient than VMs with no guest OS overhead. Memory allocated to containers reduces available memory for TrueNAS ZFS caching.

See Containers for Linux container configuration and management information.

Application Configuration

The first time you open the Applications screen, it displays an Apps Service Not Configured status on the screen header.

Click Settings > Choose Pool to choose a storage pool for Apps.

A storage pool for applications must be chosen before application installation can begin. Select a pool with enough space for all the application containers you intend to use. Set up a new dataset before installing your applications if you want to store your application data in a separate location from other storage on your system.

After an Apps storage pool is configured, the status changes to Apps Service Running.

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

About TrueNAS Support

TrueNAS Enterprise
TrueNAS Enterprise hardware customers with support contracts can contact TrueNAS Support using either this Enterprise Support link or through one of the contact options listed below.
Contacting TrueNAS Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

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.

How to download a debug file

On TrueNAS systems, go to System > General Settings, then click Save Debug and wait for the file to download to your local system. Generating the debug file might take a few minutes to complete. After that, it downloads to your system. If your browser download shows a dialog asking for confirmation, click Keep to continue the download process.

To generate a debug from the TrueNAS CLI, enter system debug > debugname.tgz, replacing debugname with your chosen file name. You must use SFTP or a similar method to connect to TrueNAS and download the file from the /home/username location, replacing username with the account name that generated the debug. SFTP Example:

PS C:\Users\tester> sftp admin@exampletruenas.net
Connected to exampletruenas.net.
sftp> cd /home/admin
sftp> get testdebug.tgz
Fetching /home/admin/testdebug.tgz to testdebug.tgz
/home/admin/testdebug.tgz						100% 7110KB	4.1MB/s	00.01
sftp> exit

Upload this debug to the private attachments area using the link provided when you open a Jira ticket. After uploading the file, link the attachment to the Jira ticket number before you click Save.

Support is also available through the TrueNAS community forums, blog, and Discord. These options are accessible on the top header of the TrueNAS Documentation Hub website and from the links at the bottom of all articles.

Using the TrueNAS Community Forum

The TrueNAS Community is an active online resource for asking questions, troubleshooting issues, and sharing information with other TrueNAS users. You must register to post.

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.

Using the Send Feedback Window

TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.

Rating a UI Screen

Reporting an Issue

Issue Reporting Example

Bug reports are created in the publicly visible TrueNAS Jira project.

TrueNAS can show a list of existing Jira tickets with similar summaries.

Click Login To Jira To Submit to finish and submit the report.

Reporting an Issue - Enterprise Licensed Systems

TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Figure 4: TrueNAS Enterprise Bug Report Form
Filling out the entire form with precise details and accurate contact information ensures a prompt response from the TrueNAS Customer Support team.

Making Feature Suggestions

Want to see a new feature added to TrueNAS? You can see and vote for community-proposed features in the TrueNAS Community Forum Feature Requests category. This is the place to suggest improvements and feature functionality to be considered for addition to the TrueNAS development roadmap.

Submitting and Voting for Requests

A TrueNAS forums account is required to submit or vote for feature suggestions.

To submit a new feature request, click New Topic in the top right of any forum screen Enter a title that describes the requested improvement or new functionality. Change the category tag to Feature Requests. The body of the post populates a template. Describe the Problem/Justification, Impact, and provide User Story for your request. Click Create Topic to submit the request.

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.

What is a good feature request?

Before creating a new feature request, it is important to take some time to think through the implementation and user story. A good feature request includes details about the functionality requested, if it involves a UI component, and a detailed user story describing how a TrueNAS user might interact with the proposed feature.

What is a bad feature request?

Items which are completely unrealistic (i.e. Can you base TrueNAS on Windows) or feature requests which are outside of the scope of typical NAS functionality (i.e. I want a full desktop with Gnome on TrueNAS).

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.

Dispute Resolution

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:
1. 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.
2. 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.
3. 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.0 Definitions

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.

2.0 License

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.

2.1 Licensee Obligations

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.

2.2 Updates and Support

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.

3.0 License Restrictions

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.

4.0 General Terms

4.1 Entire Agreement

This Agreement, together with any associated purchase order, service level agreement, and all other documents and policies referenced herein, constitutes the entire and only agreement between You and 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.

4.2 Waiver and Modification

No failure of either party to exercise or enforce any of its rights under this EULA will act as a waiver of those rights. This EULA may only be modified, or any rights under it waived, by a written document executed by the party against which it is asserted.

4.3 Severability

If any provision of this EULA is found illegal or unenforceable, it will be enforced to the maximum extent permissible, and the legality and enforceability of the other provisions of this EULA will not be affected.

4.4 United States Government End Users

For any TrueNAS 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.

4.5 Anti-Corruption

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.

4.6 Title

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.

4.7 Contact Information

If You have any questions about this Agreement, or if You want to contact TrueNAS for any reason, please email legal@truenas.com.

4.8 Maintenance and Support

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.

4.9 Force Majeure

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.

4.10 Termination

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).

4.11 Open Source Software Components

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.

4.12 Assignment

Licensee shall not assign or otherwise transfer any of its rights, or delegate or otherwise transfer any of its obligations or performance, under this Agreement, in each case whether voluntarily, involuntarily, by operation of law, or otherwise, without 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.

4.13 Notice Provisions

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.

4.14 Limitation Period

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.

5.0 Export Control Regulations

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.

6.0 Data Collection and Privacy

6.1 Data Collection & Privacy Policy

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.

6.2 Data Protection Compliance

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.

7.0 Limited Warranty

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.

8.0 Limitation of Liability and Disclaimer of Warranty

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.

9.0 Indemnification

9.1 Indemnification by TrueNAS

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.

9.2 Indemnification by Licensee

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.

9.3 Indemnification Process

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.

9.4 Indemnity Liability

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.

10.0 Confidentiality

10.1 Obligations

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.

10.2 Compelled Disclosure

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.

10.3 Return and Destruction

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.

10.4 Survival

The obligations of confidentiality under this Section 10.0 shall survive termination or expiration of this Agreement for a period of five (5) years.

Acceptance

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.

Planning

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.

Development

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.

Evaluation

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.

Maintenance

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.

Release Versioning

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

End of Life

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

Reviewing Usage Collection

To review system usage data collected by TrueNAS, access the system shell via SSH or the console and enter midclt call usage.gather. This command returns the same statistics that are transmitted to the TrueNAS team when Usage collection is enabled.

TrueNAS does not collect any user-defined names for servers, pools, datasets, shares, files, applications/jails, processes, and similar. Applications do transmit chart release names for deployed applications (e.g. “minio/2.0.6”) but not user-defined names.

While usage collection gathers only non-sensitive system data, sensitive user data is included in a TrueNAS-generated debug file, such as those requested for a bug report, feature request, or other troubleshooting. Always store debug files in a secure location. Please review debugs and redact any sensitive information before sharing with external entities. The TrueNAS Privacy Policy contains a detailed statement of our commitment to data privacy.

Top Toolbar

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.

Searching UI Fields

Click the Search UI bar or type Ctrl + / to select the UI global search.

Entering a Query

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.

Navigating Results

Select a screen result under UI to go to the matching screen within the TrueNAS UI. For example, select Shares 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 SMB Add SMB Share to locate to the Add button on the SMB screen.

TrueNAS indicates the selected element with a glow effect.

Searching TrueNAS Documentation

Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub. TrueNAS opens a new browser tab to display documentation search results for the query.

Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.

TrueNAS

The TrueNAS logo returns to the Dashboard from any other screen.

Send Feedback

TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.

Rating a UI Screen

Reporting an Issue

Issue Reporting Example

Bug reports are created in the publicly visible TrueNAS Jira project.

TrueNAS can show a list of existing Jira tickets with similar summaries.

Click Login To Jira To Submit to finish and submit the report.

Reporting an Issue - Enterprise Licensed Systems

TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Figure 10: TrueNAS Enterprise Bug Report Form
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

Click Get Connected to open the TrueNAS Connect sign-in screen.

Click Open TrueNAS Connect to open the TrueNAS Connect management interface. Click 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 info icon button displays the status of Active Directory and LDAP services.

Click on either service to go to its configuration screen.

Jobs

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 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 button as an option.

Click View next to a task to see the log information and error message for that task.

For more information, see Jobs Screens.

Alerts

Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.

TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.

Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.

Alerts Admonitions

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

Change Password

Click on the Change Password dialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.

Click on the visibility_off icon to display entered passwords. To stop displaying the password, click on the visibility icon.

My API Keys

Click API Docs to access the API documentation portal with information on TrueNAS API commands.

See API Keys for more information on adding or managing API keys.

Guide

Click on Guide library_books to open the TrueNAS Documentation Hub in a new tab.

Log Out

Log Out logs the current user out of the TrueNAS UI, but does not power off the system. The Read-Only Admin and Sharing Admin roles only have access to the Log Out option.

Power Options

TrueNAS Enterprise
Please consult your specific hardware documentation to find notes about possible hardware-specific controls for power-on or off behaviors.

Content

Alerts: Describes the TrueNAS alert system.

Alert Settings Screens: The Alert Settings screen allows users to set the warning levels and frequency of alerts.
Email Screens: Provides information on the email configuration screens for SMTP and GMail OAuth.

Settings Options: Describes the top-level Settings options in TrueNAS.

User API Keys Screen: Describes how the User API Keys screen in TrueNAS and access API Documentation
Two Factor Auth Screen: Provides information on the Two Factor Auth screen settings.

Using UI Global Search: This tutorial shows how to use the Global Search feature to explore the TrueNAS UI and documentation.

Managing API Keys: This tutorial shows how to add, create, or edit an API key in TrueNAS and access API Documentation.

Shutting Down TrueNAS Enterprise HA: Describes the procedure for shutting down an Enterprise HA system in TrueNAS.

Top Toolbar Screens: All the icons and options contained in the TrueNAS top toolbar.

Jobs Screens: Describes the TrueNAS jobs manager and how to use it to view failed jobs and logs.

Alerts

Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.

TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.

Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.

Alerts Admonitions

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 allows users to set the warning levels and frequency of alerts.

Email Screens: Provides information on the email configuration screens for SMTP and GMail OAuth.

Alert Settings Screens

The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies. To access this screen, click the notifications icon, then click the settings icon and select Alert Settings on the dropdown list.

AlertServicesScreen

Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.

Add/Edit Alert Service Screen

The Add Alert Service and Edit Alert Service screens show the same settings.

Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default. To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.

AddAlertServiceScreen

Name and Type Settings

Setting	Description
Name	Enter a name for the new alert service.
Enabled	Clear the checkmark to disable this service without deleting it.
Type	Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or 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 edit icon for the service to display the Edit Alert Service screen.

Alert Service Types

AWS SNS

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.

Email

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.

InfluxDB

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.

MatterMost

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.

OpsGenie

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).

PagerDuty

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.

Slack

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.

SNMP Trap

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.

Splunk On-Call

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.

Alert Categories

Use the Category dropdown list to display alert settings for each category.

Applications

Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.

Click here for more information

You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.

Audit

Audit alert settings apply to the audit and verification services on your TrueNAS system.

Click here for more information

You can customize alert settings for when the audit service backend fails, the audit service has a health failure, and when the TrueNAS verify service detects changes in the root file system.

Certificates

Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.

Click here for more information

You can customize alert settings for when a certificate has expired, is expiring, or is expiring soon, when a certificate parsing fails, and when the web UI HTTPS certificate setup fails.

Directory Service

Directory Service alert settings apply to the directory services configured on your TrueNAS.

Click here for more information

You can customize alert settings for when the directory service bind is not healthy and when a directory service DNS update fails.

High Availability Settings

TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only 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

Hardware alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.

Click here for more information

You can customize alert settings for when disk temperature is too hot, disk(s) format with the data integrity feature, a selftest fails, erase cycle count is high, IPMI has system events, the IPMI system event log space is low, JBOF removal requires reboot, spare block reserve is low, and uncorrected errors are detected.

The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues. Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL. Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.

Key Management Interoperability Protocol (KMIP)

Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.

Click here for more information

You can customize alert settings for when the system fails to communicate with the KMIP server, sync the SED global password, sync SED keys, or sync ZFS keys with the KMIP server.

Network

Network alert settings apply to network interfaces configured on your TrueNAS.

Click here for more information

You can customize alert settings for when a BOND interface references missing ports, when ports are not active on a BOND interface, and when there are no active ports on a BOND interface.

Reporting

Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.

Click here for more information

You can customize alert settings for when Netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.

Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.

Click here for more information

You can customize alert settings for when a deprecated service 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.

Storage

Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.

Click here for more information

You can customize alert settings for when a dataset exceeds standard 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.

System

System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.

Click here for more information

You can customize alert settings for when 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.

Tasks

Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub, and snapshot tasks scheduled on your TrueNAS.

Click here for more information

You can customize alert settings for when cloud 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.

TrueNAS Connect Service

TrueNAS Connect Service alert settings apply to the TrueNAS Connect service on your TrueNAS system.

Click here for more information

You can customize alert settings for when TrueNAS Connect is disabled or unconfigured and when the system is unable to connect to the TrueNAS Connect heartbeat service.

UPS

UPS alert settings apply to a UPS connected to your TrueNAS.

Click here for more information

You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.

Alert Warning Levels

Use the Set Warning Level dropdown list to customize alert importance. Each warning level has an icon and color to express the level of urgency.

To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level. TrueNAS sends alert notifications for all warnings matching and above the selected level For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.

Level	Icon	Alert Notification?
INFO		No
NOTICE		Yes
WARNING		Yes
ERROR		Yes
CRITICAL		Yes
ALERT		Yes
EMERGENCY		Yes

Alert Frequency

Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.

Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.

Email Screens

The top toolbar Alerts notifications icon button and settings icon display the Alerts dropdown list with two options: Alert Settings and Email.

Select Email to go to the General settings screen and find the Email widget.

The Email widget on the General Settings screen displays information about current system mail settings.

Settings opens the Email Options screen that allows users to configure the system email send method.

Email Options Screen

SMTP

Gmail OAuth

Outlook OAuth

Settings Options

The account_circle Settings icon button displays a menu of general system settings options. The options are Change Password, Preferences, My API Keys, Guide and About.

Change Password

Click on the Change Password dialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.

Click on the visibility_off icon to display entered passwords. To stop displaying the password, click on the visibility icon.

Preferences

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.

Customizing UI Theme and Localization

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.

Changing UI Session Timeout

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.

My API Keys

Click on laptop 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.

Guide

Click on library_books Guide to display the TrueNAS Documentation Hub in a new tab.

About

Click on About to display the information window links to the TrueNAS Documentation Hub, TrueNAS Community Forums, FreeNAS Open Source Storage Appliance GitHub repository, and iXsystems home page.

AboutWindow

User API Keys Screen: Describes how the User API Keys screen in TrueNAS and access API Documentation

Two Factor Auth Screen: Provides information on the Two Factor Auth screen settings.

User API Keys Screen

My API Keys on the top right toolbar 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 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 for any API key on the list opens a Delete API Key dialog to remove that key.

API Documentation

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.

Screen States

The Two Factor Auth screen displays different information depending on the Global 2FA and user 2FA configuration status.

Global 2FA Disabled

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.

Global 2FA Enabled, User Not Configured

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.

2FA Configured

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.

Set Up Two-Factor Authentication Card

The Set Up Two-Factor Authentication card contains the following elements:

Actions

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.

2FA Renew Secret — Figure 2: Renew Secret Dialog

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.

Figure 3: Unset Two-Factor Authentication Dialog

Removing your 2FA configuration reduces account security. If Global 2FA is enabled, you are prompted to set up 2FA again on your next login.

QR Code Section

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.

Text Code Section

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.

Searching UI Fields

Click the Search UI bar or type Ctrl + / to select the UI global search.

Entering a Query

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.

Navigating Results

Select a screen result under UI to go to the matching screen within the TrueNAS UI. For example, select Shares 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 SMB Add SMB Share to locate to the Add button on the SMB screen.

TrueNAS indicates the selected element with a glow effect.

Searching TrueNAS Documentation

Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub. TrueNAS opens a new browser tab to display documentation search results for the query.

Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.

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 My API Keys from the 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 API Keys

TrueNAS Connect automatically creates an API key when you register your system in the TrueNAS Connect service. TrueNAS uses this key, shown on the User API Key screen, to authenticate with the TrueNAS Connect service.

There are instances where you might see more than one tnc key listed.

If you delete a tnc API key, the TrueNAS Connect prompts you to re-authenticate the next time you connect to the service.

Adding an API Key

Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.

Always back up and secure keys. TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware. API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account. A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys. TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport. A revoked API key cannot be used until it is reset. Resetting generates a new key-string.
Remember to update clients to use the new key.

Select My API Keys from the Settings dropdown on the top toolbar.

Alternatively, you can go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.

If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.

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.

Can I view the API Key again after closing the API Key dialog?

You cannot view the API key string after closing the API Key dialog.

If you close the dialog before copying the key, select the user row and click Edit to open the Edit API Key screen. Select Reset. TrueNAS opens the API Key dialog showing a new key string. Copy the key before closing the dialog. Remember to update settings using the API key token.

Click Close to return to the User API Keys screen.

Migrating API Keys

Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.

Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system. Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, generate a new user-linked API key, and distribute it to the API client.

Editing an API Key

Select the user row and then click edit 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.

Deleting an API Key

Click delete for any API key on the list to remove that key. TrueNAS opens a Delete API Key dialog.

Select Confirm, then click Delete.

Embedded API Documentation

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.

For more information on the API documentation see API Reference.

Shutting Down TrueNAS Enterprise HA

TrueNAS Enterprise
This procedure applies to TrueNAS Enterprise High Availability (HA) systems only.

If you need to power down your TrueNAS Enterprise system with HA enabled, this is the procedure:

Shut Down From the TrueNAS Web UI

PowerButtonSCALE

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.
info	Directory Services status	Displays a dialog with the status of Active Directory and LDAP directory servers configured on the system.
assignment	Running Jobs	Displays the Running Jobs dialog. Click the History button to display the Tasks screen with a list of All, Active or Failed tasks or processes.
notifications	Alerts	Displays a list of system alerts and a dropdown list with the alert options Alert Settings and Email.
account_circle	Settings	Displays a dropdown list of setting options Change Password, Two-Factor Authentication (when Global 2FA is enabled), My API Keys, Guide, and Log Out.
power_settings_new	Power options	Displays the power related options Restart or Shut Down.

Search UI

The Search UI global search bar allows users to search for screens and elements within the TrueNAS UI or to redirect search terms to the TrueNAS Documentation Hub.

Using Global Search

Searching UI Fields

Click the Search UI bar or type Ctrl + / to select the UI global search.

Entering a Query

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.

Navigating Results

Select a screen result under UI to go to the matching screen within the TrueNAS UI. For example, select Shares 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 SMB Add SMB Share to locate to the Add button on the SMB screen.

TrueNAS indicates the selected element with a glow effect.

Searching TrueNAS Documentation

Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub. TrueNAS opens a new browser tab to display documentation search results for the query.

Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.

Send Feedback

TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.

Rating a UI Screen

Reporting an Issue

Issue Reporting Example

Bug reports are created in the publicly visible TrueNAS Jira project.

TrueNAS can show a list of existing Jira tickets with similar summaries.

Click Login To Jira To Submit to finish and submit the report.

Reporting an Issue - Enterprise Licensed Systems

TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Figure 10: TrueNAS Enterprise Bug Report Form
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

Click Get Connected to open the TrueNAS Connect sign-in screen.

Click Open TrueNAS Connect to open the TrueNAS Connect management interface. Click 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 info icon button displays the status of Active Directory and LDAP services.

Click on either service to go to its configuration screen.

Jobs

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 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 button as an option.

Click View next to a task to see the log information and error message for that task.

For more information, see Jobs Screens.

Alerts

Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.

TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.

Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.

Alerts Admonitions

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 account_circle 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 dialpad Change Password button displays a dialog where you can change the login password for the currently logged-in administrator.

The settings 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 laptop 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 library_books Guide button opens the TrueNAS Documentation Hub website in a new browser tab.

The exit_to_app Log Out button logs the current user out of the TrueNAS UI.

Preferences Screen Settings

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.

Power

The Power power_settings_new 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.

JobsScreen

Use the arrow display options to change the number of jobs per screen. Options are the default 10, 50 or 100.

Click View to display the argument passed for the selected job.

Use the north arrow beside the State or ID header to change the display order, or the south arrow to return to the top down display order.

Failed Jobs Screen

The Failed screen lists failed jobs.

JobsFailed

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: Tutorials related to using the TrueNAS Dashboard. Includes instructions on customizing the Dashboard widgets.

Dashboard Screen: Explains the main dashboard information cards (widgets) and provides basic information on synchronizing the system and TrueNAS server times, and on customizing the Dashboard display.

Customizing the Dashboard

This section contains tutorials for the main Dashboard.

Customizing the 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.
Figure 2: Widget Editor for New Widget
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.
Figure 3: Widget Editor for Existing Widget
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.
Figure 4: Widget Group Options for Network
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.

Dashboard Widgets

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.

Figure 3: System Information Widget for iX Systems

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 assignment 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

TrueNAS Enterprise
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.
Figure 4: HA System Information Widgets

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 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.

Figure 11: Backup Tasks Widget with Cloud Sync Example

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.

Dashboard in Configuration Mode

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.

Figure 17: Widget Editor for Existing Widget

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: Empty - Default selection for a new widget. Use to fill a grouping of multiple widgets where only two are defined and the others are not. Storage - Use to set up a storage or single pool widget. Network - Use to set up a network widget. Help - Use to include the widget with links to TrueNAS resources. Memory - Use to set up a memory-usage widget. Backup Tasks - Use to set up a widget showing either configured data protection tasks or links to locations to configure tasks. CPU - Use to set up a CPU usage widget. System Information - Use to add one of four system information widget types. Custom - Use to set up a text-only widget with whatever text-based information you want to include on the Dashboard. The Widget Type field shows after selecting the category.
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 Network

There are three types available when Widget Category is set to Network. Selecting Interface, IPv4 Address or IPv6 Address as the type adds the Interfaces field to the screen.

Interface shows the interface ID, link state, I/O traffic, Media type and subtype, and IP address assigned to the interface, and the dynamic bar graph for the I/O traffic. Can use a full or half-size widget.

IPv4 Address and IPv6 Address can use a full, half, or quarter-size widget. Shows the IP address for the selected interface.

Select the interface to show in the widget from the Interface dropdown field.

Widget Type Options for Storage

There are three widget categories available when Widget Category is set to Storage: Storage, Pool, and Pool Usage. The layout for the widget must be full-size.

Selecting any of the Storage categories adds the Pool field to the screen.

Selecting Pool as the category shows three options, Pool Usage, Disks w/ZFS Errors, and Last Scan Errors. Each of these three categories can be assigned to a quarter-size widget.

Widget Type Options for Help

Only Help is the available widget type when Widget Category is set to Help.

The Help widget can use a full, half, or quarter-size widget, but using the half or quarter size adds scrollbars to the widget to provide access to the full content in this widget category. For best viewing and access to the content, we recommend using the full size for the Help widget.

Widget Type Options for Memory

Only Memory is the available widget type when Widget Category is set to Memory.

The Memory widget can use a full, half, or quarter-size widget, and can be included in a widget group with other widget categories and types.

Widget Type Options for Backup Tasks

Only Backup Tasks is the available widget type when Widget Category is set to Backup Tasks.

The Backup Task widget can only use a full-size widget.

Widget Type Options for CPU

Only CPU Model, CPU Overview, and CPU Temp are available as widget types when Widget Category is set to CPU and a full layout is selected.

CPU Recent Temperature, CPU Recent Usage, CPU Usage Per Core, CPU Temperature Per Core, and CPU Usage become available as a Widget Type when full, half, or quarter-sized layouts are 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.

TrueNAS Enterprise
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.
Figure 18: TrueNAS HA System Dashboard
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.

Widget Type Options for Custom

The Custom widget has only the Arbitrary Text as the widget type but also shows the Widget Title, Widget Text, and Widget Subtext fields. Enter text that does not exceed the maximum character count for the Custom widget, which is 200 upper and lower case alpha-numeric or special characters. Spaces between characters count as characters.

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: Tutorials and UI reference to create and manage ZFS storage pools in TrueNAS.

Import Pool: Provides information on ZFS importing for storage pools in TrueNAS. It also addresses GELI-encrypted pools.
Creating Pools: Provides background considerations and a simple tutorial on creating storage pools in TrueNAS.
Creating Fusion Pools: Provides information on setting up and using fusion pools.
Managing Pools: Provides instructions on managing storage pools, VDEVs, and disks in TrueNAS.
Pool Creation Wizard Screen: Descriptions for settings and functions found in the Pool Creation Wizard.
VDEV Screens: Provides information on settings and functions found on the VDEVs screens and card.

Disks: Articles with instructions to manage, replace, and wipe disks.

Replacing Disks: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.
Wiping a Disk: Provides instructions for wiping a disk.
SLOG Over-Provisioning: Provides information on the disk_resize command in TrueNAS.
Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.
Disks Screen: Describes UI screens and dialogs related to disk operations.
Drive Health Management: Provides information and considerations for drive health.

Storage Dashboard Screens: Provides information on the Storage Dashboard widgets and options for pools, devices, and disks listed on this screen.

Pools

TrueNAS pools are ZFS storage containers that combine physical disks to provide storage capacity and data protection.

Import Pool: Provides information on ZFS importing for storage pools in TrueNAS. It also addresses GELI-encrypted pools.

Creating Pools: Provides background considerations and a simple tutorial on creating storage pools in TrueNAS.

Creating Fusion Pools: Provides information on setting up and using fusion pools.

Managing Pools: Provides instructions on managing storage pools, VDEVs, and disks in TrueNAS.

Pool Creation Wizard Screen: Descriptions for settings and functions found in the Pool Creation Wizard.

VDEV Screens: Provides information on settings and functions found on the VDEVs screens and card.

Import Pool

ZFS pool importing works for pools exported or disconnected from the current system, those created on another system, and for pools you reconnect after reinstalling or upgrading the TrueNAS system.

The import procedure only applies to disks with a ZFS storage pool.

TrueNAS supports pool imports using the WebUI or API only. Manual pool import via command line can cause unexpected behavior and system issues.

Do I need to do anything different with disks installed on a different system?

When physically installing ZFS pool disks from another system, use the zpool export poolname command in the Linux command line or a web interface equivalent to export the pool on that system. Shut down that system and move the drives to the TrueNAS system. Shutting down the original system prevents an in use by another machine error during the TrueNAS import.

To import a pool, go to the Storage Dashboard and click Import Pool at the top of the screen.

TrueNAS detects the pools that are present but not connected and adds them to the Pools dropdown list.

Select a pool from the Pool dropdown list, then click Import.

Importing SED Drives

TrueNAS Enterprise
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.
Figure 2: Import Pool with SED Disks
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.
Figure 3: Unlocking SED Disks
Skip proceeds with the import with only the unlocked disk.

Can I import GELI-encrypted pools?

GELI encryption is specific to FreeBSD so Linux-based TrueNAS cannot import GELI-encrypted pools. See the GELI Pool Migrations section in the TrueNAS 13.0 Storage Encryption article.

The Preparing to Migrate article provides information on what you can and cannot migrate and a checklist of actions to take before migrating from TrueNAS 13.0 (or 13.3 for community users) with GELI-encrypted pools to 24.04.

Creating Pools

TrueNAS uses ZFS data storage pools to efficiently store and protect data.

What is a pool?

Storage pools attach drives organized into virtual devices called VDEVs. Drives arranged inside VDEVs provide varying amounts of redundancy and performance. ZFS and VDEVs combined create high-performance pools that maximize data lifetime.

ZFS and TrueNAS periodically review and heal when discovering a bad block in a pool.

Reviewing Storage Needs

We strongly recommend that you review your available system resources and plan your storage use case before creating a storage pool. Considerations:

Allocating more drives to a pool increases redundancy when storing critical information.
Maximizing total available storage at the expense of redundancy or performance entails allocating large-volume disks and configuring a pool for minimal redundancy.
Maximizing pool performance entails installing and allocating high-speed SSD drives to a pool.

RAIDz pool layouts are well-suited for general use cases and especially smaller (<10) data VDEVS or storage scenarios that involve storing multitudes of small data blocks.

dRAID pool layouts are useful in specific situations where large disk count (>100) arrays need improved resilver times due to increased disk failure rates and the array is intended to store large data blocks.

TrueNAS recommends defaulting to a RAIDz layout generally and whenever a dRAID vdev would have fewer than 10 data storage devices.

Determining your specific storage requirements is a critical step before creating a pool. The ZFS and dRAID primers provide a starting point to learn about the strengths and costs of different storage pool layouts. You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.

Data Encryption

Security requirements can mean the data must be protected with additional encryption.

Encrypting the root dataset (pool-level encryption) creates a single point of failure. Losing one key makes the entire pool inaccessible.
Best practice Do not enable encryption during pool creation. Instead, create an unencrypted pool with individually encrypted datasets and zvols. This allows independent key management, selective unlock, isolated failures, and simplified recovery.

Creating a Pool

Click Create Pool to open the Pool Creation Wizard.

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.
Figure 1: Pool Creation Wizard General Info
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 Enterprise
If 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.
Figure 2: Pool Creation Wizard General Info - SED
Enter and confirm the global SED password. This applies to all SED drives in the system.
1. (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.
Figure 3: Pool Creation Wizard Enclosure Options
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.
Figure 4: Enclosure Option Limit Pool to a Single Enclosure

Create the required data VDEV.

Pool Creation Wizard Data VDEV

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

<!-- 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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

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).

What is a special VDEV?

A special VDEV can store metadata such as file locations and allocation tables. The allocations in the special class are dedicated to specific block types. By default, this includes all metadata, the indirect blocks of user data, and any deduplication tables. The class can also be provisioned to accept small file blocks. This is a great use case for high-performance but smaller-sized solid-state storage. Using a special vdev drastically speeds up random I/O and cuts the average spinning-disk I/Os needed to find and access a file by up to half.

Creating a Fusion Pool

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.

Figure 1: Pool Creation Wizard Metadata Screen

Select a layout that matches or exceeds the redundancy level of the data VDEV. For example, if the data VDEV uses RAIDZ2, select RAIDZ2 or a three-way mirror for the Metadata VDEV. Pool creation fails when the Metadata VDEV redundancy is lower than the data VDEV redundancy.

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. Each Metadata VDEV must use a redundancy level equal to or greater than the data VDEVs. For example, if data VDEVs are configured as RAIDZ2, use RAIDZ2 or a three-way mirror for Metadata VDEVs. Pool creation fails when Metadata VDEV redundancy is lower than data VDEV redundancy.

UPS Recommendation

When using SSDs with an internal cache, add an uninterruptible power supply (UPS) to the system to help minimize the risk from power loss.

Hot spares only activate in data VDEVs, so a hot spare cannot replace a failed drive in a special VDEV. The special VDEV must protect itself with its own internal redundancy (a mirror at the redundancy level required above). Without it, if the special VDEV fails the pool becomes corrupted and prevents access to stored data.

Special VDEVs often use a different drive type than the data VDEVs (such as a mirror of SSDs) for better performance. Provide sufficient internal redundancy for the special VDEV regardless of drive type.

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.

Setting Up Auto TRIM

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 more_vert 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.

Exporting or Deleting a Pool

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.

Exporting a Pool

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.

Deleting a Pool

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 Pool

Upgrading a storage pool is typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.

Do not do a pool-wide ZFS upgrade until you are ready to commit to this TrueNAS major version! You can not undo a pool upgrade, and you lose the ability to roll back to an earlier major version!

The Upgrade button displays on the Storage Dashboard for existing pools after an upgrade to a new TrueNAS major version that includes new OpenZFS feature flags. Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS version.

Figure 5: Upgrade Pool Confirmation Dialog

Upgrading pools only takes a few seconds and is non-disruptive. However, the best practice is to upgrade a pool while it is not in heavy use. The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.

It is not necessary to stop sharing services to upgrade the pool.

Running a Pool Data Integrity Check (Scrub)

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.

Scheduling Scrub Tasks

TrueNAS automatically creates a scheduled scrub for each pool that runs every Sunday at 12:00 AM.

The Storage Health widget shows the scheduled scrub status:

Scheduled Scrub: None Set with a Schedule link if no scrub task exists
Scheduled Scrub: [when] with a Configure link if a scrub task is configured and enabled

Click Schedule to create a new scrub schedule or Configure to modify an existing schedule. This opens the Configure Scheduled Scrub screen, where you can set the schedule, 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.

Managing Pool Disks

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.

Expanding a Pool

There are a few ways to increase the size of an existing pool:

Add one or more drives to an existing RAIDZ VDEV.
Add a new VDEV of the same type.
Add a new VDEV of a different type.
Replace all existing disks in the VDEV with larger disks.

Adding a new special VDEV increases usable space in combination with a special_small_files VDEV, but it is not encouraged.
A VDEV limits all disks to the usable capacity of the smallest attached device.

When 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 more_vert 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.

Extending a RAIDZ VDEV

Extend a RAIDZ VDEV to add additional disks one at a time, expanding capacity incrementally. This is useful for small pools (typically with only one RAID-Z VDEV), where there is not enough hardware capacity to add a second VDEV, doubling the number of disks.

Overview and Considerations

TrueNAS 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.

Figure 8: RAIDZ Expansion
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.

Adding a VDEV to a Pool

ZFS supports adding VDEVs to an existing ZFS pool to increase the capacity or performance of the pool. To extend a pool by mirroring, you must add a data VDEV of the same type as existing VDEVs.

You cannot change the original encryption or data VDEV configuration.

Adding VDEV Examples

To make a striped mirror, add the same number of drives to extend a ZFS mirror. For example, you start with ten available drives. Create a mirror of two drives, then extend the mirror by adding another mirror of two drives. Repeat this three more times until you add all ten drives.
To make a stripe of two 3-drive RAIDZ1 VDEVs (similar to RAID 50 on a hardware controller), add another three drives as a new RAIDZ1 VDEV to the existing single 3-drive RAIDZ1 VDEV pool.
To make a stripe of two 6-disk RAIDZ2 VDEVs (similar to RAID 60 on a hardware controller), add another six drives as a new RAIDZ2 VDEV to the existing single 6-drive RAIDZ2 VDEV pool.
To add a deduplication VDEV, we suggest creating the VDEV when you first create the pool to ensure that all metadata or deduplication tables are stored on it. Special or deduplication VDEVs added to a pool with existing data are only populated with new writes.

To add a VDEV to 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.
Figure 11: Add To Pool - Existing Pool

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.
Figure 12: Add VDEVs to Pool Screen

TrueNAS Enterprise
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.

Figure 13: Add VDEVs to Pool Spare Example

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.

Adding a VDEV Manually

To add the vdev manually, click Manual Disk Selection to open the Manual Selection screen.

Figure 14: Add Vdev 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.

Figure 15: Add Disk to Stripe Vdev for Spare

The Manual Selection screen closes and returns to the Add Vdev to Pool wizard screen (in this case, the Spare option).

Figure 16: Add Vdev to Pool Spare with Vdev Added

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.

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.

Figure 17: Add Vdev to Pool Review Screen

To make changes, click either Back or the vdev option (i.e., Log, Cache, etc.) to return to the settings for that vdev. To clear all changes, click Start Over. Select Confirm, then click Start Over to clear all changes.

Click Update Pool to save changes.

Adding a Deduplication VDEV

You can add a deduplication VDEV to an existing pool, but files in the pool might or might not have deduplication applied to them. When adding a deduplication VDEV to an existing pool, any existing entries in the deduplication table remain on the data VDEVs until the data they reference is rewritten.

After adding a deduplication VDEV to a pool, and when 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.

Figure 18: Prune Deduplication Table Dialog

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.

Replacing Disks to Expand a Pool

To expand a pool by replacing disks with a higher-capacity disk, follow the same procedure as in Replacing Disks.

Insert a new disk into an empty enclosure slot. Remove the old disk only after completing the replacement operation. If an empty slot is 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.
Figure 20: Devices Disk Widgets
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).
Figure 21: Replace and Online a Disk
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.
Figure 22: Replacing Disk 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.
Figure 23: Replacing Disk Status
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.

Removing VDEVs

You can always remove the L2ARC (cache) and SLOG (log) VDEVs from an existing pool, regardless of topology or VDEV type. Removing these devices does not impact data integrity but 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_removal zfs feature flag.
The pool must be upgraded to a ZFS version with the device_removal feature 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.

Pool Creation Wizard

The Pool Creation Wizard for most systems has seven configuration screens, numbered in sequence, to create a pool with VDEVs.

TrueNAS Enterprise
Larger iXsystems-provided servers for Enterprise users equipped with expansion shelves include the additional Enclosure Options screen.

Each wizard VDEV configuration screen includes the Automated Disk Selection and Advanced Options areas. Click Manual Disk Selection to open the Manual Selection screen.

Back and Next move to the previous or next wizard screen. Reset Step clears the VDEV settings for the VDEV type selected. For example, Data VDEV configuration. Save And Go To Review saves the current selections and goes directly to the Review wizard screen.

General Info

The General Info 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.

TrueNAS Enterprise
General Info with SED Encryption
Enterprise systems licensed for and containing SED encryption can use the Self Encryption Drives (SED) encryption type.
Figure 3: Pool Creation Wizard General Info - SED
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.
Enclosure Options
The Enclosure Options wizard screen shows if the Enterprise system has one or more expansion shelves.
Figure 4: Pool Creation Wizard Enclosure Options
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.
Figure 5: Enclosure Option Limit Pool to a Single Enclosure

Data Screen

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.

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Log (Optional)

The Log wizard screen settings configure a log VDEV. ZFS log devices can improve synchronous write speeds.

Figure 8: Pool Creation Wizard Log Screen

Common Pool Creation Wizard Settings

The Layout dropdown list includes the Stripe or Mirror types.

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Spare (Optional)

The Spare wizard screen settings configure a hot spare for a drive in a data VDEV.

Figure 10: Pool Creation Wizard Spare Screen

Common Pool Creation Wizard Settings

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Cache (Optional)

The Cache wizard screen settings configure a ZFS L2ARC read-cache VDEV.

Figure 12: Pool Creation Wizard Cache Screen

Common Pool Creation Wizard Settings

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Metadata (Optional)

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 Mirror, RAIDZ1, RAIDZ2, and RAIDZ3 types.

Match the Metadata VDEV redundancy level to the data VDEV redundancy level. For example, if data VDEVs use RAIDZ2, use RAIDZ2 or a three-way mirror for the Metadata VDEV. Pool creation fails when the Metadata VDEV redundancy is lower than the data VDEV redundancy.

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Dedup (Optional)

The Dedup wizard screen settings configure a deduplication VDEV. A Dedup VDEV stores de-duplication tables. Size dedup VDEVs as x GiB for each x TiB of general storage.

Figure 16: Pool Creation Wizard Dedup Screen

Common Pool Creation Wizard Settings

The Layout dropdown list includes the Mirror, RAIDZ1, RAIDZ2, and RAIDZ3 types.

Match the Dedup VDEV redundancy level to the data VDEV redundancy level. Pool creation fails when the Dedup VDEV redundancy is lower than the data VDEV redundancy.

VDEV Layouts

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.

Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts

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.

Automated Disk Selection - dRAID layouts

Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.

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.

Manual Selection Screen

The Manual Selection screen shows settings to add a Data VDEV Layout and the individual disks available to add to the new VDEV. You can filter disks by type or size.

Add places a VDEV area to populate with individual disks.

The screen shows disk icons for available disks. The system dropdown list also shows a list of available system disks. Use the disk filters separately or together to find disks of the same type and size. Drag disks to the VDEV to add them.

Save Selection creates the VDEV and closes the window.

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.

Review

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.

ZFS Info Card

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).

Disk Cards

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.

ZFS Info Card

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.

ZFS Info Card With Extend and Remove — Figure 5: ZFS Info Card with Extend and Remove

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.

Disk Info Card

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.

Hardware Disk Encryption Card

TrueNAS Enterprise
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.

Figure 10: Manage Disk SED 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.

Replacing Disk Dialog

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: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.

Wiping a Disk: Provides instructions for wiping a disk.

SLOG Over-Provisioning: Provides information on the disk_resize command in TrueNAS.

Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.

Disks Screen: Describes UI screens and dialogs related to disk operations.

Drive Health Management: Provides information and considerations for drive health.

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.

Replacing a Failed Disk

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.

Figure 1: Main Dashboard Pool and Storage Widgets Degraded

The Storage Dashboard pool widgets also show the status of each of your pools.

Figure 2: Storage Pool Widgets in Degraded State

From the main Dashboard, you can click the on either the Pool or Storage widget or you can click Storage on the main navigation menu to open the Storage Dashboard screen and locate the pool in the degraded state.

My disk is faulted. Should I replace it?

If a disk shows a faulted state, TrueNAS has detected an issue with that disk and you should replace it.

Can I use a disk that is failing but still active?

There are situations where you can leave a disk that has not completely failed online to provide additional redundancy during the replacement procedure.

We do not recommend leaving failed disks online unless you know the exact condition of the failing disk.

Attempting to replace a heavily degraded disk without offlining it significantly slows down the replacement process.

Taking a Failed Disk Offline

We recommend users off-line a disk before starting the physical disk replacement. Offlining a disk removes the device from the pool and can prevent swap issues. To offline a disk:

Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool. Click next expand the VDEV, then look for the disk with the REMOVED status.

Click on the failed disk, then click Offline in the ZFS Info widget to take the disk offline. The disk status changes to OFFLINE.

The offline failed?

If the off-line operation fails with a Disk offline failed - no valid replicas message, go to Storage Dashboard and click Scrub on the ZFS Health widget for the pool with the degraded disk. The Scrub Pool confirmation dialog opens. Select Confirm and then click Start Scrub.

When the scrub operation finishes, return to the VDEVs screen, expand the VDEV, then click the disk, and try to offline it again.

After offlining the failed disk, physically remove it from the system.

Replacing a Failed Disk Without a Hot Spare

After taking the failed disk offline and physically removing it from the system, insert the replacement disk now. The new disk must have the same or greater capacity as the failed disk. If replacing a failed disk with an available disk in the system, proceed to the next step.

Click Replace on the Disk Info widget on the Devices screen for the disk you off-lined.

Select the new drive from the Member Disk dropdown list on the Replacing disk dialog.

Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!

Preserve disk description maintains any descriptions associated with the original disk, which prevents you from needing to copy descriptors to the new disk manually. This option is enable by default. Select to clear the checkmark if you want the replacement disk to use descriptors that differ from those attached to the original disk.

Click Replace Disk to add the new disk to the VDEV and bring it online.

Disk replacement fails when the selected disk has partitions or data present. To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.

When the disk wipe completes, TrueNAS starts replacing the failed disk. TrueNAS resilvers the pool during the replacement process. For pools with large amounts of data, this can take a long time. When the resilver process completes, the pool status returns to Online on the Devices screen.

Refresh the screen to ensure the replacement disk appears in the pool as expected.

Replacing a Failed Disk With a Hot Spare

A Hot Spare vdev sets up 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.

Detaching a Failed Disk

After taking the failed disk offline and physically removing it from the system, go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool. Click next to the VDEV to expand it, then look for the disk with the REMOVED status.

Figure 7: Devices Disk Failed - Hot Spare Active

Click Detach on the ZFS Info widget on the VDEVs screen for the disk you off-lined.

Select Confirm, then click Detach. TrueNAS detaches the disk from the pool and promotes the hot spare disk to a full member of the pool.

Refresh the screen to ensure the promoted hot spare appears in the pool as expected.

Recreating a Hot Spare

After promoting the hot spare, recreate the Spare vdev and assign a disk to it.

Do I really need to promote the hot spare and then recreate the spare vdev?

If you have a hot spare inserted into the pool and then follow the instructions in Replacing a Failed Disk Without a Hot Spare, TrueNAS automatically returns the hot spare disk to the existing Spare vdev and ONLINE status.

However, we do not recommend this method because it causes two resilver events: one when activating the hot spare and again when replacing the failed disk. Resilvering degrades system performance until completed and causes unnecessary strain on the disk.

To avoid unnecessary resilvers, promote the hot spare by [detaching the failed disk]](#detaching-a-failed-disk) then recreate the hot spare vdev.

If recreating the spare with a replacement in place of the failed disk, insert the replacement disk now. The new disk must have the same or greater capacity as the failed disk. If recreating the spare with an available disk in the system, proceed to the next step.

Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.

Click Add VDEV to open the Add Vdevs to Pool screen.

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.

DiskScreenExpandedDiskWithWipeOption

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.

WipeDiskConfirmationDialog

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.

DiskWipeProgressDialog

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

TrueNAS Enterprise
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
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Managing Self-Encrypting Drives (SED)

TrueNAS Enterprise
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.

Supported Specifications

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 Implementation

TrueNAS implements the security capabilities of sedutil-cli for TCG-compliant devices.

You can configure a SED before or after assigning the device to a pool.

By default, SEDs are not locked until the administrator takes ownership of them. Ownership is taken by explicitly configuring a global or per-device password in the web interface and adding the password to the SEDs. Adding SED passwords in the web interface also allows TrueNAS to automatically unlock SEDs on boot.

A password-protected SED protects the data stored on the device when the device is physically removed from the system. This allows secure disposal of the device without having to first wipe the contents. Repurposing a SED on another system requires the SED password or a full cryptographic erase with PSID revert.

TrueNAS Enterprise
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.

Deploying SEDs

TrueNAS supports setting a global password for all detected SEDs or setting individual passwords for each SED. Using a global password for all SEDs is strongly recommended to simplify deployment and avoid maintaining separate passwords for each SED.

SED passwords are used during initial setup and for unlocking SEDs.

Configuring Global SED Settings

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!

Configuring Individual SED Passwords

To configure individual, per-disk SED passwords, go to Storage and click Disks in the top right of the screen to open the Disks screen. Click the row or expand_more for a confirmed SED to expand the row. Click Edit to open the Edit Disk screen.

Enter 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.

Check SED Functionality

When SED devices are detected during system boot, TrueNAS checks for configured global and device-specific passwords.

Unlocking SEDs allows a pool to contain a mix of SED and non-SED devices. Devices with individual passwords are unlocked with their password. Devices without a device-specific password are unlocked using the global password.

Managing SED Disks and Data

Improper use of the sedutil-cli can be destructive to data and passwords. Keep backups and use with caution.

Additional SED management options are available using a shell session and the sedutil-cli utility. Enter sedutil-cli -h or see the sedutil-cli.8 man page for more information.

TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial setup and management of SEDs using sedutil-cli.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

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.

Disks Screen - Expanded Disk

Click anywhere on a disk row to expand it and show the traits specific to that disk and available options. The expanded view of a disk includes details for the disk, options to edit disk properties, and, in some instances, the ability to wipe the disk. 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.

Batch Operations

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.

Bulk Edit Disks

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.

Bulk Edit Disks Settings

Setting

Description

HDD Standby

Select the minutes of inactivity before the drive enters standby mode from the dropdown list. Options are Always On or 5, 10, 20, 30, 60, 120, 240, 300, and 330. For more information, read this forum post describing identifying spun-down drives. Temperature monitoring is disabled for the standby disk.

Advanced Power Management

Select the power management profile from the dropdown list. Options are Disabled, Level 1 - Minimum power usage with Standby (spindown), Level 64 - Intermediate power usage with Standby, Level 127 - Maximum power usage with Standby, Level 128 - Minimum power usage without Standby (no spindown), Level 192 - Intermediate power usage without Standby, and Level 254 - Maximum performance, maximum power usage.

Wipe Disk Dialogs

The option to wipe a disk only displays when a disk is not assigned to a pool and is not in use. Wipe opens three dialogs: one to select the method, a confirmation dialog, and a progress dialog that includes the option to abort the process.

The Wipe Disk diskname opens after clicking Wipe on the expanded view of a disk on the Disks screen.

Method provides options for how you want the system to wipe the disk. Options are Quick, Full with zeros, or Full with random data. See Wiping Disks for more information.

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.

SED Unlock Dialog

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.

SED Reset Window

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.

Edit Disk Screen

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.

General Settings

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.

Power Management Settings

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:

Disabled (the default setting)

Level 1 - Minimum power usage with Standby (spindown)

Level 64 - Intermediate power usage with Standby

Level 127 - Maximum power usage with Standby

Level 128 - Minimum power usage without Standby (no spindown)

Level 192 - Intermediate power usage without Standby

Level 254 - Maximum performance, maximum power usage

SED Password

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 Considerations

Enterprise deployments benefit from additional protections and processes built around DHM:

Factory burn-in testing (running drives at sustained load before deployment) significantly reduces failure rates.
TrueNAS DHM is designed to scale across large drive counts (1000+) without increasing administrator and system resource overheads.
When an alert appears, review the alert details to determine the recommended action.
For guidance on drive replacement or interpreting a specific alert condition, contact iXsystems support.

How DHM Works in TrueNAS 25.10 and Later

SMART Integration

TrueNAS integrates SMART stats collection directly into the middleware, which provides consistent handling across all supported drive types and vendors.

SMART polls drives every 90 minutes. When a polled attribute crosses a threshold indicating a likely failure, TrueNAS alerts the user.

ZFS as Real-Time Failure Detection

ZFS acts as the primary detector for sudden, unexpected drive failures. Unlike SMART polling, which runs on a schedule, ZFS detects failures immediately when a read or write operation returns an error.

When ZFS encounters an unrecoverable error, it marks the affected VDEV or disk as faulted and generates an alert. ZFS and SMART work together: SMART catches degrading drives before they fail, while ZFS catches drives that fail without prior warning.

Alert Logic

TrueNAS evaluates incoming SMART data and ZFS events against alert rules before generating a notification. This filtering suppresses known-benign attribute fluctuations and only notifies users about conditions that require attention, reducing false-positive alerts by approximately 50% compared to prior releases.

Alert Levels can be adjusted to control notification severity. Higher-priority alerts appear in the Alerts panel and can trigger configured alert services (email, SNMP, etc.).

TrueNAS configures automated temperature alerts based on the specified maximum operating temperature of each drive. If a drive reports a temperature that exceeds its rated maximum, TrueNAS generates an alert.

Monitoring Drive Health

To view drive health status, go to the Storage dashboard and view the Disk Health card.

Active alerts appear in the Alerts panel at the top right of the UI. Click an alert to expand it and view details, including the affected disk, the attribute or event that triggered the alert, and recommended next steps.

Alert Types

Type	Description
SMART Stat	A drive-reported diagnostic value crossed a failure threshold. The alert identifies the specific attribute (for example, Reported Uncorrectable Error) and the current value.
ZFS Event	ZFS detected an I/O error or checksum failure during a read or write operation. These alerts indicate the disk might have failed or is failing.
Temperature	Drive temperature exceeded the rated maximum from the manufacturer specification.

SMART Test Options for Community Edition

TrueNAS handles SMART testing through its automated DHM polling. The manual SMART test options described in this section are primarily intended for Community Edition users who want additional drive validation beyond the automated 90-minute polling.

Cron Jobs

You can schedule manual SMART tests using Cron Jobs in the TrueNAS UI.

TrueNAS logs cron job output. Review the system log or configure the cron job to send output to a file for later review.

Manual Drive Tests

The manual SHORT test performs a quick, surface-level diagnostic check. It typically completes within a few minutes and has minimal performance impact on drives used in a ZFS pool. It is suitable for nightly or weekly scheduling as a routine check.

The manual LONG test performs a full drive surface scan for periodic, deep validation. It provides a thorough validation of the entire drive surface, but has a significant negative performance impact during the test. LONG tests can also produce false-positive failure results on healthy drives.

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.

Deprecated API for SMART Testing

TrueNAS 25.10+ has an unsupported API call it can leverage to start a SMART test on all drives with the default parameters. Use at your own risk or switch to a custom smart command where advanced options are required for stability or functionality.
To run the command, use midclt call disk.smart_test {SHORT|LONG} '["*"]'

Third-Party Tools

Additional drive introspection and analysis tools are available outside of TrueNAS. These tools can supplement DHM data with more detailed vendor-specific diagnostics. Consult the documentation for any third-party tool before running it against drives in an active ZFS pool.

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.

No Pools Screen

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.

Storage Dashboard

After adding pools, the dashboard shows the pool widgets, the Update and Disconnect buttons, and a more_vert 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.
Figure 3: 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.
Expand Pool
Select Expand Pool on the more_vert dropdown menu to increase the pool size to match all available disk space. Users with pools using virtual disks use this option to resize these virtual disks apart from TrueNAS.
Figure 4: Expand Pool Dialog
Confirm activates the Continue button.
AutoTrim
The Auto TRIM option on the more_vert dropdown menu opens the AutoTRIM dialog. The ZFS Health widget shows whether this function is set to on.
Figure 5: Pool Option AutoTRIM
When enabled, Auto TRIM allows TrueNAS to periodically review data blocks and identify which empty blocks of obsolete blocks it can delete. Leave unselected to incorporate day block overwrites when a device write is started (default). Select Confirm to activate Save.
For more details about TRIM in ZFS, see the autotrim property description in zpool.8.
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.
Figure 6: Upgrade Pool Dialog
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.

Storage Dashboard Widgets

After adding a pool, the screen displays storage and pool widgets.

The set of four pool widgets and the Export/Disconnect and Expand buttons show for each pool created on the system.

Each set of pool widgets provides access to screens for disks, datasets, VDEVs, snapshots, quotas, and pool ZFS functions for the pool. For example, Manage Devices on the Topology widget opens the Devices screen with the VDEVs configured for only that pool.

Unassigned Disks and Disks with exported pools Widgets

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.
Figure 8: Add To Pool New 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.
Figure 9: Add To Existing Pool
Figure 10: Add To Existing Pool (Legacy)
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.

Status Indicators

Each pool widget includes a color-coded icon just to the right of the header, near the VDEV lists to indicate the state of the pool VDEV, or near disks in the VDEV. Possible states are:

Green circle with checkmark for a Healthy
Orange circle with an exclamation mark for No Redundancy or Pool is Unhealthy
Red circle with an x for Pool is not Healthy

This same information displays on the main Dashboard on the Storage widget and a pool widget.

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.

Configure Scheduled Scrub Screen

The Configure Scheduled Scrub screen sets a schedule for TrueNAS to run a scrub operation.

A scrub is a data integrity check of your pool. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts. By default, TrueNAS automatically checks every pool to verify it is on a recurring scrub schedule. If TrueNAS detects problems during the scrub, it corrects them automatically or generates an alert.

Enabled shows the schedule information on the Storage Health dashboard as the value for Scheduled Scrub. When disabled, Scheduled Scrub changes to Not Set and shows the Schedule link. Schedule opens the Configure Scheduled Scrub screen.

Schedule shows a dropdown list of schedule options:

Hourly, which runs the scrub at the start of each hour.
Daily, which runs a scrub at 00:00 on the 24-hour clock. This is the time period where system processes and demands are likely at the lowest point, and where it reduces the drain on system resources.
Weekly, which runs the scrub on Sundays at 00:00 for the same reason as with the Daily option.
Monthly, which runs on the first day of the month at 00:00.
Custom, which runs at 12.00 AM, only on Sunday. ** Create, which opens the custom schedule window where you can select the frequency (how often it runs), time (in hours and minutes), start or finish times, and set a time zone.

Threshold Days sets the days before a completed scrub is allowed to run again. This controls the task schedule. For example, scheduling a scrub to run daily and setting threshold days to 7 means the scrub attempts to run daily. When the scrub is successful, it continues to check daily but does not run again until seven days have elapsed. Using a multiple of seven ensures the scrub always occurs on the same weekday.

Save sets the schedule and adds the time and frequency to the Storage Health widget.

Starting in TrueNAS 25.10, resilver priority settings are now located in System Settings > Advanced Settings on the Storage widget.

Prune Deduplication Table Dialog

The Prune Deduplication Table dialog shows pruning measurement options the system should use when pruning the deduplication table (DDT). Options are Percentage and Age.

Percentage shows a slider to set the size (maximum amount of storage) percentage threshold the DDT is filled before it reaches the maximum size. When reached, the system prunes the table.

Figure 15: Prune Deduplication Table - Percentage

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.

Figure 16: Prune Deduplication Table - Age

Deduplication Qutoa Dialog

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.

Deduplication Quota for Pool Dialog — Figure 17: Prune Deduplication Table Dialog

Custom shows the Custom Qutoa field where you enter the maximum size of the DDT (quota).

Deduplication Quota for Pool - Custom — Figure 18: Prune Deduplication Table - Custom

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.

Section Contents

Datasets

This section has tutorials about dataset configuration and management.

Adding and Managing Datasets: Provides instructions on creating and managing datasets.

Encryption: Tutorials and UI reference to configure dataset and zvol encryption in TrueNAS.

Encrypting Datasets: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.
Encryption Screen: Provides information on the settings and functions found on the TrueNAS storage encryption screens.

Permissions: Tutorials and UI reference to configure dataset ACL permissions in TrueNAS.

Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.
Edit ACL Screen: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.

Quotas: Tutorials and UI reference to configure dataset capacity settings and user or group quotas in TrueNAS.

Managing User or Group Quotas: Provides information on managing user and group quotas.
Capacity Settings Screen: Provides information on the quota settings and functions found on the Capacity Settings screen.
User and Group Quota Screens: Provides information on the settings and functions found on the User and Group Quota screens.

Snapshots: Tutorials and UI reference to create and manage dataset snapshots in TrueNAS.

Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.
Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.
Snapshots Screens: Provides information on the settings and functions found on the Snapshots screen.

Zvols: Tutorials and UI reference to create and manage zvols in TrueNAS.

Adding and Managing Zvols: Provides instructions on creating, editing, and managing zvols.
Zvols Screen: Provides information on the settings and functions found on the Zvol screens and widgets.

Datasets Screens: Provides information on the Datasets screens and settings.

Adding and Managing Datasets

A TrueNAS dataset is a file system within a data storage pool. Datasets can contain files, directories, and child datasets, and have individual permissions or flags.

Datasets can also be encrypted. In TrueNAS 22.12.3 or later, the TrueNAS UI requires encryption for child datasets created in encrypted parent datasets, but you can change the encryption type from key to passphrase. You can create an encrypted dataset if the parent is not encrypted and set the type as either key or passphrase.

We recommend organizing your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.

Creating a Dataset

To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.

Select a dataset (root, parent, or child), then click Add Dataset.

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.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.

If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.

Click Save.

Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.

Setting Dataset Compression Levels

Compression encodes information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of saved space.

Figure 2: Add Dataset Compression Level 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.

Setting Dataset Quotas

You can set dataset quotas while adding datasets using the quota management options in the Add Dataset screen under Advanced Options. You can also add or edit quotas for an existing dataset, by clicking Edit on the Dataset Space Management widget to open the Capacity Settings screen.

Figure 3: Add Dataset Advanced Quota Options

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.

Changing Dataset Inherited Values

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.

Setting Datasets Access Controls

For information on ACL settings see Setting Up Permissions.

Adding Deduplication

Deduplication is found on the Add Datasets Advanced Settings screen.

Best practice is to add deduplication when you first create the dataset.
You can add deduplication to an existing dataset but existing files do not have deduplication applied to them. Adding deduplication to an existing dataset only applies deduplication to data written after you enable the function.
When enabling deduplication for a dataset of a pool that does not have a deduplication or special VDEV, the deduplication table (DDT) is stored on a regular VDEVs of the pool. To store the DDT outside of the regular VDEVs, add a deduplication or special VDEV to the pool.

To add deduplication to a new dataset, after entering the name and selecting the dataset preset, click Advanced Settings.

To add deduplication to an existing dataset, select the dataset on the Dataset screen tree table, click Edit on the Dataset Details widget to open the Edit Dataset screen. Click Advanced Settings.

Scroll down to the ZFS Deduplication setting, then change to On. A warning dialog opens and states that deduplication is an experimental and not fully supported feature.

Click Continue.

Change Checksum to SHA512.

Complete any other setting changes you want to make, then click Save.

Creating a Dataset for a Fusion Pool

First, add the pool with a Metadata VDEV.

Figure 5: Pool Creation Wizard Metadata Step

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.

Managing Datasets

After creating a dataset, users can manage additional options from the Datasets screen. Select the dataset, then click Edit on the dataset widget for the function you want to manage. The Datasets Screen article describes each option in detail.

Editing a Dataset

Select the dataset on the tree table, then click Edit on the Dataset Details widget to open the Edit Dataset screen and change the dataset configuration settings. You can change all settings except Name, Case Sensitivity, or Device Preset.

Editing Dataset Permissions

To edit the dataset ACL permissions, click Edit on the Permissions widget. If the ACL type is NFSv4, the Permissions widget shows ACE entries for the dataset. Each entry opens a checklist of flag options you can select or clear without opening the Edit ACL screen. To modify ownership, configure new or change existing ACL entries, click Edit to open the ACL Editor screen.

To edit a POSIX ACL type, click Edit on the Permissions widget to open the Unix Permissions Editor screen. To access the Edit ACL screen for POSIX ACLs, select Create a custom ACL on the Select a preset ACL window.

For more information, see the Setting Up Permissions article.

Deleting a Dataset

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: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.

Encryption Screen: Provides information on the settings and functions found on the TrueNAS storage encryption screens.

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).

Pool and Dataset Encryption

Encryption is for users storing sensitive data. It does not apply encryption to the storage vdev or the disks in the pool.

Encrypting the root dataset (pool-level encryption) creates a single point of failure. Losing one key makes the entire pool inaccessible.
Best practice Do not enable encryption during pool creation. Instead, create an unencrypted pool with individually encrypted datasets and zvols. This allows independent key management, selective unlock, isolated failures, and simplified recovery.

Leave Encryption unselected on the Pool Creation Wizard screen to create a pool with an unencrypted root dataset. You can create both encrypted and unencrypted datasets within an unencrypted pool.

By default, child datasets inherit encryption settings from the parent. Disabling Inherit under Advanced Options allows modifying the encryption configuration for a child dataset.

You cannot change a child dataset of an encrypted parent dataset to unencrypted. However, datasets created outside the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured. For example, the ix-apps dataset on the pool selected for applications does not inherit encryption settings.

Can I change dataset encryption?

Before saving a new dataset, you can change the type of encryption of an encrypted dataset to key to passphrase. After saving a dataset with encryption applied, you cannot change the dataset to unencrypted.

Can I unencrypt my data?

Yes, you can move encrypted data to an unencrypted pool or dataset using either rsync or replication. You can also move data from an unencrypted pool or dataset to an encrypted dataset using rsync or replication.

If your system loses power or you restart the system, all encrypted datasets and zvols automatically lock to protect data.

Encryption Visual Cues

TrueNAS uses lock icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen. Each icon shows a text label with the state of the dataset when you hover the mouse over the icon.

The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.

Icon	State	Description
	Locked	Displays for locked encrypted root, non-root parent and child datasets.
	Unlocked	Displays for unlocked encrypted root, non-root parent and child datasets.
	Locked by ancestor	Displays for locked datasets that inherit encryption properties from the parent.
	Unlocked by ancestor	Displays for unlocked datasets that inherit encryption properties from the parent.

A dataset that inherits encryption shows the mouse hover-over label Locked by ancestor or Unlocked by ancestor.

Select an encrypted dataset to see the ZFS Encryption widget on the Datasets screen.

The dataset encryption state is unlocked until you lock it using the Lock button on the ZFS Encryption widget. After locking the dataset, the icon on the tree table changes to locked, and the Unlock button appears on the ZFS Encryption widget.

Implementing Encryption

Before creating a encrypted pool (root dataset) or dataset, decide if you want to encrypt all child datasets, zvols, and data stored on that dataset.

If your system does not have enough disks to create a second storage pool, we recommend not using encryption at the pool level. Apply encryption at the dataset level to non-root parent or child datasets.

All pool-level encryption is key-based encryption. When prompted, download the encryption key and keep it stored in a safe place where you can back up the key file. You cannot use passphrase encryption at the pool level.

You cannot change an existing dataset from encrypted to unencrypted. You can only change the dataset encryption type (key or passphrase).

Adding Encryption to a New Pool

Encrypting the root dataset (pool-level encryption) creates a single point of failure. Losing one key makes the entire pool inaccessible.
Best practice Do not enable encryption during pool creation. Instead, create an unencrypted pool with individually encrypted datasets and zvols. This allows independent key management, selective unlock, isolated failures, and simplified recovery.

Go to Storage and click Create Pool on the Storage Dashboard screen. Or click Add to Pool on the Unassigned Disks widget and click Add to New to open the Pool Creation Wizard.

Enter a name for the pool, then select Encryption. Select the layout for the data VDEV and add the disks. A warning dialog displays after selecting Encryption.

Read the warning, select Confirm, and then click I UNDERSTAND.

A second dialog opens where you click Download Encryption Key for the pool encryption key.

Figure 1: Download Encryption Key on Pool Manager

Click Done to close the window. Move the encryption key to safe location where you can back up the file.

Add the VDEVs to the pool you want to include, then click Save to create the pool with encryption.

Adding Encryption to a New Dataset

To add an encrypted dataset, go to Datasets.

Select a dataset 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.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

Click Advanced Options. To add encryption to a dataset, scroll down to Encryption Options and select the inherit checkbox to clear the checkmark and show the Encryption option. Clear this checkbox to show the default settings for key type encryption. If the parent dataset is unencrypted and you want to encrypt the dataset, select the Inherit (non-encrypted) checkbox to clear it and show the Encryption option. If the parent dataset is encrypted and you want to change the type, select Inherit (encrypted) to show the encryption configuration options. To keep the dataset encryption settings from the parent, leave inherit selected.

Figure 2: Add Dataset Encryption Options Clear Inherit

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.

What are these options?

TrueNAS supports AES Galois Counter Mode (GCM) and Counter with CBC-MAC (CCM) algorithms for encryption. These algorithms provide authenticated encryption with block ciphers.

Changing Dataset (or Zvol) Encryption

You cannot add encryption to an existing dataset!

You can change the type of encryption for an already encrypted dataset using the Edit option on the Encryption widget for the dataset.

Save changes to the encryption key or passphrase, update your saved passcodes and keys file, and back up that file.

To change the encryption type, go to Datasets, select the encrypted dataset on the tree table, then click Edit on the Encryption widget. The Edit Encryption Options dialog for the selected dataset opens.

Before making changes to a locked encrypted dataset you must unlock it.

If the dataset inherits encryption settings from a parent dataset, to change this, clear the Inherit encryption properties from parent checkbox to display the key type encryption setting options.

Figure 5: Edit Encryption Window - Inherited

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.

Locking and Unlocking Datasets

You can only lock and unlock an encrypted dataset if it is secured with a passphrase instead of a key file. Before locking a dataset, verify that it is not currently in use.

Locking a Dataset

Select the encrypted dataset on the tree table, then click Lock on the Encryption widget to open the Lock Dataset dialog with the full path name for the dataset.

Use the Force unmount option only if you are certain no one is currently accessing the dataset. Force unmount boots anyone using the dataset (e.g. someone accessing a share) so you can lock it. Click Confirm to activate Lock, then click Lock.

You cannot use locked datasets.

Unlocking a Dataset

To unlock a dataset, go to Datasets then select the locked dataset on the tree table. Click Unlock on the Encryption widget to open the Unlock Dataset screen.

Enter the key if key-encrypted, or the passphrase into Dataset Passphrase and click Save.

Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.

Select Force if the dataset mount path exists but is not empty. The unlock operation fails when this happens. Using Force allows the system to rename the existing directory and file where the dataset should mount which prevents the mount operation from failing. A confirmation dialog displays.

Figure 10: Continue Dataset Unlock Confirmation

Click CONTINUE to confirm you want to unlock the datasets. Click CLOSE to exit and keep datasets locked. A second confirmation dialog opens confirming the datasets unlocked. Click CLOSE. TrueNAS displays the dataset with the unlocked icon.

Encrypting a Zvol

Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.

To encrypt a Zvol, select a parent dataset and then create a new Zvol. If the parent dataset is encrypted, select Inherit (encrypted) under Encryption Options. If the parent dataset is not encrypted, disable Inherit (non-encrypted), select Encryption, and then configure the Encryption Type and related settings.

Next, go to Datasets and click on the Zvol and locate the Encryption widget.

ZFS Encryption Widget Root Dataset — Figure 11: ZFS 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.

Managing Encryption Credentials

There are two ways to manage the encryption credentials, with a key file or passphrase. Creating a new encrypted pool automatically generates a new key file and prompts users to download it.

Always back up the key file to a safe and secure location.

To manually back up a root dataset key file, click Export Key on the Encryption widget.

Figure 13: Edit Root Dataset Encryption Keys

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.

Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase

TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.

Method 1: Construct JSON Manifest.

Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this: {"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.

Method 2: Replicate Encrypted Dataset/zvol Without Properties.

Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.

Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.

Method 3: Replicate Key Encrypted Dataset/zvol.

Go to Datasets on the system you are replicating from. Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset. Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.

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.

Figure 1: 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.

Dataset Encryption

The Encryption option on the Pool Manager screen sets encryption for the entire pool.

Encrypting the root dataset (pool-level encryption) creates a single point of failure. Losing one key makes the entire pool inaccessible.
Best practice Do not enable encryption during pool creation. Instead, create an unencrypted pool with individually encrypted datasets and zvols. This allows independent key management, selective unlock, isolated failures, and simplified recovery.

The Download Encryption Key warning window opens when you create the pool. It downloads a JSON file to the downloads folder on your system.

The Encryption Options settings under Advanced Options on the Add Dataset screen configure encryption for that dataset.

Figure 3: Add Dataset Encryption Options Key

Export Key Options

The Encryption widget for root datasets with encryption includes the Export All Keys and Export Key options. It does not include the Lock option.

If a dataset is encrypted using a key, the Encryption widget for that dataset includes the Export Key option.

Export All Keys Dialog

Export All Keys opens a confirmation dialog with the Download Keys option that exports a JSON file of all encryption keys to the system download folder.

Export Key Dialog

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.

Edit Encryption Options Window

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.

Figure 6: Encryption Options Key Type Window

Encryption Settings

Setting	Description
Encryption Type	Shows two encryption type options: Key - Shows key-based encryption settings. Shows a system-generated key field, an option to use a manual entry key, and key-based encryption algorithms. Passphrase - Shows text fields for manual or copy/paste entry of a passphrase, and passphrase authentication algorithms.
Generate key	Shows when Encryption Type is set to Key. Selected by default and sets TrueNAS to generate a random encryption key for securing the dataset. Clearing the checkbox shows the Key field that accepts manual or copy/paste entry of an encryption key. Warning! The encryption key is the only means to decrypt the information stored in a key-encrypted dataset. Store encryption keys in a secure location! Creating a new key file invalidates a previously downloaded key file (for this dataset). Delete any previous key file backups and back up the new key file.
Key	Text entry field that accepts manual or copy/paste entry of an encryption key string to secure the dataset.
Algorithm	Shows a dropdown list of mathematical instruction algorithms that determine how plaintext converts into ciphertext for key and passphrase encryption types. See Advanced Encryption Standard (AES) for more details on each option.
Passphrase Confirm Passphrase	Text entry fields that accept manual or copy/paste entry of an alphanumeric string or phrase to secure the dataset.
pbkdf2iters	Sets the number of password-based key deviation function 2 (PBKDF2) iterations used for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.

Lock Dataset Dialog

Lock shows on the Encryption widgets when you encrypt a dataset (or zvol) with a passphrase. An encrypted child that inherits encryption from an encrypted parent does not see the Lock option on its Encryption widget when the lock state is controlled by the parent dataset for that child dataset. The locked icon for child datasets that inherit encryption is the locked by ancestor icon.

Lock opens the Lock Dataset confirmation dialog with the option to Force unmount and Lock the dataset. Force unmount disconnects any client system accessing the dataset via the sharing protocol. Do not select this option unless you are certain the dataset is not used or accessed by a share, application, or other system services.

After locking a dataset, the Encryption screen displays Locked as the Current State and adds the Unlock option.

Unlock Datasets Screen

Unlock on the Encryption widget shows for locked datasets that are not child datasets that inherit encryption from the parent dataset. Unlock opens the Unlock Datasets screen, which is used when you unlock the selected dataset and child datasets simultaneously.

Figure 8: Unlock Non-Root Parent and Child Datasets Screen

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.

Unlock Dataset Settings

Setting	Description
Unlock Child Encrypted Roots	Unlocks any encrypted dataset stored within this dataset.
Dataset Passphrase Dataset Key	Text entry field that accepts manual or copy/paste entry of the user-defined string (passphrase) or system-generated or user-created alphanumeric key entered when you created the dataset.
Force	Adds a force flag to the operation. In some cases, the provided key/passphrase might be valid, but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, the unlock operation fails. Adding the force flag can override this, and when selected, the system renames the existing dataset mount directory/file path and unlocks the dataset.
Save	Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Continue unlocks the dataset.
Save	Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Continue unlocks the dataset.

Permissions

TrueNAS provides ACL-based permission controls for datasets to manage user and group access to stored data.

Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.

Edit ACL Screen: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.

Configuring ACL Permissions

TrueNAS provides basic permissions settings and an access control list (ACL) editor to define dataset permissions. ACL permissions control the actions users can perform on dataset contents and shares.

An Access Control List (ACL) is a set of account permissions associated with a dataset that applies to directories or files within that dataset. TrueNAS uses ACLs to manage user interactions with shared datasets. When you create a dataset, TrueNAS sets the ACL type based on the dataset preset, but you must configure the ACL before it becomes active.

ACL Types in TrueNAS

TrueNAS offers two ACL types: POSIX and NFSv4. The Dataset Preset setting on the Add Dataset screen determines the type of ACL for the dataset. Datasets created with the Generic dataset preset have the ACL type set to a POSIX (Unix) ACL. Datasets created with the SMB dataset preset have the ACL type set to an NFSv4 ACL. SMB shares require the more robust configurations in an NFSv4 ACL.

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.

How do I know what ACL Type my dataset has?

The Permissions widget for the dataset shows the dataset ACL type. When Unix Permissions shows in the widget, the dataset has a POSIX ACL.

Alternatively, click Edit on the Dataset Details widget for the dataset to open the Edit Dataset screen, then click Advanced Options and scroll down to the ACL Type field to see the ACL type.

You can also check the ACL type while on the Edit ACL screen by clicking Use Preset, then clicking the down arrow for the Preset field in the Select a preset ACL window.

TrueNAS does not allow creating an ACL for the root dataset of a pool.

TrueNAS POSIX or NFSv4 ACL types, show different options on the ACL Editor screen. Both the POSIX and NFSv4 ACL Editors screens allow you to:

Select a pre-configured ACL by clicking Use Preset and then selecting a Preset option
Customize the ACL by defining the owner user and group and adding ACL entries (ACEs) for individual user accounts or groups
Select a preset and customize the ACL

When using a preset and customising the ACL, select the preset first and then customize the ACL with new users or groups. Selecting the preset after adding new ACL entries (ACEs) erases any ACEs added to the ACL, requiring you to re-enter them. Click Save Access Control List when you are done configuring the ACL. In most cases, the owner user and group should remain set to root, but you can change this to the primary admin user and group account with full privileges. Add ACE items for users, groups, directories, etc., not included in preset configurations, to customize access permissions to the dataset.

When adding a dataset using the SMB preset for a share or just setting up an NFSv4 ACL, TrueNAS shows the Set ACL for this dataset dialog after you save the dataset. Click Go to ACL Manager to configure the ACL. You must configure an ACL for the dataset. The dataset does not have an ACL until you configure it even though you see ACL information in the Permissions widget. This initially indicates the type of ACL created and the default basic permissions. To access the dataset and files within it, you must set up the ACL with users and access permissions.

If you want to defer configuring the ACL, click Return to pool list, but make a note to return to the dataset to configure the ACL before attempting to use it.

Changing the ACL type affects how TrueNAS writes and reads on-disk ZFS ACLs.
When the ACL type changes from NFSv4 to POSIX, native ZFS ACLs do not convert to POSIX1e extended attributes, but ZFS uses the native ACL for access checks.
To prevent unexpected permissions behavior, you must manually set new dataset ACLs recursively after changing the ACL type.
Setting new ACLs recursively is destructive. We suggest creating a ZFS snapshot of the dataset before changing the ACL type or modifying permissions.

While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.

Configuring POSIX ACL Permissions

The Unix Permissions Editor screen shows for datasets using the Generic dataset preset.

Accept the default root in Owner and Owner Group, or if you want to change this to a system administrator with full permissions, select the admin user name from each dropdown list, then click Apply Owner and Apply Group to make the change.

Next, select the Access levels using the Read, Write, Execute checkboxes for User, Group, Other.

Click Save to save changes and close the Unix Permissions Editor screen. To further define the POSIX ACL, click Set ACL to open the Select a preset ACL window with two options: Select a preset ACL and Create a custom ACL.

Accept the default option Select a preset ACL to choose from the options on the Preset dropdown list. Select Create a custom ACL to open the Edit ACL screen for a POSIX ACL with a minimal default configuration. Selecting a preset also opens the Edit ACL screen, but with different default configurations based on the preset selected.

After selecting a preset, click Continue to close the preset window and show the Edit ACL screen for a POSIX ACL. Next add ACL entries.

POSIX Preset Options

TrueNAS built-in presets automatically include entries for the builtin_users and builtin_administrators groups. If the system is joined to Active Directory, entries for domain users and domain admins are also added. After selecting a preset, these entries appear in the ACL editor. TrueNAS allows removing any unwanted entries before saving changes to the ACL.

This automatic expansion applies only to the built-in presets shipped with TrueNAS and does not apply to user-created presets.

POSIX_OPEN - Gives the owner and group full dataset control. All other accounts can modify the dataset contents. Use for collaborative datasets where multiple users need read/write access.
POSIX_RESTRICTED - Gives the owner full dataset control. The group can modify the dataset contents. Others have no access. Use when you want group collaboration but need to restrict outside access.
POSIX_HOME - Gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset, but cannot read or modify files. Use for private user directories where others need to traverse the path but not access the contents.
POSIX_ADMIN - Gives the admin user and builtin_administrators group full dataset control. All other accounts can navigate the dataset but cannot read or modify files. Use for administrative datasets that only system administrators should access.

Adding POSIX ACL Entries

The Edit ACL screen shows the ACL owner and owner group and allows you to change both, just as you can on the Unix Permissions Editor screen. It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.

You can define the ACE entries when you first configure the POSIX ACL or change ACL entries (ACEs) and permissions for ACEs. To edit an existing POSIX ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.

When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.

Click Add Item below the Access Control List on the left side of the screen. If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List. With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen. Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset. Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset. This shows the Group field. The group must be defined on the system. In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users. Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.

The options are Read, Modify, and/or Execute permissions.

(Optional) Select Default under Flags.
The POSIX flag for an ACL entry controls inheritance for newly created files and directories. The default flag can only be set on directories, not on files. When Default is selected, the ACL entry becomes a default ACL that applies to new objects created inside that directory, but it does not affect the access permissions of the current directory, just controls what new files/directories inherit. New files inherit the default ACL as their access ACL. New directories inherit the default ACL as both their access ACL and their default ACL. This continues down the tree of files and directories.
If not set, the ACL entry only affects access to the directory itself; new files and directories created inside the dataset do not inherit the permission.

(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets. This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.

If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.

If you change your mind and want to discard the changes and revert to using a preset, click Use Preset. This reopens the Select a Preset window where you can select a different preset to apply to the dataset.

Changing an ACL Owner or Owner Group

This applies to both POSIX and NFSv4 ACLs. The Edit ACL screen for POSIX and NFSv4 ACLs shows different configuration options, but the Owner and Owner Group settings are the same for both ACL types.

Think of the owner of the ACL as the main traffic cop granting other users access. In most cases, leave the default user set to root. To allow a system administrator access, either change the owner and owner group to that admin user name, or add that admin user as an ACL entry (ACE) and grant it full permissions to allow it to administer the ACL and configure the dataset for other functions like an SMB share.

To change the owner and owner group:

Select the Owner user from the User dropdown list. To filter the list of users, begin typing the name in the field. Click Apply Owner to apply the change. Next, change the Owner Group in the same manner as changing the owner. Click Apply Group to apply the group change.

User and group options include those created manually or imported from a directory service.

To prevent errors, TrueNAS only submits changes after you select the apply options.

A common misconfiguration is not adding or removing the Execute permission from a dataset that is a parent to other child datasets. Removing this permission results in lost access to the path.

If only changing the owner and owner group, click Save Access Control List.

If adding ACL entries, refer to the instructions for each ACL type.

To apply ACL settings to all child datasets, select Apply permissions recursively.

Change the default settings to your preferred primary account and group and select Apply permissions recursively before saving any changes.

See Edit ACL Screen for information on the ACL editor screens and setting options.

Users can grant root permissions to containers and instances through an unprivileged root account using the ACL editor in the UI or the TrueNAS API.
To ensure functionality, add an ACE for the truenas_container_unpriv_root user and assign the appropriate permissions (such as Read, Modify, and Execute).
For container environments, verify that the ACL includes an entry for truenas_container_unpriv_root with the required access to any dataset paths used by the container.
See Granting Root Access to Host Paths for more information.

Configuring an NFSv4 ACL

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 not to 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 use 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.

Figure 4: Permissions Widget Showing Unix 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.

Figure 5: Permissions Widget for an NFSv4 ACL

To edit or configure an NFSv4 ACL, select the dataset in the dataset tree table, then click Edit on the Permissions widget to open the Edit ACL screen.

You can change the owner and owner group, and/or change, add, or delete an ACE item on the Access Control List.

Either change the owner and owner group to the admin user on your system with full administration privileges, or add the admin user name as an ACE item on the Access Control List. This allows the admin user to make functional changes for the dataset and child datasets nested under it. For example, when configuring shares and private dataset shares.

To rewrite the current ACL with a standardized preset, click Use Preset on the Edit ACL screen, which opens the Select a preset ACL window.

Select the preset option, then click Continue to apply the preset. Presets load pre-configured permissions to match general permissions situations.

NFSv4 ACL Presets

This automatic expansion applies only to the built-in presets shipped with TrueNAS and does not apply to user-created presets.

NFS4_OPEN gives the owner and group full dataset control. All other accounts can modify the dataset contents.
NFS4_RESTRICTED gives the owner full dataset control. The group can modify the dataset contents.
NFS4_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_DOMAIN_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_ADMIN gives the admin user and builtin_administrators group full dataset control. All other accounts can navigate the dataset.

Adding NFSv4 ACL Entries

The Edit ACL screen shows the ACL owner and owner group and allows you to change both. It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.

You can define the ACE entries when you first configure the NFSv4 ACL or change ACL entries (ACEs) and permissions for ACEs when you edit an existing ACL. To edit an existing NFSv4 ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.

When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.

Click Add Item below the Access Control List on the left side of the screen. If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List. With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen. Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset. Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset. This shows the Group field. The group must be defined on the system. In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users. Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.

If Basic is selected, the Permissions dropdown list shows four options: Read, Modify, Traverse, and Full Control. If Advanced is selected, the Permissions dropdown list shows 14 checkboxes for more granular control over the permissions granted to the selected ACE entry. Options are: Read Data, Write Data, Append Data, Read Named Attributes, Write Named Attributes, Execute, Delete Children, Read Attributes, Write Attributes, Delete, Read ACL, Write ACL, Write Owner, and Synchronize.

(Optional) Select the ACL flags to apply the ACE item selected on the Access Control List, not to the entire ACL. Each ACE entry can have different flags set. Flags apply to the files, directories, and subdirectories created in this dataset. Flag options:
- Basic shows the Inherit and No Inherit flags. Just as with the POSIX Default flag, this determines if files and directories in this dataset, for the ACE item selected (for example, a user item selected on the Access Control List), inherit the ACL from the dataset.
- Advanced shows five flags for more granular control. Flag options are:
  - File Inherit - Selected by default. Limits ACL inheritance for files in the dataset for the selected ACE item.
  - Directory Inherit - Selected by default. Limits ACL inheritance for directories in the dataset for the selected ACE item.
  - No Propagate Inherit - Limits ACL inheritance to direct child directories. Files and directories created in this dataset inherit the ACL, but subdirectories cannot pass it further down the tree for the selected ACE item.
  - Inherit Only - Removes the ACE from permission checks but allows new files or subdirectories to inherit it for this dataset and the selected ACE item. Inherit Only is removed from these new objects.
  - Inherited - Selected by default. Indicates the selected ACE item inherited the ACL from the parent dataset (set by TrueNAS).
Selecting Advanced allows more granular control of file and directory permissions for a selected ACE item (such as a user) on the Access Control List. See Debian nfs4_setfacl(1) NFSv4 ACL ENTRIES.

(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets. This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.

If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.

Viewing Permissions

Basic ACL permissions are viewable and configurable from the Permissions widget on the Datasets screen. Select a dataset, then scroll down to the Permissions widget to view owner and individual ACL entry permissions.

To view the Edit ACL screen, select the dataset and click Edit on the Permissions widget, or go to Sharing and click on the share widget header to open the list of shares. Select the share, then click the options icon and select Edit Filesystem ACL.

You can view permissions for any dataset, but the edit option only displays on the Permissions widget for non-root datasets.

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 edit icon on the Dataset Permissions widget.

Set ACL Type to NSFv4 to activate and select which ACL Mode the dataset uses.

While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.

Unix Permissions Editor Screen

If you set Dataset Preset to Generic, or selected POSIX or Inherit as the ACL Type settings on the Add Dataset > Advanced Options screen, the first screen you see after clicking Edit on the Permissions widget is the Dataset > Edit Permissions screen Unix Permissions Editor.

Use the settings on this screen to configure basic ACL permissions.

POSIX ACL Owner Settings

The Owner section controls which TrueNAS user and group has full control of this dataset.

Setting	Description
User	Enter or select a user to control the dataset. Users created manually or imported from a directory service appear in the menu.
Apply User	Select to confirm user changes. To prevent errors, TrueNAS only submits changes after you select this option.
Group	Enter or select the group to control the dataset. Groups created manually or imported from a directory service appear in the menu.
Apply Group	Select to confirm group changes. To prevent errors, TrueNAS only submits changes after you select this option.

POSIX ACL Access Settings

The Access section lets users define the basic Read, Write, and Execute permissions for the User, Group, and Other accounts that might access this dataset.

A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets. Removing this permission results in lost access to the path.

POSIX ACL Advanced Settings

The Advanced section lets users Apply Permissions Recursively to all directories, files, and child datasets within the current dataset.

To access advanced POSIX ACL settings, click Add ACL on the Unix Permissions Editor. The Select a preset ACL window displays with two radio buttons.

Select an ACL Preset

There are two different Select a preset ACL windows, one for the POSIX ACL and the other for the NFSv4 ACL. Selecting a preset replaces the ACL currently displayed on the Edit ACL screen and deletes any unsaved changes.

For a POSIX ACL, a window with three setting options displays before you see the Edit ACL screen. These setting options allow you to select and use a pre-configured set of permissions that match general permissions situations or to create a custom set of permissions. You can add to a pre-configured ACL preset on the Edit ACL screen.

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, POSIX_HOME, and POSIX_ADMIN. For NFSv4, the options are NFS4_OPEN, NFS4_RESTRICTED, NFS4_HOME, NFS4_DOMAIN_HOME, and NFS4_ADMIN.

TrueNAS built-in presets automatically include entries for the builtin_users and builtin_administrators groups. Systems joined to Active Directory also include domain users and domain admins entries. User-created presets are not affected.

Setting	Description
Select a preset ACL	Click to populate the Default ACL Options dropdown list with pre-configured POSIX permissions.
Create a custom ACL	Click to open the Edit ACL screen with no default permissions, users, or groups or to configure your own set of permissions. Click Continue to display the Edit ACL screen.

The Edit ACL screen options are based on ACL type (POSIX or NFSv4). The Dataset Preset and ACL Type settings determine the ACL type. They are under Advanced Options in the Add Dataset and Edit Dataset screens

The section below describes the differences between screens for each ACL type.

ACL Editor Settings - POSIX and NFSv4

Select any user account or group manually entered or imported from a directory service in the Owner or Owner Group. The value entered or selected in each field displays in the Access Control List below these fields.

Dataset displays the dataset path (name) you selected to edit.

Access Control List - POSIX and NFS4

The Access Control List section displays the items and a permissions summary for the owner@, group@, and everyone@ for both POSIX and NSFv4 ACL types. The list of items changes based on a selected pre-configured set of permissions.

To add a new item to the ACL, click Add Item, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.

Edit ACL Functions - POSIX and NFS4

These functions display on the Edit ACL screen for both POSIX and NSFv4 ACL types except for Strip ACL, which only displays for NSFv4 types.

Edit ACL Settings

Setting	Description
Add Item	Adds a new ACE to the Access Control List.
Apply permissions recursively	Select to apply all settings or changes on the Edit ACL screen to all child datasets in the path in Dataset.
Save Access Control List	Saves settings or changes made on the Edit ACL screen.
Strip ACL	(NSFv4 only) Remove all ACLs from the current dataset and any directories or files contained within this dataset. Stripping the ACL resets dataset permissions and can make data inaccessible until you create new permissions.
Permissions Editor	(POSIX only) Displays the Unix Permissions Editor screen for POSIX ACL types.
Use Preset	Displays the Select a preset ACL window. If the ACL Type setting, found in the Advanced Options of both the Add Dataset and Edit Dataset screens, is POSIX or Inherit, the Default ACL Options dropdown displays POSIX pre-configured options. If set to NFSv4, the preset options displayed are pre-configured NSFv4 options.
Save As Preset	Saves the current access control list as a custom preset and adds it to the Access Control List.

POSIX Access Control Entry Settings

The POSIX Access Control Entry settings include Who, Permissions, and Flags options.

POSIX ACE Settings

Setting	Description
Who	Select the user or group from the dropdown list the permissions apply to. User denotes access rights for users identified by the entry qualifier. Group denotes access rights for the filegroup. Other denotes access rights for processes that do not match any other entry in the ACL. Group Obj denotes access rights for the filegroup. User Obj denotes access rights for the file owner. Mask denotes the maximum access rights User, Group Obj, or Group type entries can grant.
Permissions	Select the checkbox for each permission type (Read, Write and Execute) to apply to the user or group in Who.
Flags	Select the Default option to include a flag setting for the user or group in Who.

NFS4 Access Control Entry Settings

There are two Access Control Entry settings, Who and ACL Type.

The NFSv4 ACL Type radio buttons change the Permissions and Flags setting options. Select Allow to grant the specified permissions or Deny to restrict the permissions for the user or group in Who.

NFS ACE Settings

Setting

Description

Who

Access Control Entry (ACE) user or group. Select a specific User or Group for this entry. See nfs4_setfacl(1) NFSv4 ACL ENTRIES.

User denotes access rights for users identified by the qualifier.
Group denotes access rights for groups identified by the qualifier.
owner@ applies this entry to the user that owns the dataset.
group@ applies this entry to the group that owns the dataset.
everyone@ applies this entry to all users and groups.

ACL Type

Determines how the Permissions apply to the chosen Who. Choose Allow to grant the specified permissions and Deny to restrict the specified permissions.

NFS4 Permissions and Flags

TrueNAS divides permissions and inheritance flags into basic and advanced options. The basic permissions options are commonly-used groups of advanced options. Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.

Basic Permissions Settings

Click the Basic radio button to display the Permissions dropdown list of options that applies to the user or group in Who.

Figure 8: NSFv4 Basic Permissions Options

NFSv4 Basic Permissions Settings

Permission	CLI Command	Description
Read	`r-x---a-R-c---`	View file or directory contents, attributes, named attributes, and ACL.
Modify	`rwxpDdaARWc--s`	Adjust file or directory contents, attributes, and named attributes. Create new files or subdirectories. Includes the Traverse permission.
Traverse	`--x---a-R-c---`	Execute a file or move through a directory.
Full Control	`rwxpDdaARWcCos`	Apply all permissions.

Advanced Permissions Settings

Click the Advanced radio button to display the Permissions options for the user or group in Who.

Figure 9: NSFv4 Advanced Permissions Options

NFSv4 Advanced Permisions Settings

Permission	CLI Command	Description
Read Data	`r`	View file contents or list directory contents.
Write Data	`w`	Create new files or modify any part of a file.
Append Data	`p`	Add new data to the end of a file.
Read Named Attributes	`R`	View the named attributes directory.
Write Named Attributes	`W`	Create a named attribute directory. Must be paired with the Read Named Attributes permission.
Execute	`x`	Execute a file, move through, or search a directory.
Delete Children	`D`	Delete files or subdirectories from inside a directory.
Read Attributes	`a`	View file or directory non-ACL attributes.
Write Attributes	`A`	Change file or directory non-ACL attributes.
Delete	`d`	Remove the file or directory.
Read ACL	`c`	View the ACL.
Write ACL	`C`	Change the ACL and the ACL mode.
Write Owner	`o`	Change the user and group owners of the file or directory.
Synchronize	`s`	Synchronous file read/write with the server. This permission does not apply to FreeBSD clients.

NFSv4 Basic Flags

Click the Basic radio button to display the flag settings that enable or disable ACE inheritance.

NFSv4 Basic Flag Settings

Flag	CLI Command	Description
Inherit	`fd-----`	Enable ACE inheritance.
No Inherit	`-------`	Disable ACE inheritance.

NFSv4 Advanced Flags

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.

NFSv4 Advanced Flag Settings

Flag	CLI Command	Description
File Inherit	`f`	The ACE is inherited with subdirectories and files. It applies to new files.
Directory Inherit	`d`	New subdirectories inherit the full ACE.
No Propagate Inherit	`n`	The ACE can only be inherited once.
Inherit Only	`i`	Remove the ACE from permission checks but allow new files or subdirectories to inherit it. Inherit Only is removed from these new objects.
Inherited	`I`	Set when this dataset inherits the ACE from another dataset.

Quotas

TrueNAS quota settings limit how much storage space a dataset, user, or group can consume.

Managing User or Group Quotas: Provides information on managing user and group quotas.

Capacity Settings Screen: Provides information on the quota settings and functions found on the Capacity Settings screen.

User and Group Quota Screens: Provides information on the settings and functions found on the User and Group Quota screens.

Managing User or Group Quotas

TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system. You can use the quota settings on the Add Dataset or Edit Dataset configuration screens in the Advanced Options settings to set up alarms and set aside more space in a dataset. See Adding and Managing Datasets for more information.

To manage the dataset overall capacity, use Edit on the Dataset Space Management widget to open the Capacity Settings screen.

Configuring User Quotas

To view and edit user quotas, go to Datasets and click Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.

Click Add to open the Add User Quota screen.

Click in the field to view a list of system users including any users from a directory server that is properly connected to TrueNAS. Begin typing a user name to filter all users on the system to find the desired user, then click on the user to add the name. Add additional users by repeating the same process. A warning dialog displays if there are no matches found.

To edit individual user quotas, click anywhere on a user row to open the Edit User Quota screen where you can edit the User Data Quota and User Object Quota values.

User Data Quota is the amount of disk space that selected users can use. User Object Quota is the number of objects selected users can own.

Configuring Group Quotas

Click Add to open the Add Group Quota screen.

Click in the Group field to view a list of system groups on the system. Begin typing a name to filter all groups on the system to find the desired group, then click on the group to add the name. Add additional groups by repeating the same process. A warning dialog displays if there are no matches found.

To edit individual group quotas, click anywhere on a group name to open the Edit Group Quota screen where you can edit the Group Data Quota and Group Object Quota values.

Group Data Quota is the amount of disk space that the selected group can use. Group Object Quota is the number of objects the selected group can own.

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.

CapacitySettingsScreen

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.

User Quotas Screen

Select Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen. The User Quotas screen displays names and quota data of user accounts cached on or connected to the system. If no users exist, the screen displays No User Quotas in the center of the screen.

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.

Edit User Configuration 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.

Set User Quotas Screen

To display the Set User Quotas screen click the Add button.

Set Quotas Settings

Settings	Description
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.

Apply Quotas to Selected Users Settings

Settings	Description
Apply To Users	Select the users from the dropdown list of options.

Click Save to set the quotas or click the “X” to exit without saving.

Group Quotas Screens

Click Manage Group Quotas on the Dataset Space Management widget to open the Group Quotas screen.

The Group Quotas screen displays the names and quota data of any groups cached on or connected to the system. If no groups exist, the screen displays No Group Quotas in the center of the screen.

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.

Edit Group Configuration 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.

Edit Group Configuration Settings

Settings	Description
Group	Displays the name of the selected group(s).
Group Data Quota (Examples: 500KiB, 500M, 2 TB)	Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota	Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.

Set Group Quotas Screen

To display the Set Group Quotas screen, click the Add button.

Set Quotas Settings

Settings	Description
Group Data Quota (Examples: 500KiB, 500M, 2 TB)	Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota	Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.

Apply Quotas to Selected Groups Settings

Settings	Description
Apply To Groups	Select groups from the dropdown list of options.

Snapshots

TrueNAS snapshots capture the state of a dataset or zvol at a point in time, enabling data recovery without full backups.

Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.

Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.

Snapshots Screens: Provides information on the settings and functions found on the Snapshots screen.

Creating Snapshots

Snapshots are one of the most powerful features of ZFS. A snapshot provides a read only point-in-time copy of a file system or volume. This copy does not consume extra space in the ZFS pool. The snapshot only records the differences between storage block references whenever the data is modified.

Why do I want to keep snapshots?

Snapshots keep a history of files and provide a way to recover an older or even deleted files. For this reason, many administrators take regular snapshots, store them for some time, and copy them to a different system. This strategy allows an administrator to roll the system data back to a specific point in time. In the event of catastrophic system or disk failure, off-site snapshots can restore data up to the most recent snapshot.

Taking snapshots requires the system have all pools, datasets, and zvols already configured.

Creating a Snapshot

Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.

There are two ways to access snapshot creation:

From the Data Protection Screen

To access the Snapshots screen, go to Data Protection > Periodic Snapshot Tasks and click the Snapshots button in the lower left corner of the widget.

Existing snapshots display as a list.

From the Datasets Screen

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.

StorageSnapshotsListedContentSCALE

Click Add at the top right of the screen to open the Add Snapshot screen.
Figure 4: Add a New Snapshot
Select a dataset or zvol from the Dataset dropdown list.
Accept the name suggested by the TrueNAS software in the Name field or enter any custom string to override the suggested name.
(Optional) Select an option from the Naming Schema dropdown list that the TrueNAS software populated with existing periodic snapshot task schemas. If you select an option, TrueNAS generates a name for the snapshot using that naming schema from the selected periodic snapshot and replicates that snapshot.
You cannot enter a value in both Naming Schema and in Name as selecting or entering a value in Naming Schema populates the other field.
(Optional) Select Recursive to include child datasets with the snapshot.
Click Save to create the snapshot.

Managing Snapshots

Viewing the List of Snapshots

File Explorer limits the number of snapshots Windows presents to users. If TrueNAS responds with more than the File Explorer limit, File Explorer shows no available snapshots. TrueNAS displays a dialog stating the dataset snapshot count has more snapshots than recommended and states performance or functionality might degrade.

There are two ways to view the list of snapshots:

Go to Datasets > Data Protection widget > Manage Snapshots link to open the Snapshots screen.

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 expand_more to view snapshot options.

Cloning to New Dataset

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.

Promoting a Dataset

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.

Figure 10: Demoted Dataset with Promote Button

See zfs-promote.8 for more information.

Deleting a Snapshot

The Delete option destroys the snapshot. You must delete child clones before you can delete their parent snapshot. While creating a snapshot is instantaneous, deleting one is I/O intensive and can take a long time, especially when deduplication is enabled.

Why?

ZFS has to review all allocated blocks before deletion to see if another process is using that block. If not used, the ZFS can free that block.

Click the Delete button. A confirmation dialog displays. Select Confirm to activate the Delete button.

Deleting with Batch Operations

To delete multiple snapshots, select the left column box for each snapshot to include. Click the Delete button that displays.

To search through the snapshots list by name, type a matching criteria into the 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.

Using Rollback to Revert a Dataset

The Rollback option reverts the dataset to the point in time saved by the snapshot.

Rollback is a dangerous operation that causes any configured replication tasks to fail. Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out of order.
A less disruptive method to restore data from a point in time is to clone a specific snapshot as a new dataset:
Clone the desired snapshot.
Share the clone with the share type or service running on the TrueNAS system.
Allow users to recover their needed data.
Delete the clone from Datasets.
This approach does not destroy any on-disk data or disrupt automated replication tasks.

TrueNAS asks for confirmation before rolling back to the chosen snapshot state. Select the radio button for how you want the rollback to operate.

Click Confirm to activate the Rollback button.

Browsing a Snapshot Collection

All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden .zfs located at the root of every dataset.

A snapshot and any files it contains are not accessible or searchable if the snapshot mount path is longer than 88 characters. The data within the snapshot is safe but to make the snapshot accessible again shorten the mount path.

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 .zfs directory and navigate to the snapshot.

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.

My Snapshot screen is blank

If the Snapshots screen does not display a list of snapshots and you know you added snapshots, clear the dataset path in the search field to show all dataset and zvol snapshots on the system.

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.

Snapshot Details Screen

Click anywhere on a snapshot to expand it and view more information about the snapshot and the options for that snapshot.

Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.

Option	Description
Delete	Opens a Delete confirmation dialog for the selected snapshot(s). Select Confirm to activate the Delete button.
Clone to New Dataset	Opens the Clone to New Dataset) window where you enter a new name or clone with the default value in the Dataset Name field.
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.

Rollback from Snapshot Window

The snapshot Rollback option replaces the data in the selected dataset with the information saved in the snapshot.

WARNING: Rolling the dataset back destroys data on the dataset and can destroy additional snapshots that are related to the dataset. This can result in permanent data loss! Do not roll back until all desired data and snapshots are backed up.

There are three Stop Rollback if Snapshot Exists radio button options that impose safety levels on the rollback operation. When the safety check finds additional snapshots directly related to the dataset you are rolling back it cancels the rollback.

Rollback Options

Setting	Description
Newer Intermediate, Child, and Clone	Select to stop rollback when the safety check finds any related intermediate, child dataset, or clone snapshots that are newer than the rollback snapshots.
Newer Clone	Select to stop rollback when the safety check finds any related clone snapshots newer than the rollback snapshot.
No Safety Check (CAUTION)	Select to stop rollback if snapshot exists. The rollback destroys any related intermediate, child dataset, and cloned snapshots newer than the rollback snapshot.
Confirm	Select to confirm the selection and activate the Rollback button.

Clone Snapshot and Promote Dataset

Cloning to New Dataset

Click Clone to confirm.

The Go to Datasets button opens the Datasets screen.

Promoting a Dataset

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.

Delete Snapshot

The snapshot Delete option opens a window that lists the snapshot(s) you select.

Confirm activates the Delete button.

Batch Operations - Delete

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.

Add Snapshot Screen

The Add Snapshots screen allows you to create a snapshot while on the Snapshots screen. It also opens when you click Create Snapshot on the Dataset Protection widget on the Datasets screen.

Save retains the settings and returns to the Snapshots screen.

Add Snapshot Settings

Setting	Description
Dataset	Select the dataset or zvol from the dropdown list. The snapshot created is from this dataset or zvol.
Name	TrueNAS populates this with a name but you can override the name with any string of your choice. You cannot use Name and Naming Schema for the same snapshot.
Naming Schema	Select an option from the dropdown list or leave this blank to use the system-populated name in the Name field. This generates a name for the snapshot using the naming schema from a previously-entered periodic snapshot. This allows replication of the snapshot. You cannot use Naming Schema with Name. Selecting a schema option overwrites the value in Name.
Recursive	Select to include child datasets or zvols in the snapshot.

Zvols

Zvols are block-level datasets used as virtual disks for virtual machines and iSCSI shares.

Adding and Managing Zvols: Provides instructions on creating, editing, and managing zvols.

Zvols Screen: Provides information on the settings and functions found on the Zvol screens and widgets.

Adding and Managing Zvols

A ZFS Volume (zvol) is a dataset that represents a block device or virtual disk drive. TrueNAS requires a zvol when configuring iSCSI Shares. Adding a virtual machine also creates a zvol to use for storage.

Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused. Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume. Do not assign capacity that exceeds what is required for TrueNAS to operate properly. For more information, see TrueNAS Hardware Guide for CPU, memory and storage capacity information.

Adding a Zvol

To create a zvol, go to Datasets. Select the root or non-root parent dataset where you want to add the zvol, and then click Add Zvol.

Figure 1: Dataset Tree Table and Zvol Widgets

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.

Adding a Zvol for a Fusion Pool

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.

Click Save.

Managing Zvols

Options to manage a zvol are on the zvol widgets shown on the Dataset screen when you select the zvol on the dataset tree table.

Delete Zvol removes the zvol from TrueNAS. Deleting a zvol also deletes all snapshots of that zvol. Click Delete on the Zvol Details widget.

Deleting zvols can result in unrecoverable data loss! Remove critical data from the zvol or verify it is obsolete before deleting a zvol.

Edit on the Zvol Details widget opens the Edit Zvol screen where you can change settings. Name is read-only and you cannot change it.

To create a snapshot, click Take Snapshot on the Data Protection widget.

Cloning a Zvol from a Snapshot

To clone a zvol from an existing snapshot, select the zvol on the datasets tree table, then click View Snapshots on the Data Protection widget to open the Snapshots screen. You can also access the Snapshots screen from the Periodic Snapshot Tasks screen. Click on the Periodic Snapshot Task widget header on the Data Protection screen to open the Period Snapshot Tasks screen. Click Snapshots to open the Snapshots screen.

Click on the snapshot you want to clone, then click Clone to New Dataset. Enter a name for the new dataset or accept the one provided, then click Clone.

The cloned zvol shows on the Datasets screen.

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.

Zvol Widgets

Each zvol has a set of Details for zvolname information cards (widgets) that provide information grouped by functional areas. Zvol widgets are:

Zvol Details
Zvol Space Management
Data Protection
Encryption

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.

Delete Zvol

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.

Add and Edit Zvol Screens

The Add Zvol and Edit Zvol screens allow admin users with the right permission level to create and modify zvols. Both screens include the same settings, but you cannot change the zvol name, Block Size, or select the Sparse option after you click Save on the Add Zvol screen. After adding a zvol, click Edit on the Zvol Details widget to open the Edit Zvol screen.

When the zvol is encrypted, Edit on the Encryption widget opens a configuration screen where you can change the passphrase for a zvol encrypted with the passphrase type, but you cannot change to a key encryption type. If the zvol is not encrypted, you do not see encryption options on the Edit Zvol screen.

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: Inherit gets the sync settings from the parent dataset. Standard uses the sync settings requested by the client software. Always waits for data writes to complete. Disabled never waits for writes to complete.
Compression level	Select the option from the dropdown list for the type of data compression to use for encoding information in less space than the original data occupies. Select the algorithm that balances disk performance with the amount of space saved. See below for the options.
ZFS Deduplication	Do not change this setting unless instructed to by your TrueNAS support engineer. Transparently reuses a single copy of duplicated data to save space. Deduplication can improve storage capacity, but it is RAM-intensive. Compressing data is generally recommended before using deduplication. Deduplicating data is a one-way process. Deduplicated data cannot be undeduplicated!.
Read-only	Select the option to prevent modifying the zvol. Options are Inherit (off), On or Off.
Block size	Select the size option from the dropdown list. The default is 16KiBt, other options are 4KiB, 8KiB, 16KiB, 32KiB, 64KiB, 128KiB. The zvol default block size is automatically chosen based on the number of disks in the pool for a general use case.
Snapdev	Select the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible from the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Use Metadata (Special) VDEVs	Enables storing data blocks in a special allocation class (fusion pool) metadata VDEV. Options: Inherit - Uses the parent dataset setting. Displays the inherited value in human-readable form, for example, Inherit (128 KiB) or Inherit (off). On - Enables the special allocation class for this zvol. Shows the Threshold field where you enter the maximum block size to store in the special class. Valid values are 1 byte to 16 MiB. 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. Off - Disables storing blocks in the special allocation class. Before enabling this setting, you must add a metadata special class VDEV to the pool.
Inherit (non-encrypted/encrypted)	Encryption settings are inherited from the parent dataset. When the parent is encrypted, this option defaults to Inherit (encrypted); otherwise, it shows (non-encrypted). Clearing the checkmark shows the Encryption options. If the parent is encrypted with the passphrase type, the zvol can only use passphrase encryption. When the parent is encrypted with a key, the zvol can use either key or passphrase encryption. Refer to the Encryption Settings article for more details.

Block Size Table

TrueNAS recommends a space-efficient block size for new zvols. This table shows the minimum recommended volume block size values by configuration (mirror or RAIDz type). Use this table to change the Block size value.

Configuration	Number of Drives	Optimal Block Size
Mirror	N/A	16k
Raidz-1	3	16k
Raidz-1	4/5	32k
Raidz-1	6/7/8/9	64k
Raidz-1	10+	128k
Raidz-2	4	16k
Raidz-2	5/6	32k
Raidz-2	7/8/9/10	64k
Raidz-2	11+	128k
Raidz-3	5	16k
Raidz-3	6/7	32k
Raidz-3	8/9/10/11	64k
Raidz-3	12+	128k

Depending on their workload, zvols can require additional tuning for optimal performance. See the OpenZFS handbook workload tuning chapter for more information.

Data Compression Algorithms

The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.

ZSTD offers highly configurable compression speeds, with a very fast decoder.

ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.

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.

Datasets Screen

The Datasets screen shows No Datasets and a Create Pool button until you add a pool and the first root dataset.

After creating a dataset, the screen shows the dataset tree table on the left and the Details for 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.

Dataset Tree Table

The datasets tree table shows an expandable hierarchical structure, starting with the root dataset, then each non-parent or parent and child datasets, with the child datasets nested under each parent dataset.

The top row of the tree table is selected by default when you go to the Datasets screen. The 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.

Dataset Cards

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:

Details
Dataset Space Management
Data Protection
Permissions
Usage
ZFS Encryption

Details Card

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.

Delete Window

The Delete window shows information about the dataset, including the path, services that depend on the dataset, and shares using the dataset and the path to the dataset.

If a service does not use a dataset, the Delete window does not show a service.

The window includes a field where you enter the path to the dataset. Confirm activate the Delete Dataset button. Delete Dataset deletes the dataset and all data it contains.

Space Management Card

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.

Data Protection Card

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.

Permissions Card

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.

Figure 8: Permissions Card for Root Dataset

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.

Figure 10: Permissions Card NFSv4 Selectable Options

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.

Usage Card

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.

Encryption Card

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.

Figure 14: Encryption Card Inherit from Parent

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.

Add and Edit Dataset Screens

The Add Dataset and Edit Dataset screens allow admin users with full control access to create and manage datasets. Both screens include the same Advanced Options settings but you cannot change the dataset name, Dataset Preset selection, or the Case Sensitivity settings on the Advanced Options screen after clicking Save on the Add Dataset screen.

Edit on the Dataset Details 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

Basic Options

The Basic Options show on the Advanced Options screen.

Basic Option Settings

{id=“dataset_add_basic”}

Setting	Description
Parent Path	A read-only field populated with the full dataset path, from the pool root dataset down to the dataset. Adds the name of the dataset after it is entered in Name. For example, tank/shares/smbshare1. The dataset name and parent path name are combined and limited to a 200-byte maximum length. The maximum nested directory level names in a path are limited to 50. You cannot create a dataset at the 51st level in the directory hierarchy after you account for the nested levels in the parent path.
Name	Text entry field that accepts manual or copy/paste entry of a unique identifier for the dataset. Names can consist of upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters. Names cannot have trailing spaces after the dataset name. The dataset name and parent path name are combined and limited to a 200-byte maximum length. The maximum nested directory level names in a path are limited to 50. You cannot create a dataset at the 51st level in the directory hierarchy after you account for the nested levels in the parent path. You cannot change the dataset name after clicking Save. The Name field on the Edit Dataset screen shows the path but is not editable.
Dataset Preset	Presets configure dataset settings and permissions based on the type of data sharing the dataset uses, for example, SMB/NFS shares, apps, or generic storage. The options optimize the dataset for a sharing protocol or app, and set the ACL type (NFSv4 or POSIX) best suited to the dataset purpose. Options are: Generic - Use for general storage datasets that are not associated with SMB, NFS, or multi-protocol shares, or apps. Created with a POSIX ACL. SMB - Optimizes the dataset for SMB shares. Preselects the Create SMB Share option and populates the SMB Name field with the value entered in Name. Created with an NFSv4 ACL. Apps - Optimize for use by any application. Created with an NFSv4 ACL. If planning to deploy container applications, the system automatically creates the ix-apps dataset for Docker storage for application data. For data storage for individual apps, create separate datasets. Multiprotocol - Optimized for multi-protocol or mixed-mode NFS and SMB sharing protocols, or to create only an NFS share. Allows clients to use either protocol to access the same data. The Create NFS Share and Create SMB Share options are pre-selected, and the SMB Name field populates with the value entered in Name. See Multiprotcol Shares for more information. Created with an NFSv4 ACL. This setting cannot be edited after saving the dataset.

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.

Advanced Options

The Add Dataset and Edit Dataset screens show the Advanced Options button. Advanced Options show:

Quota Management settings
Encryption settings
Other Options settings

Quota Management 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.

Add Dataset Quota Options — Figure 16: Add Dataset Advanced Quota Options

Quota Settings

{id=“dataset_add_quota-mgmt”}

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.

Encryption Options Section

Encryption settings apply key or passphrase type encryption to the selected dataset, and encrypt any child datasets of an encrypted parent. Encryption settings show on in the Advanced Options screen for the Add Dataset screen, but not on the Edit Dataset screen. Edit on the Encryption 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.

Figure 19: Add Dataset Encryption Options - Passphrase

Encryption Settings

{id=“dataset_add_encryption”}

Setting	Description
*Inherit (non-encrypted)*	Selected by default. When selected, it inherits the encryption setting of the parent dataset (encrypted/non-encrypted). Clearing the checkmark shows the Encryption option.
Encryption	When selected, shows other encryption settings. The default encryption type is key. Clearing the Encryption checkmark hides the encryption settings.

{id="add_encryption-options"}

Setting	Description
Encryption Type	Shows two encryption type options: Key - Shows key-based encryption settings. Shows a system-generated key field, an option to use a manual entry key, and key-based encryption algorithms. Passphrase - Shows text fields for manual or copy/paste entry of a passphrase, and passphrase authentication algorithms.
Generate key	Shows when Encryption Type is set to Key. Selected by default and sets TrueNAS to generate a random encryption key for securing the dataset. Clearing the checkbox shows the Key field that accepts manual or copy/paste entry of an encryption key. Warning! The encryption key is the only means to decrypt the information stored in a key-encrypted dataset. Store encryption keys in a secure location! Creating a new key file invalidates a previously downloaded key file (for this dataset). Delete any previous key file backups and back up the new key file.
Key	Text entry field that accepts manual or copy/paste entry of an encryption key string to secure the dataset.
Algorithm	Shows a dropdown list of mathematical instruction algorithms that determine how plaintext converts into ciphertext for key and passphrase encryption types. See Advanced Encryption Standard (AES) for more details on each option.
Passphrase Confirm Passphrase	Text entry fields that accept manual or copy/paste entry of an alphanumeric string or phrase to secure the dataset.
pbkdf2iters	Sets the number of password-based key deviation function 2 (PBKDF2) iterations used for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.

Other Options Section

The Other Options section tunes the dataset for specific data-sharing protocols, sets compression level, sync type options, ACL type and mode, and other settings.

Figure 20: Dataset Advanced Other Options

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: Standard - Uses the sync settings requested by the client software. Always - Waits for data writes to complete. Disabled - Never waits for writes to complete.
Compression level	Applies the compression algorithm to the option selected on the dropdown list. Options encode information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance against the amount of space saved. Options include: LZ4 - Generally recommended as it maximizes performance and dynamically identifies the best files to compress. ZSTD - Uses the Zstandard compression algorithm. Has several options for balancing speed and compression. Gzip - Has options that range from 1 for least compression with best performance or 9 for maximum compression with greatest performance impact. ZLE - Has a fast algorithm that only eliminates runs of zeroes. LZJB - A legacy algorithm that is not recommended for use.
Enable Atime	Sets the access time for files to the selected option on the dropdown list. Access time can result in significant performance gains. Inherit uses the access time setting of the parent or the root dataset. On updates the access time for files when they are read. Off disables creating log traffic when reading files to maximize performance.
ZFS Deduplication	Sets the option to transparently reuse a single copy of duplicated data to save space to the option selected on the dropdown list. Options: Inherit - Uses the parent or root dataset settings. On - Uses deduplication. Off - Does not use deduplication. Verify - Use to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical. Deduplication can improve storage capacity but is RAM-intensive. Compressing data is recommended before using deduplication. Deduplicating data is a one-way process. You cannot undo deduplicated data!
Case Sensitivity	Sets case sensitivity to the option selected on the dropdown list. Options are: Sensitive - Assumes file names are case sensitive. Insensitive - Assumes file names are not case sensitive. You cannot change case sensitivity after saving the dataset. Note: The Mixed option no longer exists.
Checksum	Sets the checksum to the option selected on the dropdown list. Options: Inherit - Uses the parent setting. On - Uses the checksum without specifying the variant. FLETCHER2 (deprecated) or FLETCHER4 - Uses a position-dependent checksum that uses two checksums to determine single-bit errors in messages transmitted over network channels or ZFS streams. SHA256 (default for deduped datasets) or SHA512 - Uses a sequence of numbers and letters to check the copy of a downloaded update file is identical to the original. SKEIN - Not supported for a file system on boot pools. EDNOR - Not supported for file systems on boot pools, and Edon-R requires verification when used with dedup, so it automatically uses `verify`.

Figure 21: Add Dataset Advanced Other Options

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 .zfs directory on the dataset from the option selected in the dropdown list. Select Visible, Invisible, or Disabled.
Snapdev	Sets the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible to the options selected on the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Copies	Sets the number of ZFS user data duplicates stored on this dataset to the option selected on the dropdown list. Select between 1, 2, or 3 redundant data copies. This can improve data protection and retention, but is not a substitute for storage pools with disk redundancy.
Record Size	Sets the logical block size in the dataset to the option selected on the dropdown list. Matching the fixed size of data, as in a database, can result in better performance.
ACL Type	Sets the access control list type to the option selected on the dropdown list. Options: Inherit - Preserves ACL type from the parent dataset. Off - Uses neither NFSv4 nor POSIX protocols. NFSv4 - Cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with TrueNAS, FreeBSD, or other non-Linux ZFS implementations. POSIX - Use when a data backup target does not support native NFSv4 ACLs. Since the Linux platform has used POSIX for a long time, many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSv4 ACLs. All datasets within an SMB share path must have identical ACL types. For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer. This advanced setting changes ACL type and mode settings configured by the Dataset Preset option. Do not make changes here if you do not understand ACLs.
ACL Mode	Determines how chmod behaves when adjusting file ACLs to the option selected on the dropdown list. See the zfs(8) `aclmode` property for more information. Options: Passthrough - Only updates ACL entries related to the file or directory mode. Restricted - Does not allow chmod to make changes to files or directories with a non-trivial ACL. An ACL is trivial if it can be fully expressed as a file mode without losing access rules. Set ACL Mode to restricted to optimize a dataset for SMB sharing, but it can also require further optimizations. For example, configuring an rsync task with this dataset could require adding `--no-perms` in the task Auxiliary Parameters field.
Use Metadata (Special) VDEVs	Enables storing data blocks in a special allocation class (fusion pool) metadata VDEV. Options: Inherit - Uses the parent dataset setting. Displays the inherited value in human-readable form, for example, Inherit (128 KiB) or Inherit (off). On - Enables the special allocation class for this dataset. Shows the Threshold field where you enter the maximum block size to store in the special class. Valid values are 1 byte to 16 MiB. 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. Off - Disables storing blocks in the special allocation class. Before enabling this setting, you must add a metadata special class VDEV to the pool.

Data Compression Algorithms

The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.

ZSTD offers highly configurable compression speeds, with a very fast decoder.

ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.

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.

TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

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): Configuration tutorials and UI reference for Windows SMB shares in TrueNAS.

Adding and Managing SMB Shares: Provides instructions on creating and managing SMB shares, configuring advanced options, and managing ACL permissions.
Adding a Basic Time Machine SMB Share: Provides instructions for adding an SMB share and enabling basic Time Machine.
Setting Up Final Cut Pro SMB Shares: Provides instructions for adding an SMB share optimized for Final Cut Pro workflows.
Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.
Setting Up SMB Private Dataset Shares: Provides instructions on using SMB Private Datasets Share as an alternative to legacy SMB Home Shares.
Using SMB Shares with macOS Decomposed Unicode: Provides information on SMB share macOS client limitations when using decomposed unicode characters.
Setting Up SMB Multichannel: Provides information on setting up SMB multichannel.
SMB Shares Screens: Provides information on SMB share screens and settings.

NFS Shares: Configuration tutorials and UI reference for Unix (NFS) shares in TrueNAS.

Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.
NFS Shares Screens: Provides information on NFS Shares screens and settings.

Multiprotocol Shares: Provides instructions on setting up SMB and NFSv4 mixed-mode shares.

Block Shares (iSCSI): Describes the iSCSI protocol and has tutorials for various configuration scenarios.

Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.
Setting Up Fibre Channel: Provides instructions on setting up Fibre Channel on TrueNAS.
Using an iSCSI Share: Provides information on setting up a Linux or Windows system to use a TrueNAS-configured iSCSI block share.
Increasing iSCSI Available Storage: Provides information on increasing available storage in zvols and file LUNs for iSCSI block shares.
Block (iSCSI) Share Target Screens: Provides information on Block (iSCSI) Share Targets screens and settings.
Fibre Channel Screens: Provides information on iSCSI Fibre Channel screens and settings.

NVMe-oF Subsystems: Information on NVMe-oF subsystems and instructions to create a subsystem and configure enterprise-level subsystem settings.

Configuring NVMe-oF: Information on NVMe-oF subsystems and instructions to create a subsystem and configure enterprise-level subsystem settings.
Managing NVMe-oF Subsystems: Provides information on managing NVMe-oF subsystems, namespaces, hosts, and ports.
NVMe-oF Share Screens: Provides information on NVMe-oF share screens and settings.

WebShare: Tutorials to configure WebShare, a web-based file sharing feature in TrueNAS.

Configuring WebShare: Tutorials to configure WebShare, a web-based file sharing feature in TrueNAS.
WebShare Shares Screens: Provides information on WebShare share screens and settings.

Migrating AFP Shares: Provides information on migrating AFP shares from FreeBSD- to Linux-based TrueNAS versions.

Shares Screens: Describes the TrueNAS Sharing screen and options for accessing SMB, NFS, iSCSI, and NVMe-oF shares.

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: Provides instructions on creating and managing SMB shares, configuring advanced options, and managing ACL permissions.

Adding a Basic Time Machine SMB Share: Provides instructions for adding an SMB share and enabling basic Time Machine.

Setting Up Final Cut Pro SMB Shares: Provides instructions for adding an SMB share optimized for Final Cut Pro workflows.

Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.

Setting Up SMB Private Dataset Shares: Provides instructions on using SMB Private Datasets Share as an alternative to legacy SMB Home Shares.

Using SMB Shares with macOS Decomposed Unicode: Provides information on SMB share macOS client limitations when using decomposed unicode characters.

Setting Up SMB Multichannel: Provides information on setting up SMB multichannel.

SMB Shares Screens: Provides information on SMB share screens and settings.

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 Active Directory to provide additional user accounts. If setting up an external SMB share, we recommend using Active Directory, or at a minimum, synchronizing the user accounts between systems.
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.
Modify the share permissions.
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.

Why not just allow anonymous access to the share?

Anonymous or guest access to the share is possible, but allowing guest access can create a security vulnerability, so it is not recommended for Enterprise customers or systems with more than one SMB share administrator account. Using a guest account increases the likelihood of unauthorized users gaining access to your data in the SMB share. Major SMB client vendors are deprecating guest users, partly because signing and encryption are impossible for guest sessions.

What about LDAP users?

Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel). Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.

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.

What are ZFS dataset setting defaults?

TrueNAS creates the ZFS dataset with these settings:

ACL Mode set to Restricted The ACL Type influences the ACL Mode setting. When ACL Type is set to Inherit, you cannot change the ACL Mode setting. When ACL Type is set to NFSv4, you can change the ACL Mode to Restricted.

For datasets with NFSv4 ACL type, SMB clients automatically use access-based enumeration. This means directory listings over SMB only include files and directories for which the client has read permissions. This behavior is enabled by default and matches FreeBSD behavior.

Case Sensitivity set to Insensitive

TrueNAS also applies a default access control list to the dataset. This default ACL is restrictive and only grants access to the dataset owner and group. You can modify the ACL later according to your use case.

If you want to organize the SMB share dataset under a parent dataset (for example, under smb-shares), create that parent dataset so you can select it as the parent in step 2 below. Alternatively, you can create the parent and SMB share dataset using the Create Dataset option associated with the file browser in the Add SMB screen by making the create dataset instructions a two-=step process.

To create a basic Windows SMB share and a dataset, go to Shares, then click Add on the Windows Shares (SMB) widget to open the Add Share screen.

Enter or browse to select the SMB share mount path (parent dataset where you want to add a dataset for this share). You cannot use a root dataset for a share. When the dataset selected has an existing ACL, a warning dialog shows. Click Continue. Click on the dataset under which you want to add the SMB share dataset. The blank Path field populates with the path selected in the file browser field directly below it. The Path file browser field is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 2: File Explorer Folder Icons
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:
- Files and directories
- Share names
Select a share type on the Purpose dropdown list. The share type selected locks or unlocks the pre-determined Advanced Options settings for the share.
Select Default Share to create a basic SMB share with the Browsable to Network Clients option preselected. This determines whether this share name is included when browsing shares.
Select Private Datasets Share to create an alternative to home shares. See Setting Up SMB Home Shares for more information on replacing this legacy feature with private SMB shares and datasets.
Select Multi-protocol Share to create a multi-protocol share (NFSv4/SMB). Set this if the path is shared through NFS, FTP, or used by containers or apps. Note: This setting can reduce SMB share performance as it turns off some SMB features for safer interoperability with external processes. See Setting Up SMB Multichannel for more information on creating multi-protocol shares.
Select Time Machine Share to create a Time Machine share. The SMB share is presented to Mac OS clients as a Time Machine target. See Adding a Basic Time Machine SMB Share for more information on creating and using Time Machine shares.
Select Final Cut Pro Storage Share (available in TrueNAS 25.10.1 and later) to create a share optimized for Final Cut Pro workflows. The SMB share is configured with Apple-style character encoding and requires Apple SMB2/3 protocol extensions for compatibility with Final Cut Pro. See Setting Up Final Cut Pro SMB Shares for more information on creating shares for Final Cut Pro workflows.
Select External Share to create an external share. Enter the full domain name or IP address and the share name as 192.168.0.200\SHARE in Remote Path.
Select Time Locked Share to create a share that makes files read-only after the grace period you specify expires. This setting does not work if the path is accessed locally or if another SMB share with the Time Locked Share purpose uses the same path. Warning: This setting might not meet regulatory requirements for write-once storage.
(Optional) Enter a short description or explanation of the share purpose or use in Description. This shows on both the SMB widget and Share > SMB screen to help explain how the share is used. For example, if for an external share, enter external share in the field. The description entered shows in the SMB table on the SMB screen and the Windows (SMB) Share widget.
Select Enabled to allow sharing of this path when the SMB service is activated. Leave the checkbox cleared to disable the share without deleting the configuration.
(Optional) Click Advanced Options to show additional configuration settings. Click to configure other advanced settings such as access, audit logging, or settings specific to the type of share selected in Purpose.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.

Start or restart the SMB service when prompted.

Configuring Advanced Options

A basic SMB share does not need to use the Advanced Options settings. Click Advanced Options to finish customizing the SMB share settings.

See SMB Shares Screens for all settings and other possible use cases.

Guest Access

Guest access adds security vulnerabilities and should be avoided.

Guest access allows users to connect to an SMB share without providing credentials. In TrueNAS SCALE 25.10 and later, this feature is only available for shares with the Legacy Share preset (shares that used No Preset in releases before 25.10).

To enable guest access on a Legacy Share:

Go to Shares and click on the share name to expand the share widget, then click Edit.
Click Advanced Options and scroll down to the Access settings.
Select the Allow Guest Access checkbox.
Click Save.

The privileges granted are the same as those for a guest account.

Windows 10 version 1709 and later–and Windows Server 2019 and later–disable guest access by default as a security measure. Windows clients require additional configuration to connect to shares with guest access enabled.
To enable guest access on Windows clients, modify Windows registry settings or Group Policy to allow insecure guest logons. See Microsoft documentation for configuration details.

For new shares:

New shares created in TrueNAS SCALE 25.10 and later cannot select the Legacy Share preset, and therefore cannot use guest access. Guest access has been limited to legacy shares due to security concerns and client-side deprecation:

Windows 10 version 1709 and Windows Server 2019 and later disable guest access by default
Major SMB client vendors are deprecating guest users
Guest sessions cannot use signing and encryption features

Client-specific behavior:

Mac OS clients - Prevent automatic connection as guest account. Users must explicitly select Connect As: Guest. See the Apple documentation for more details.
Windows clients - Require registry or Group Policy modifications to enable insecure guest authentication

Alternative approaches:

Instead of guest access, consider these secure alternatives:

Create a dedicated guest user account with limited permissions
Use share ACL to restrict the guest user to read-only access

If the share is nested under parent datasets, see Using the Traverse Permission.

Read or Write Access

To prohibit writes to the share, select Export Read-Only.

Select Access Based Share Enumeration to restrict share visibility for users with read or write access to the share. This setting applies to datasets with a POSIX ACL type. For datasets with NFSv4 ACL type, access-based enumeration is automatically enabled and does not allow disabling. See the smb.conf manual page.

Host Allow and Host Deny

Hosts Allow and Hosts Deny settings are available for all share presets except External Share.

Use the Host Allow and Host Deny options to allow or deny specific host names and IP addresses.

Use the Hosts Allow field to enter a list of allowed IP addresses. Separate entries by pressing Enter.

Entering values in the Host Allow restricts access to only the addresses entered into this list! This list can break UI access for all other IP or host name entries.

You can find a more detailed description with examples here. Use the Hosts Deny field to enter a list of denied host names or IP addresses. Separate entries by pressing Enter.

Hosts Allow and Hosts Deny work together to produce different situations:

Leaving both Hosts Allow and Hosts Deny free of entries allows any host to access the SMB share.
Adding entries to the Hosts Allow list but not the Hosts Deny list allows only the hosts on the Hosts Allow list to access the share.
Adding entries to the Hosts Deny list but not the Hosts Allow list allows all hosts not on the Hosts Deny list to access the share.
Adding entries to both a Hosts Allow and Hosts Deny list allows all hosts on the Hosts Allow list to access the share and allows hosts not on the Hosts Allow or Hosts Deny list to access the share.

Legacy Share Preset (Upgraded Shares Only)

When you upgrade to TrueNAS SCALE 25.10 from an earlier release, existing shares that used the No Preset option are automatically migrated to the Legacy Share preset. This preset provides access to configuration options that are no longer available for new shares.

Why can’t I create a new legacy share?

The Add SMB screen does not include Legacy Share as an option. This preset only appears in the Edit SMB screen for shares created before 25.10. TrueNAS removed these options from new shares due to:

Security concerns (guest access, recycle bin)
Better alternatives available (ZFS snapshots instead of recycle bin)
Client-side deprecation (guest access no longer supported by major vendors)

Legacy share options:

Legacy shares provide access to additional settings not available in modern presets.

In the Access section:

Enable ACL - Configure additional ACL entries for custom access controls
Allow Guest Access - Enable anonymous access without credentials (not recommended)

In the Other Options section:

Use as Home Share - Configure share as user home directories (see Private Dataset Share for modern alternative)
Time Machine Quota - Set maximum limit on Time Machine backup storage
Legacy AFP Compatibility - Support for migrated AFP shares
Enable Shadow Copies - Export ZFS snapshots as volume shadow copies for VSS clients (see Shadow Copies)
Export Recycle Bin - Move deleted files to a .recycle directory (not recommended - use ZFS snapshots instead)
Use Apple-style Character Encoding - Translate NTFS illegal characters to Unicode private range
Enable Alternate Data Streams - Support multiple NTFS data streams
Enable SMB2/3 Durable Handles - Allow file handles to survive disconnections
Enable FSRVP - Remote VSS protocol support for snapshot management
Path Suffix - Append per-user/computer/IP suffixes to connection path
Additional Parameters String - Add custom smb.conf parameters (advanced users only)
VUID - Time Machine volume UUID for mDNS advertisements

See Legacy Share Settings in the UI reference for complete details on each option.

Apple Filing Protocol (AFP) Compatibility

AFP shares are deprecated and not available in TrueNAS.

To customize your SMB share to work with a migrated AFP share or with your Mac OS, use the share option on the Purpose dropdown list and the Advanced Options settings provided for these use cases:

Time Machine Share enables Apple Time Machine backups on this share.

Use Apple-style Character Encoding, listed under Other Options for all share types except Time Machine Share and External Share, converts NTFS illegal characters like the Mac OS SMB clients do. By default, Samba uses a hashing algorithm for NTFS illegal characters.

Private SMB Datasets and Shares

Used to set up an alternative to the legacy home shares function, select Private Dataset Share on the Purpose dropdown list, and customize settings listed under Other Options.

This allows you to add private datasets and shares for individual users, and is an alternate way to create home shares for them. See Setting Up SMB Home Shares for more information.

SMB Audit Logging

Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.

SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.

From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.

Selecting Enable turns auditing on for the share you are creating or editing.

At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.

Configuring Watch List

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.

Managing SMB Shares

To manage an SMB share, click more_vert dropdown list to the right of each share to see the options for the share you want to manage. Options are:

Edit opens the Edit SMB screen where you can change settings for the share.
Edit 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.

Configuring SMB Auditing

Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.

SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.

From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.

Selecting Enable turns auditing on for the share you are creating or editing.

At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.

Configuring Watch List

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.

Modifying ACL Permissions for SMB Shares

When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
Figure 5: Strip ACL Warning
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.
Figure 6: Configure ACL Dialog
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 share 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.

Configuring Dataset File System ACL

You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).

To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option. This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level. To customize permissions, add Access Control Entries (ACEs) for users or groups.

To access the dataset (filesystem) permissions, click on the more_vert dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share. You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.

Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group. Users in this group can add or modify files and directories in the share.

The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default. Change the @owner and @group values to the admin (Full admin) user and click Apply under each.

To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry. Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group. Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.

Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL

If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.

Changing the built-in-user Group Permissions

To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.

Click Edit to open the Edit ACL screen. Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Figure 8: Edit ACL Permissions
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.

Using the Traverse Permission

If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.

After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).

Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.

Starting the SMB Service

To connect to an SMB share, start the SMB service.

After adding 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 more_vert to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.

Each SMB share on the list also has a toggle to enable or disable the service for that share.

Starting the Service Using System Settings

To make SMB share available on the network, go to System > Services and click the SMB Start Service button to start the service. Toggle Start Automatically on if you want the service to activate when TrueNAS boots.

Configuring the SMB Service

Configure the SMB service by clicking Config Service from the more_vert dropdown menu on the Windows (SMB) Shares widget header or by clicking on the Services screen. Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.

Enabling SMB Stateful Failover

TrueNAS Enterprise
SMB Stateful Failover requires an Enterprise license and a High Availability (HA) configuration. When enabled, this setting is incompatible with:
Minimum Protocol set to SMB1
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.

Enabling Stateful Failover

Go to System > Services and click the 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.

Enabling Spotlight Search for macOS

TrueNAS supports macOS Spotlight search on SMB shares through the TrueSearch indexing service. After enabling Spotlight on the SMB service, macOS users can use native Finder search to quickly locate files on mounted SMB shares.

Spotlight search requires a TrueNAS Enterprise license or a configured TrueNAS Connect integration. If neither is configured, the Enable Search (Spotlight) setting is disabled and a notice displays with a link to configure TrueNAS Connect.

Enabling Spotlight Search

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 saving, TrueSearch begins indexing every active SMB share. TrueSearch excludes encrypted datasets from indexing to protect sensitive data.

TrueSearch indexes every active SMB share. You cannot enable indexing per share.

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.

Using Spotlight Search on macOS

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 does not return results from SMB shares when the search scope is set to This Mac.
Enter search terms. Spotlight supports searching by file name, file content, and file type.

TrueSearch filters out the keywords BEFORE, AND, and THE by default. Queries containing these words return results as if those words were not in the query.

Results appear as TrueSearch returns matches.

The instructions in this section cover mounting the SMB share on a system with the following operating systems.

Mounting on a Linux System

Verify that your Linux distribution has the required CIFS packages installed.

Create a mount point with the sudo mkdir /mnt/smb_share command.

Mount the volume with the sudo mount -t cifs //computer_name/share_name /mnt/smb_share command.

If your share requires user credentials, add the switch -o username= with the username after cifs and before the share address.

Mounting on a Windows System

To permanently mount the SMB share in Windows, map a drive letter in the computer for the user to the TrueNAS IP and share name. Select a drive letter from the bottom of the alphabet rather than from the top to avoid assigning a drive dedicated to some other device. The example below uses Z. Open the command line and run the following command with the appropriate drive letter, TrueNAS system name or IP address, and the share name.

net use Z: \\TrueNAS_name\share_name /PERSISTENT:YES

Where:

Z is the drive letter to map to TrueNAS and the share
TrueNAS_name is either the host name or the system IP address
share_name is the name given to the SMB share

To temporarily connect to a share, open a Windows File Explorer window, type \\TrueNAS_name\share_name and then enter the user credentials to authenticate with to connect to the share. Windows remembers the user credentials, so each time you connect, it uses the same authentication credentials unless you restart the system. After restarting, you are prompted to enter the authentication credentials again.

Mounting on an Apple System

Before you begin this process, have the username and password for the user assigned to the pool or the credentials for the guest if the share has guest access ready.

Open Finder > Go > Connect To Server Enter the SMB address as follows: smb://192.168.1.111.

Input the username and password for the user assigned to that pool or a guest user if the share has guest access.

For further tuning in Mac OS, Apple provides some enterprise-specific pointers in their Adjust SMB browsing behavior in macOS article.

Mounting on a FreeBSD System

Mounting on a FreeBSD system involves creating the mount point and mounting the volume.

Create a mount point using the sudo mkdir /mnt/smb_share command.

Mount the volume using the sudo mount_smbfs -I computer_name\share_name /mnt/smb_share command.

External SMB shares are essentially redirects to shares on other systems. Administrators might want to use this when managing multiple TrueNAS systems with SMB shares, and if they do not want to keep track of which shares are on which boxes for clients. This feature allows admins to see and connect to any TrueNAS system with external shares active.

Create the SMB share on another TrueNAS remote server (for example, system1), as described in Adding an SMB Share above.

We recommend using Active Directory when creating user accounts, but at a minimum, synchronize user accounts between the system with the share (system1) and on the TrueNAS system where you set up the external share (for example, system2).

On system2 (the local system), select External Share, enter the full domain name or IP address, and the share name. Separate the server and share name with the \ character. Example: 192.168.0.200\SHARE in Remote Path.

Click Save to add the share.

Repeat the system2 instructions above on system1 to see the SMB shares on each system.

Figure 10: Set Up Another External SMB Share

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.
Modify the SMB service settings.

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.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.

If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.

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.
Figure 2: Strip ACL Warning
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.
Figure 3: Configure ACL Dialog
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.

Modifying the SMB Service

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 to open the SMB service settings screen.

Click Advanced Settings.
Select Enable Apple SMB2/3 Protocol Extension to enable it, then click Save.
Start or restart the SMB service.

Setting Up Final Cut Pro SMB Shares

When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.

The Final Cut Pro Storage Share purpose enables Use Apple-style Character Encoding, which translates NTFS illegal characters to the Unicode private range. This ensures compatibility with Final Cut Pro.
Enabling this feature on shares with existing data might cause unexpected behavior for files that were written without Apple character encoding enabled. Test thoroughly before applying to production shares with existing content.
This share purpose requires Apple SMB2/3 Protocol Extensions to be enabled globally in the SMB service configuration.

About Final Cut Pro Storage Shares

The Final Cut Pro Storage Share purpose is available in TrueNAS 25.10.1 and later.

TrueNAS provides the Final Cut Pro Storage Share purpose for professional media production workflows. This share type automatically enables Use Apple-style Character Encoding to translate NTFS illegal characters for proper file handling in Final Cut Pro.

Apple-style character encoding ensures that special characters and metadata are preserved correctly, which is essential when working with media files that have complex naming conventions.

Many online guides recommend manually configuring SMB VFS options for macOS compatibility:
vfs objects = catia fruit streams_xattr
TrueNAS does not support manual VFS module configuration. Manually setting VFS objects via auxiliary parameters or CLI overrides TrueNAS defaults and breaks Asynchronous I/O (AIO), Access Control Lists (ACLs), and Shadow Copies.
Why does TrueNAS handle VFS modules differently?
The TrueNAS SMB implementation integrates VFS modules with several advanced features. Manual VFS configuration breaks functionality including:
Asynchronous I/O (AIO): Overrides modules needed for SMB performance optimization, causing poor performance or stability issues.
Access Control Lists (ACLs): Bypasses or breaks ACL functionality, causing incorrect permission handling.
Shadow Copies: Disables Shadow Copy functionality, preventing file restoration.
The Final Cut Pro Storage Share purpose preset automatically configures VFS modules to integrate properly with TrueNAS AIO, ACLs, and Shadow Copies. By using this preset instead of manual configuration, you get a share that works seamlessly with Final Cut Pro without risking system functionality.

Prerequisites

Before setting up a Final Cut Pro Storage Share:

Create user accounts for media users who access the share. Go to Credentials > Local Users and click Add. Ensure SMB Access is selected for each user.
Prepare a dataset for the share (or you can create one during share creation). For best performance with large media files, consider:
- Enabling compression (LZ4 is recommended for media files).
- Setting appropriate record size (128K or larger for video files).
- Configuring adequate space quotas.
Turn on Enable Apple SMB2/3 Protocol Extensions for the SMB service (instructions below).

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 Apple SMB2/3 Protocol Extensions

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 configure button.
Click Advanced Settings to expand advanced options.
Select Enable Apple SMB2/3 Protocol Extensions.
Figure 6: Enable Apple SMB2/3 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.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 7: File Explorer Folder Icons
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.
Figure 8: Add Final Cut Pro Storage Share - Basic Options
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.
Figure 9: Final Cut Pro Storage Share Extension Required
Click Enable Now to enable the required setting in the SMB service configuration. Wait for the service to update. When complete, TrueNAS displays a success message confirming Apple SMB2/3 protocol extension support is enabled.

Configure Advanced Options

While creating a basic Final Cut Pro Storage Share requires no additional configuration, you can customize access and logging settings.

Click Advanced Options to expand additional settings.
Configure Access settings as needed:
- Export Read-Only: Leave unselected to allow media file editing.
- Browsable to Network Clients: Enabled by default (recommended).
- Access Based Share Enumeration: Select to enable if needed for your access control requirements.
Figure 10: Final Cut Pro Storage Share - Advanced Options
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.

Configure Dataset Permissions

After creating the share, configure dataset permissions to grant access to media users.

On the Shares screen, locate the new share in the Windows (SMB) Shares widget.
Click and select Edit Filesystem ACL.
Configure ACL entries for users or groups who need access:
- For individual users: Add ACL entries with appropriate permissions (FULL for editors, READ for reviewers).
- For groups: Create a group like media_users and add users, then add a group ACL entry.
Click Save Access Control List.

See 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.

Connect from Mac Client

On the Mac client, connect to the share:

Open Finder.
Select Go > Connect to Server (or press Cmd+K).
Enter the SMB address: smb://your-truenas-ip/share-name.
Authenticate with a user account that has access to the share.

The share is now available for use with Final Cut Pro.

Testing and Verification

After mounting the share, verify proper operation:

File Creation: Create test files from Final Cut Pro to verify proper file handling.
Character Handling: Test filenames with special characters to confirm Apple character encoding is working correctly.
Performance: Copy large media files to verify adequate transfer speeds for your workflow.
Permissions: Test access with different user accounts to verify ACL configuration.

Migrating Existing Media Libraries

If you have an existing Final Cut Pro workflow using a standard SMB share with default settings that works properly, TrueNAS recommends keeping your current configuration. Migration is only necessary if you are experiencing specific compatibility issues or need the character encoding features provided by the Final Cut Pro Storage Share preset.

Migrating an existing media library from a standard SMB share to a Final Cut Pro Storage Share requires careful planning because enabling Apple character encoding might affect existing files:
Files created without Apple character encoding might display differently or have access issues
Existing project files might need to be re-indexed by Final Cut Pro
Test thoroughly in a non-production environment before migrating production data
Migration Steps
Only proceed with migration if you have confirmed that your current setup is incompatible with your requirements:
Create a new Final Cut Pro Storage Share and dataset in TrueNAS following the instructions in this article.
Configure dataset permissions for the new share to grant appropriate access to media users.
Copy a small subset of test files to the new share using the Mac client:
Open Finder and connect to both the old and new shares
Copy a few representative project files and media assets from the old share to the new share
Test these files in Final Cut Pro to verify proper access and functionality
If testing is successful, migrate remaining data via the Mac client:
Use Finder to copy files from the old share to the new share
Monitor the transfer for errors or warnings
Verify file integrity after the transfer completes
Update Final Cut Pro libraries and project files to point to the new share location.
Keep the old share available for a period of time as a backup until you confirm all workflows function correctly with the new share.

Using SMB Shadow Copy

When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.

TrueNAS automatically enables shadow copies for SMB shares, exporting ZFS snapshots as Shadow Copies for Microsoft clients.

About SMB Shadow Copies

Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. You can use shadow copies to restore previous versions of files from within Windows Explorer.

By default, all ZFS snapshots for a dataset underlying an SMB share path are presented to SMB clients through the volume shadow copy service or are accessible directly with SMB when the hidden ZFS snapshot directory is within the SMB share path.

TrueNAS 25.10 and later does not support per-share disabling of SMB shadow copies on non-legacy shares.
If you need to completely disable shadow copies and prevent client access to ZFS snapshots, disable the ZFS snapshot directory for the shared dataset. Go to Storage > Datasets, select the shared dataset, and click Edit on the Details widget. In the Edit Dataset screen, select Advanced Options and set Snapshot Directory to Disabled. When the snapshot directory is disabled, Samba automatically turns off the shadow copy feature.

Deleting Shadow Copies

Users with an SMB client cannot delete shadow copies. Instead, the administrator uses the TrueNAS web interface to remove snapshots.

Managing Shadow Copies (Legacy Shares)

Enabling or disabling shadow copies is an available option in pre-25.10 TrueNAS releases or for legacy shares in 25.10 or later.

TrueNAS sets a share Purpose to Legacy Share after upgrading to 25.10 when shares created in a release before 25.10 have Purpose set to No Preset. See Legacy Share Settings for more information.

To enable shadow copies for a compatible dataset, go to Shares > Windows (SMB) Shares and locate the share.

Click on the Edit option for the share.

If not listed, click Windows (SMB) Shares launch to open the Sharing > SMB screen. Select the share, then click the more_vert for the share, then click Edit to open the Edit SMB screen.

Click Advanced Options, scroll down to Other Options, and then select Enable Shadow Copies.

Click Save.

Windows 10 v2004 Issue

Some users might experience issues in the Windows 10 v2004 release where they cannot access network shares. The problem appears to come from a bug in gpedit.msc, the Local Group Policy Editor.

Unfortunately, setting the Allow insecure guest logon flag value to Enabled in Computer Configuration > Administrative Templates > Network > Lanman Workstation in Windows does not affect the configuration.

To work around this issue, edit the Windows registry. Use Regedit and go to HKLM\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters. The DWORD AllowInsecureGuestAuth is an incorrect value: 0x00000000. Change this value to 0x00000001 (Hexadecimal 1) to allow adjusting the settings in gpedit.msc. You can use a Group Policy Update to apply the edit to a fleet of Windows machines.

Disable shadow copies for an SMB share by clearing the Enable shadow copies checkbox on the Edit SMB screen in the Other Options on the Advanced Options screen for the SMB share. Disabling does not prevent access to the hidden .zfs/snapshot directory for a ZFS dataset when it is within the path for an SMB share.

Setting Up SMB Private Dataset Shares

When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.

SMB Home Share is a legacy feature for organizations looking to maintain existing SMB configurations. Microsoft deprecated the Home Shares feature in Windows 10 and removed it completely from Windows 11. They no longer support Home Shares as of October 2025. TrueNAS removed the home share option from the SMB share Purpose list in 24.04 (Dragonfish).
The SMB share Other Options in pre-25.10 releases includes a home share legacy option, but it is not recommended for new shares. It is for organizations still using the legacy home shares option to add a single SMB share to provide a personal directory for every user account. Future TrueNAS releases can introduce instability or require configuration changes affecting this legacy feature. This option does not show in 25.10 and later releases unless an existing home share is upgraded to 25.10 or later.

Adding Private Dataset Shares

Private directories are not intended for every user on the system.

When setting the Purpose dropdown list to the Private Dataset Share option, TrueNAS might show the private directories to all users with access to the root level of the share, but setting the share ACL prevents other users from accessing the private share.

Examples of setting up private SMB shares are those for backups, system configuration, and users or departments that need to keep information private from other users.

This article covers:

Adding the private dataset share user.
Creating the private dataset share and the dataset.
Modifying ACL permissions for the dataset (who has access to the file system) and the share (who has access to the share).

The share user is the individual user account for the private dataset share. You can manually create this user as described below, or by using a directory server (FreeIPA or Active Directory). Users 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?

User Access Levels

Users are assigned different access levels by TrueNAS administrators. All user accounts are assigned access levels based on their roles or system privileges. All users are assigned the SMB Access by default.

SMB Access is the default user access type assigned to user accounts that require access to SMB shares. It uses the user account credentials to access data shared with SMB.

TrueNAS requires other options based on the level of access. TrueNAS Access shows the predefined roles available in TrueNAS. Assigning TrueNAS Access requires setting one of the options or roles: Full Admin, Readonly Admin, or Sharing Admin.

Some administration users require access to the TrueNAS shell or might require access using an SSH session. These users must be assigned the Shell option and or the SSH Access options. If a user only requires access to the TrueNAS Shell screen, assign the user Shell Access. If the user requires SSH session access, assign the SSH Access to the user. This provides access to the Shell screen and an SSH session. SSH Access requires adding an SSH keypair to TrueNAS, and then copying the public key into the Add User or Edit User screen. Turn on the SSH service before establishing an SSH session, and then turn it off when access is no longer required to maintain a security-hardened system.

When creating a user, you must:

Enter a value in Full Name or description for the user, such as a first and last name.
Enter a value in Username.
Enter a value in Password and confirm that password.
Specify or accept the default user ID (UID)

To manually add a new user, 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.
Setting up SSH Access
These options only show when you select the SSH Access option. Only Full Admin users who require SSH session access should be configured with this option.
Select the optional Allow SSH Login with Password if you want to allow this user to log in to an SSH session and not be prompted to enter a password. This is not recommended as it presents a security vulnerability!
Manually enter or copy/paste the public key in the Public SSH Key field to assign a public SSH key to the user for key-based authentication.
Do not enter the private key!
After adding authentication settings, complete the SSH access by setting up sudo commands in the next step.
Always keep a backup of an SSH public key if you are using one.
Enter additional details for the user. Setting options change based on the access option selected in Allow Access. If this is an SMB share user, leave the default SMB Access selected.
When Shell Access and SSH Access are assigned to the user, the Shell and Sudo Command settings show in the Additional Details section.
Figure 1: Additional Details Settings
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.
Figure 2: User Group Settings
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list. Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID. TrueNAS suggests a user ID starting at 3000, but you can change it if you wish. We recommend using an ID of 3000 or greater for non-built-in users.
(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty. This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory. If set to this path, TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Figure 3: User Home Directory Settings
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory. The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset. After clicking on a dataset, the Create Dataset option activates. Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist. pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure. This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did. This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign. For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task. See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished. Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password. To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Figure 4: Add User Sudo Command Options
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password. To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.

Using AD to Add Users with Private Shares

Using AD to Add Users and Private Dataset Shares

You can manually add users and groups in TrueNAS, or configure groups in Active Directory and add users to each group, and then have AD add the users and group to TrueNAS. After AD adds users and groups, configure private directories, and if needed for other file system functions not related to private directory shares, configure home directories for the users and group(s). See Managing Users for more information on adding home directories.

Before setting up SMB shares, check system alerts to verify that no errors related to connections to Active Directory are listed. Resolve any issues with Active Directory before proceeding. If Active Directory cannot bind with TrueNAS, you cannot start the SMB service after making changes.

Adding Share Users with Directory Services

You can use Active Directory to create the share users.

If not already created, add a pool, then join Active Directory.

Go to Storage and create a pool.

Next, set up the Active Directory that you want to share resources with over your network.

When creating the share for this dataset, use the SMB preset for the dataset, but do not add the share from the Add Dataset screen.

Do not share the root directory!

Go to Shares and follow the instructions listed above using the Private Dataset Share preset, and then modify the file system permissions of the dataset to use the NFSv4_HOME ACL preset.

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.
Figure 5: Strip ACL Warning
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.
Figure 6: Configure ACL Dialog
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.

Checking Parent Dataset File Permissions

To avoid possible permission issues or error messages when creating the private dataset share, check the file system permissions assigned to the parent dataset for the private share dataset. If the admin user who creates the private dataset share and dataset is not listed as the owner or as an ACL entry, the permission issues blocks creating the share dataset.

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.
Figure 7: Add Share Advanced 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.
Figure 8: Edit Private Share Dataset
Follow naming conventions for:
- Files and directories
- Share names
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.

Setting ACL Permissions

There are two types of ACL permissions for shares: file system and share permissions. The private dataset share requires both the dataset and share ACL permissions to allow or prevent access to the share.

If you did not modify the dataset ACL permissions as described above, when prompted by the system to configure the dataset ACL, accept the option. The Edit ACL screen for the new private share dataset opens. This controls who can access or modify file system permissions for the dataset the share uses.

The Edit Share ACL option for the share opens the Share ACL for rikka-private screen where you can 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.

Figure 10: Set the owning group to Domain Admins

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.

Figure 11: Set the Share ACL Permissions

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.

Replacing SMB Home Shares

This section applies to users upgrading from earlier releases of TrueNAS where they configured SMB shares for use as home shares.

TrueNAS has removed the Use as Home Share option, found in the Other Options section of the Advanced Options screen for the Add SMB and Edit SMB screens in earlier releases of TrueNAS. The Private Dataset Share 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.

What is a private dataset and share?

The Private Dataset Share option allows creating a private personal directory for a user in the specified dataset, that when correctly configured, provides users with a private folder only they access through an SMB share.

A Private Dataset Share is not the same as guest access:
Private Dataset Share creates per-user isolated datasets - users must authenticate with credentials
Guest Access (Legacy Share only) allows anonymous access without credentials
If you are looking for guest access functionality, see the Guest Access section in the main SMB tutorial.

TrueNAS allows creating one private directory per user, while it still allows creating as many non-private directories as desired or needed. When a user first authenticates to a Private Dataset Share, TrueNAS automatically creates a subdirectory named after their username (for example, /mnt/poolname/share-name/username/). Each user only sees and can access their own subdirectory when connecting to the share. Users can create as many directories as needed through Windows File Explorer.

TrueNAS does not control what Windows allows through the File Explorer. 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.

What about the home directory?

A user home directory in TrueNAS is a function of the ZFS file system and is not related to the SMB private dataset share or (deprecated Home Share). A user configuration does not need to specify or add a file system home directory for a private dataset share.

Other options for configuring individual user directories include:

Configure a single share on the TrueNAS and provision individual user directories on the client OS.
Create a single SMB share and configure the ACL so that users can create individual directories on the share that inherit write access for the user and grant read access to the administrator.
Create an SMB share using the Private 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̈ (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.

Configuring Multiple Network Interfaces

Do not configure multiple SMB multichannel interfaces on the same subnet. To ensure reliable multichannel performance, TrueNAS recommends placing each interface on a different subnet.

If interfaces share a subnet, the system could fail to initialize multichannel, experience several connectivity issues, and accept inbound traffic inconsistently. To avoid these issues, assign each NIC a unique IP address on a different subnet and avoid bridging interfaces used for multichannel.

Activating Multichannel in TrueNAS

If you already have clients connected to SMB shares, disconnect them before activating multichannel.

Go to System > Services and click the edit edit icon for the SMB service.
Click Advanced Settings, then enable Multichannel.
Save and restart the SMB service, then reconnect all clients to their SMB Shares.

Validating Multichannel Activated In Windows

After you connect a client to their SMB share, open Powershell as an administrator on a client, then enter Get-SmbMultichannelConnection. The terminal should list multiple server IPs.

# View active SMB multichannel 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

# 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.

Figure 18: Windows (SMB) Share Widget without Shares

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.

Figure 19: Windows (SMB) Share Widget with Shares

The Windows (SMB) Shares launch header shows the status of the SMB service as either STOPPED (red) or RUNNING (green). Before adding the first share, the STOPPED status displays in the default color. The header is a link that opens the Sharing > SMB screen.

The more_vert dropdown list shows four options available to SMB shares and the SMB service in general:

Turn Off/ON Service toggles to Turn Off Service when the SMB service is enabled, and to Turn On Service when the SMB service is disabled.
Config Service opens the SMB configuration screen.
SMB Sessions opens the SMB Status screen with showing Sessions.
Audit Logs opens the Audit screen with a predefined filter applied to show the SMB logs.

The widget shows a table listing SMB shares created in TrueNAS. Each SMB share row on the Windows (SMB) Shares widget shows the path to the shared dataset, a description if one is entered when the share is added, an Enabled toggle that allows you to enable or disable the share, and indicates if audit logging is turned on/off.

The more_vert dropdown list for each share shows four options:

edit Edit opens the Edit SMB screen.
Edit Share ACL opens the Edit Share ACL screen.
Edit Filesystem ACL opens the Edit ACL screen.
delete Delete opens the Delete dialog.

The delete delete icon opens the Delete dialog.

Select Confirm to activate the Delete button.

SMB Screen

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.

SMB Table

The SMB table lists all SMB shares added to the system. The table header shows the status of the SMB service as stopped or running. The table columns show the share name, the path to the dataset for the share, and a description, if added during share creation. The Enabled toggle allows you to enable/disable the share. When enabled, the share path is available when the SMB service is active. If disabled, the share is disabled but not deleted from the system. Audit Logging indicates whether auditing for the share is enabled or disabled.

The more_vert dropdown list at the right of each table row shows four options for a share:

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.

Add and Edit SMB Screens

The two SMB share configuration screens, Add SMB and Edit SMB, have the same SMB share setting options.

The Create Dataset option becomes active after selecting a parent dataset in the Path file browse field. It opens the Create Dataset dialog.

Save creates the share (or saves an existing one) and adds it to the Windows (SMB) Shares widget and the SMB table on the SMB screen.

Enable Now appears on both the Add SMB and Edit SMB screens after selecting the Time Machine Share option in Purpose if the Enable SMB2/3 Protocol option is not already enabled in the Advanced Options section of the SMB service screen.

Enable Now also appears on both the Add SMB and Edit SMB screens after selecting the Final Cut Pro Storage Share option in Purpose if the Enable Apple SMB2/3 Protocol Extensions option is not already enabled in the Advanced Options section of the SMB service screen. When this requirement is not met, an inline requirement error message appears below the Purpose field stating: This parameter requires Apple SMB2/3 protocol extension support to be enabled in SMB service. Click Enable Now to enable the required setting. The service updates automatically.

Basic Settings

The Basic Options settings show by default on the Add and Edit SMB screens. Basic settings show for all share options in the Purpose dropdown list; only the External Share option shows the Remote Path setting.

Browsing to select a path

Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.

Setting	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 arrow_right icon to the left of expands the dataset directory tree. Root datasets do not show and cannot be selected for shares unless the share existed prior to upgrading to 25.10 or later releases.
Create Dataset	Creates a dataset for a share while configuring the share. Inactive until the parent dataset is selected. It opens the Create Dataset dialog, where you enter a name for a new dataset. The dataset name becomes the SMB share name. Create adds the dataset and populates Name field on the Add SMB screen.
Name	Sets the name for the share. This text entry field accepts manual entry or copy/paste of a name for the share that does not exceed 80 characters. A name must not exceed 80 characters because of how the SMB protocol uses the name. A name cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. Name is automatically populated with the name of the dataset when you use Create Dataset. If not supplied, the share name becomes the last component of the path. This forms part of the full share path name when SMB clients perform and SMB tree connect. If changing the name, follow the naming conventions for files and directories or share names.
Purpose	Sets the share type to one selected on the dropdown list. Options are: Default Share - The SMB share uses standard configuration with default settings suitable for general-purpose file sharing. This is the recommended option when you do not need specialized share functionality. Time Machine Share - The SMB share is optimized for Apple Time Machine backups. This option configures the share to serve as a backup destination for macOS devices. It requires SMB2/3 protocol support enabled in the SMB service configuration. Final Cut Pro Storage Share - Available in TrueNAS 25.10.1 and later. The SMB share is optimized for Final Cut Pro workflows. This option requires Apple SMB2/3 protocol extensions enabled in the SMB service configuration and forcibly enables Apple name mangling for proper media file handling. Warning: Name mangling can cause unexpected behavior for existing data written without this feature enabled. See Setting Up Final Cut Pro SMB Shares for details. Multi-Protocol Share - The SMB share is configured for multi-protocol (SMB and NFS) access. Set this if the path is shared through NFS, FTP, or used by containers or apps. Note: This setting can reduce SMB share performance because it turns off some SMB features for safer interoperability with external processes. Incompatible with the Stateful Failover SMB service setting. Time Locked Share - The SMB share makes files read-only through the SMB protocol after the set grace period ends. WARNINGS: This setting does not work if the path is accessed locally or if another SMB share without the Time Locked Share purpose uses the same path. This setting might not meet regulatory requirements for write-once storage. Private Datasets Share - The server creates a new ZFS dataset for each user when the client connects, using the specified dataset naming schema in options. The server uses this dataset as the share path during the SMB session. This provides isolated storage spaces for individual users. External Share - The SMB share is a DFS proxy to a share hosted on an external SMB server. Use this option to redirect users to shares on other servers. The selected option applies predetermined settings and changes the settings shown in Other Options when showing advanced options.
Remote Path	Sets the path to a remote server and share. Each server entry must include a full domain name or IP address and the share name. Separate the server and share name with the `\` characters. Example: 192.168.0.200\SHARE. This text entry field accepts copy/paste of a path to the external server and share. Shows when Purpose is set to External Share.
Description	A text-entry field for a brief description or notes about how this share is used. The description entered shows in the Description column on the Windows (SMB) Shares widget on the Shares dashboard and the SMB table on the SMB screen.
Enabled	A toggle that shows the status of the share and allows enabling or disabling the share. This does not enable or disable the SMB service. Enabled is the default setting.

Advanced Options Settings

Advanced Options settings are grouped into three categories:

Access
Audit Logging
Other Options

Access and Audit Logging settings show for all share options in the Purpose dropdown list. The Other Options settings change based on the share option selected in the Purpose dropdown list.

Access Settings

Access settings customize access to the share and files, and specify allowed or denied access for host names or IP addresses. All share options listed in the Purpose dropdown show these settings.

For datasets with NFSv4 ACL type, SMB clients automatically use access-based enumeration. This means directory listings over SMB only include files and directories for which the client has read permissions. This behavior is enabled by default and matches FreeBSD behavior.

Setting	Description
Export Read-Only	Prohibits writes to the share when enabled.
Browsable to Network Clients	Determines whether this share name is included when browsing shares. Enabled by default. Private dataset shares (the replacement for home shares) are only visible to the owner, regardless of this setting.
Access Based Share Enumeration	Restricts share visibility to users with read or write access to the share. This setting applies to datasets with a POSIX ACL type. For datasets with NFSv4 ACL type, access-based enumeration is automatically enabled and cannot be disabled. See the smb.conf manual page.
Hosts Allow	Specifies a list of allowed IP addresses or host names. When populated, restricts access to only the addresses entered. This can break UI access for all other IP or host name entries. Separate entries by pressing `Enter`. See smb.conf for detailed syntax. Not available for External Share preset.
Hosts Deny	Specifies a list of denied IP addresses or host names. Works in combination with Hosts Allow to control access. Separate entries by pressing `Enter`. See smb.conf for detailed syntax. Not available for External Share preset.

Hosts Allow and Hosts Deny interaction:

Both empty: Any host can access the share
Hosts Allow populated, Hosts Deny empty: Only hosts in Allow list can access
Hosts Allow empty, Hosts Deny populated: All hosts except those in Deny list can access
Both populated: Hosts in Allow list can access; hosts not in either list can access; hosts in Deny list cannot access

Legacy share additional access options:
Shares with Purpose set to Legacy Share display additional access controls not available in modern presets:
Enable ACL - Configure custom ACL entries
Allow Guest Access - Enable anonymous access without credentials
See Legacy Share Settings for complete details on these options.

Audit Logging

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 Minimum Protocol is set to SMB1 on the SMB Service screen. Starting in TrueNAS 25.10.1, shares are automatically disabled in the running configuration if the watch or ignore lists contain invalid groups.
Watch List	Specifies groups to audit. Click the field to display the dropdown list of group options. Auditing applies only to user accounts that are members of groups in this list. If the same user belongs to groups in both the Watch List and Ignore List, the watch list takes precedence, and operations are audited.
Ignore List	Specifies groups to exclude from auditing. Click the field to display the dropdown list of group options. If the same user belongs to groups in both the Watch List and Ignore List, the watch list takes precedence and operations are audited.

Other Options Settings

The Other Options settings vary based on the option selected on the Purpose dropdown list.

Default, Multi-Purpose, and External Shares

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.

Time Machine 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.

Time Locked Share

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.

Private Datasets Share

When Purpose is set to Private Dataset Share, the following settings show in Other Options.

Figure 29: Other Options - Private Dataset Share

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.

Final Cut Pro Storage Share

When Purpose is set to Final Cut Pro Storage Share, the following settings show in Other Options.

The Final Cut Pro Storage Share purpose enables Use Apple-style Character Encoding, which translates NTFS illegal characters to the Unicode private range. This ensures compatibility with Final Cut Pro.
Enabling this feature on shares with existing data might cause unexpected behavior for files that were written without Apple character encoding enabled. Test thoroughly before applying to production shares with existing content.
This share purpose requires Apple SMB2/3 Protocol Extensions to be enabled globally in the SMB service configuration.

Setting	Description
Use Apple-style Character Encoding	Automatically enabled and non-editable for Final Cut Pro Storage Share. This implements Apple-style character encoding for NTFS illegal characters, which is required for proper operation of Final Cut Pro. This setting cannot be changed for this share purpose because it is essential for Final Cut Pro compatibility.

Many online guides recommend manually configuring SMB VFS options for macOS compatibility:
vfs objects = catia fruit streams_xattr
TrueNAS does not support manual VFS module configuration. Manually setting VFS objects via auxiliary parameters or CLI overrides TrueNAS defaults and breaks Asynchronous I/O (AIO), Access Control Lists (ACLs), and Shadow Copies.
Why does TrueNAS handle VFS modules differently?
The TrueNAS SMB implementation integrates VFS modules with several advanced features. Manual VFS configuration breaks functionality including:
Asynchronous I/O (AIO): Overrides modules needed for SMB performance optimization, causing poor performance or stability issues.
Access Control Lists (ACLs): Bypasses or breaks ACL functionality, causing incorrect permission handling.
Shadow Copies: Disables Shadow Copy functionality, preventing file restoration.
The Final Cut Pro Storage Share purpose preset automatically configures VFS modules to integrate properly with TrueNAS AIO, ACLs, and Shadow Copies. By using this preset instead of manual configuration, you get a share that works seamlessly with Final Cut Pro without risking system functionality.

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.

Legacy Access Options

These settings only show on the Edit SMB screen for shares with Purpose set to Legacy Share.

Setting	Description
Enable ACL	Shows additional ACL configuration options for the share. When enabled, allows configuring custom ACL entries beyond standard share ACL settings. Only shows for Legacy Share preset.
Allow Guest Access	Allows anonymous access to the share without requiring user credentials. The privileges granted are the same as those for a guest account. Windows 10 version 1709 and Windows Server 2019 and later disable guest access by default and require additional client-side configuration. Not recommended due to security vulnerabilities. Only shows for Legacy Share preset.

Legacy Other Options

These settings only show on the Edit SMB screen after upgrading from an earlier release with an existing SMB share configured with them, unless indicated otherwise. Do not confuse these settings with those listed in the Settings by Purpose tabbed area in the section above.

Setting	Description
Use as Home Share	Allows the share to host user home directories. Each user has a personal home directory that they use when connecting to the share that is not accessible by other users. Home Shares allow for personal, dynamic shares. You can only use one share as the home share. See Adding an SMB Home Share for more information.
Time Machine Quota	Visible when Time Machine is enabled. Sets a maximum limit on storage consumed by Time Machine backups. This applies to the entire share.
Legacy AFP Compatibility	Enables backend compatibility with metadata written by legacy netatalk implementations. This option configures Samba to properly read and present Apple Filing Protocol (AFP) metadata, such as resource forks to SMB clients. Only enable this option when migrating data that was previously shared via the AFP. Pure SMB shares and standard macOS SMB clients do not require this compatibility option. Shows only when a pre-25.10 share selected this option.
Enable Shadow Copies	Exports ZFS snapshots as Shadow Copies for Microsoft Volume Shadow Copy Service (VSS) clients.
Export Recycle Bin	Renames deleted files to a per-user subdirectory within the `.recycle` directory at either the root of the SMB share if the path is the same dataset as the SMB share (default is share and dataset have the same name), or at the root of the current dataset if datasets are nested. Nested datasets do not have automatic deletion based on file size. Do not rely on this function for backups or replacements of ZFS snapshots.
Use Apple-style Character Encoding	Samba uses a hashing algorithm for NTFS illegal characters by default. Enabling this option translates NTFS illegal characters to the Unicode private range. Select to convert NTFS illegal characters in the same manner as macOS SMB clients. By default, Samba uses a hashing algorithm for NTFS illegal characters. Apple extension options cannot be set if Purpose is set to the multi-protocol option.
Enable Alternate Data Streams	Allows multiple NTFS data streams. Disabling this option causes macOS to write streams to files on the file system.
Enable SMB2/3 Durable Handles	Allows using open file handles that can withstand short disconnections. Support for POSIX byte-range locks in Samba is also disabled. This option is not recommended when configuring multi-protocol or local access to files.
Enable FSRVP	Enables support for the File Server Remote VSS Protocol (FSVRP). This protocol allows remote procedure call (RPC) clients to manage snapshots for a specific SMB share. Requires setting the share path to a dataset mount point. Snapshots have the prefix `fss-` followed by a snapshot creation timestamp. A snapshot must have this prefix for an RPC user to delete it.
Path Suffix	Appends a suffix to the share connection path. Use to provide individualized shares on a per-user, per-computer, or per-IP address basis. Suffixes can contain a macro. See the smb.conf manual page for a list of supported macros. The connection path must be preset before a client connects.
VUID	Sets the user session identifier to a valid universally unique identifier (UUID4). Samba uses the UUID to uniquely identify the share for macOS Time Machine backups. A UUID4 string is 36-character hexadecimal in format 8-4-4-4-12 (for example, `123e4567-e89b-12d3-a456-426614174000`). Generate using commands or online tools. Shows for Legacy Share with Time Machine functionality enabled.
Additional Parameters String	Shows a string of parameters associated with the share preset selected, or if no preset, enter additional smb4.conf parameters not covered by the TrueNAS API.

Create Dataset

The Create Dataset dialog adds a new dataset under the parent dataset selected in the file browser Path field on the Add SMB or Edit SMB share screens.

The Share ACL for sharename screen edits permissions at the share level for the selected share. Settings configure new ACL entries for the selected SMB share and apply them at the entire SMB share level, but do not apply to the dataset. It is separate from file system permissions. To configure dataset permissions, use the Edit Filesystem ACL option.

The Share ACL for sharename screen opens after clicking on the Edit Share ACL icon on the Windows (SMB) Shares widget or the more_vert on the Sharing SMB details screen.

ACL Entries shows a block of settings that specify who and the permissions they are granted.

Add shows a block of these settings to enter who, the permissions level, and type.

Save stores the share ACL and immediately applies it to the share.

Setting	Description
SID	Shows the security identifier (SID) trustee value or to whom this ACL entry (ACE) applies. SID is a unique value of variable length that identifies the trustee. Shown as a Windows Security Identifier. Save and re-open Edit Share ACL to update.
Who	Sets permissions to apply to the ACL entry for the domain for the selected account (who). Options are: User - Select to show the User field. Enter or select a user (who) from the dropdown list to apply the permissions for this ACL entry, which is shown as a username. Group - Select to show the Group field. Enter or select a group (who) from the dropdown to apply the permissions for this ACL entry, which is shown as a group name. everyone - Select to apply the ACL entry permissions to everyone.
Permission	Sets the level of access to a selected predefined permission combination from the dropdown list. Options are: FULL - Grants read access, execute permission, write access, delete objects, change permissions, and take ownership (RXWDPO) permissions. CHANGE - Grants read access, execute permission, write access, and delete object (RXWD) permissions. READ - Grants read access and execute permission on the object (RX). For more details, see smbacls(1).
Type	Sets how TrueNAS applies permissions to the share to the selected option on the dropdown list. Options are: ALLOWED - Denies all permissions by default, except manually defined permissions. DENIED - Allows all permissions by default, except manually defined permissions.

Edit Filesystem ACL Screen

The Edit Filesystem ACL option sets permissions at the dataset level. It opens the Edit ACL screen for the dataset the share uses. See Edit ACL Screen for more information on the settings found on this screen.

Use the ACL editor screen to set file system permissions for the shared dataset. See Permissions for more information on configuring permissions.

SMB Status Screens

The SMB Status screen shows a table of SMB session IDs from the audit logs for SMB share sessions. It opens after clicking SMB on the icon on the System > Services screen, or after clicking SMB Sessions on the more_vert dropdown list on the Windows (SMB) Shares widget.

The SMB Status screen shows information related to SMB sessions, for example:

Sessions ID - The current SMB sessions (default view).
Hostname - The host name associated with the session ID.
Remote machine - The remote machine information.
Username - The username associated with the session.
UID - The user ID associated with the session.
GID - The group ID for the user associated with the session.
Session Dialect - The version of the SMB protocol.
Encryption - The share encryption.
Signing - The security mechanism used, such as an authentication algorithm like AES-128-GCM, etc.

Refresh updates the information shown on the screen.

Column shows a dropdown list of options to customize the information included in the table on the screen.

Sharing or SBM on the top breadcrumb returns to the selected screen name.

NFS Shares

Unix (NFS) shares allow TrueNAS to share data with Unix-like operating systems and other NFS-compatible clients.

Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.

NFS Shares Screens: Provides information on NFS Shares screens and settings.

Adding NFS Shares

When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.

About UNIX (NFS) Shares

Creating a Network File System (NFS) share on TrueNAS makes a lot of data available for anyone with share access. Depending on the share configuration, you can restrict users to read or write privileges.

NFS treats each dataset as its own file system. When creating the NFS share on the server, the specified dataset is the location that the client accesses. If you choose a parent dataset as the NFS file share location, the client cannot access any nested or child datasets beneath the parent.
If you need to create shares that include child datasets, SMB sharing is an option. Note that Windows NFS Client versions currently support only NFSv2 and NFSv3.

The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.

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.

You have the option to create the share and a dataset at the same time from either the Add Dataset or Add NFS screens.

If creating a dataset and share from the Add Dataset screen, we recommend creating a new dataset with the Dataset Preset set to Generic for the new NFS share. Or you can set it to Multiprotocol and only select the NFS share type.

Creating a Dataset Using Add Dataset

To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.

Select a dataset (root, parent, or child), then click Add Dataset.

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.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.

If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.

Click Save.

Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.

To create the share and dataset from the Add NFS Share screen:

Go to Shares > Unix (NFS) Shares and click Add to open the Add NFS Share configuration screen.

Enter the path or use the arrow_right icon to the left of /mnt to locate the dataset and populate the path.

Browsing to select a path

Click 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.

Adjusting Access Permissions

To tune the NFS share access permissions or define authorized networks, click Advanced Options.

Figure 5: Advanced Options Access Settings

Select Read-Only to prohibit writing to the share.

To map user permissions to the root user, enter a string or select the user from the Maproot User dropdown list. To map the user permissions to all clients, enter a string or select the user from the Mapall User dropdown list.

To map group permissions to the root user, enter a string or select the group from the Maproot Group dropdown list. To map the group permissions to all clients, enter a string or select the group from the Mapall Group dropdown list.

Select an option from the Security dropdown. If you select KRB5 security, you can use a Kerberos ticket. Otherwise, everything is based on IDs.

Security Types

Setting	Description
SYS	Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5	Uses Kerberos for authentication.
KRB5I	Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P	Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.

To edit an existing NFS share, go to Shares > Unix (NFS) Shares and click the share you want to edit. The Edit NFS screen settings are identical to the share creation options, but you cannot create a new dataset.

Starting the NFS Service

To begin sharing, click the more_vert on the toolbar and select Turn On Service. Turn Off Service displays if NFS is on. Turn On Service displays if NFS is off.

Figure 6: Unix (NFS) Shares Widget Options

Or you can go to System > Services, locate NFS, and click the Start Service button to start the service. Toggle Start Automatically on if you want NFS to activate when TrueNAS boots.

The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.

Configuring the NFS Service

You can configure the NFS service from either the System > Services screen or the Shares > Unix (NFS) Shares widget.

To configure NFS service settings from the Services screen, click on the System > Services screen to open the NFS service screen.

To configure NFS service settings from the Shares > Unix (NFS) Shares widget, click the Config Service from the more_vert dropdown menu on the widget header to open the NFS service screen.

Unless you need specific settings, we recommend using the default NFS settings.

When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.

TrueNAS Enterprise
NFS over RDMA
TrueNAS Enterprise customers utilizing NFS shares with compatible hardware can enable NFS over RDMA to improve NFS performance and efficiency. Remote Direct Memory Access (RDMA) lets a client system transfer data directly from server memory to its own, improving speed, reducing latency, and lowering CPU usage.
NFS over RDMA support requires an active Enterprise license and RDMA-capable network interface cards (NICs) in the TrueNAS host and client systems. Interested customers should contact Enterprise Support for assistance.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

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.

Figure 2: Unix (NFS) Share Widget with Shares

The Unix (NFS) Share launch header shows the status of the NFS service as either STOPPED (red) or RUNNING (green). Before adding the first share, the STOPPED status displays in the default color. The header is a link that opens the NFS screen.

The more_vert dropdown list shows three options available to NFS shares and the NFS service in general:

Turn Off/ON Service toggles to Turn Off Service when the NFS service is enabled, and to Turn On Service when the NFS service is disabled.
Config Service opens the NFS configuration screen.
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 more_vert dropdown list for each share shows two options:

edit Edit opens the Edit NFS screen.
delete Delete opens the Delete dialog.

Enable Service 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 delete icon displays a delete confirmation dialog that removes the share from the system.

Select Confirm to activate the Delete button.

NFS Screen

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.

NFS Table

The NFS table lists all NFS shares added to the system. The table header shows the status of the NFS service as stopped or running. The table columns show the path to the dataset for the share, the share description if added during share creation, networks, and hosts. The Enabled toggle allows you to enable/disable the share. When enabled, the share path is available when the NFS service is active. If disabled, the share is disabled but not deleted from the system.

Columns shows a set of options to customize the list view. Options include Unselect All, Path, Description, Enabled and Reset to Defaults.

The more_vert dropdown list at the right of each table row shows two options for a share:

Edit opens the Edit NFS screen.
Delete displays the Delete dialog.

Add and Edit NFS Screens

The Add NFS and Edit NFS show the same Basic Options and Advanced Options settings.

The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.

Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.

Basic Options

The Basic Options settings on the Add and Edit NFS screens show by default, and at the top of the screen when Advanced Options is selected.

Browsing to select a path

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 arrow_right icon to the left of to expand the dataset directory tree.
Create Dataset	Creates a dataset for a share while configuring the share. Inactive until the parent dataset is selected. It opens the Create Dataset dialog, where you enter a name for a new dataset. The dataset name becomes the last part of the NFS share path. Create adds the dataset and populates Path field on the Add NFS screen.
Description	A text-entry field for a brief description or notes about how this share is used. The description entered shows in the Description column on the Unix (NFS) Shares widget on the Shares dashboard and the NFS table on the NFS screen.
Enabled	Select to enable this NFS share. Clear the checkbox to disable this NFS share without deleting the configuration.
Networks	Defines an authorized network, and any added, restricts access to all other networks. Leave empty to allow all networks. Add shows the Networks IP address and CIDR fields to enter an allowed network IP and select the mask CIDR notation. Click Add for each network address and CIDR you want to define as an authorized network.
Add hosts	Defines allowed clients (hosts) you want to allow to connect to the share. Defining authorized systems restricts access to all other systems. Leave the field empty to allow all systems access to the share. Add shows the Authorized Hosts and IP addresses field. Enter a host name or IP address to allow that system access to the NFS share. Click Add for each allowed system you want to define.

Advanced Options Settings

Advanced Options settings tune the share access permissions and define authorized networks. Advanced Options shows the Access settings listed below.

Figure 8: Add NSF Advanced Options Access Settings

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.

Security Types

Setting	Description
SYS	Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5	Uses Kerberos for authentication.
KRB5I	Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P	Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.

NFS Sessions Screen

The NFS Sessions screen shows a table of sessions with the IP address and Export status of each session listed. You can access the NFS Sessions screen from the :

icon on the NFS service row on the System > Services screen
more_vert 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

About 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.

Choosing a Setup Method

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 You Begin

Before adding a multiprotocol share, start the SMB and NFS services. From the Shares screen, click more_vert 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 more_vert on the widget and select Config Service, or go to System > Services and click 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.

Configuring the NFS Service

Open the NFS service settings using Config Service from the more_vert menu on the Unix (NFS) Shares widget. Alternatively, go to System > Services and click 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.

Securing NFS Access

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.
Figure 4: Adding a Multi-Mode Dataset and Share
(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 more_vert 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.
Figure 5: Edit SMB Purpose
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 more_vert icon and then click Edit. The Edit NFS screen opens with the Basic Options settings showing.
Figure 6: Edit NFS Multiprotocol Share
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.
Figure 7: Advanced Options Security Settings
(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.

Adjusting the Dataset ACL

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 security 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.

Figure 9: Editing Multi-Mode Dataset Permissions

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)

TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations. IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.

iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack. The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack. Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance clould suffer if your data traffic is traversing the Internet).

The table below shows where iSCSI sits in the OSI network stack:

OSI Layer Number	OSI Layer Name	Activity as it relates to iSCSI
7	Application	An application tells the CPU that it needs to write data to non-volatile storage.
6	Presentation	OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage.
5	Session	Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU).
4	Transport	OSI encapsulates the iSCSI PDU within a TCP segment.
3	Network	OSI encapsulates the TCP segment within an IP packet.
2	Data	OSI encapsulates the IP packet within the Ethernet frame.
1	Physical	The Ethernet frame transmits as bits (zeros and ones).

Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing. Block sharing provides the benefit of block-level access to data on the TrueNAS. iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.

iSCSI Terminology

Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively. iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network. The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes. It also requires that each node is given a unique iSCSI name. To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
- dash (-)
- dot (.)
- colon (:)
- lower case characters (a…z). Upper-case characters must be mapped to their related lower-case counterparts.
- digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN. The result is an iSCSI connection that emulates a connection to a SCSI hard disk. Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs. When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size. This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU). A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways. Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames. Systems administrators should also account for the impact on host CPU utilization. Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment. Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.

TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system. HA storage clusters can provide multiple paths to the same storage. For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer. The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage. If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage. When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.

iSCSI Configuration Methods

There are a few different approaches for configuring and managing iSCSI-shared data:

TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores. This is all managed through the vCenter web interface.

TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.

Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.

Setting Up Fibre Channel: Provides instructions on setting up Fibre Channel on TrueNAS.

Using an iSCSI Share: Provides information on setting up a Linux or Windows system to use a TrueNAS-configured iSCSI block share.

Increasing iSCSI Available Storage: Provides information on increasing available storage in zvols and file LUNs for iSCSI block shares.

Block (iSCSI) Share Target Screens: Provides information on Block (iSCSI) Share Targets screens and settings.

Fibre Channel Screens: Provides information on iSCSI Fibre Channel screens and settings.

Adding iSCSI Block Shares

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 You Begin

Before adding iSCSI shares, make sure you have already created a zvol or a dataset with at least one file to share. Do not use capital letters or spaces in the names or path. Take note of the path to the zvol or file.

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.
Figure 2: iSCSI Wizard Extent Screen Device Settings
Figure 3: iSCSI Wizard Extent Screen File Settings
If using a zvol, select Device in Extent Type. You can create a new zvol or select an existing zvol as the Device.
Adding a New Device
To create a new zvol, set Device to Create New.
Browse to select the path to the parent dataset using the file browser field below Pool/Dataset. Selecting the parent dataset activates Create Dataset.
Click Create Dataset, enter a name that does not exceed 64 lowercase alphanumeric and/or special characters, then click Create. The mount path under Pool/Dataset populates with the path to the new zvol.
To use an existing zvol, after selecting Device in Extent Type, select Existing, then browse to select the existing zvol.
Enter a numerical value and suffix to specify the size of the zvol you are creating in Size.
Adding a File
To use a file for the extent, select File in Extent Type.
Enter or browse to select the mount point to the directory you want to use. If a directory does not exist, after selecting the parent dataset where you want to add the directory, enter a / followed by the name to add the directory to the dataset.
Enter the size for the directory in Filesize. Leave this set to 0 to use the actual file size. This requires that the file already exists. Otherwise, specify the file size for the new file.
c. Select the sharing platform, then click Next or on Protocol Options to advance to the next step.
Create a portal or select an available existing portal.
Figure 4: iSCSI Wizard Protocol Options Screen Portal Settings
Select a portal from the dropdown list or click Create New to add a new portal. If you create a new portal, click Add to enter an IP address and netmask (CIDR) for the portal. To add another, click Add again.
Leave Initiator blank to allow all, or enter a host name to limit access to the select client. To enter more than one host name, press Enter after each to separate each entry. You can edit initiators from the individual screens on the iSCSI screen after adding the target.
click Save.

iSCSI Manual Setup

This procedure guides you through adding an iSCSI share using the individual configuration screens. While the procedure places each screen in order, you can select tab screens in any order.

Click on the Block (iSCSI) Share Targets widget header to open the iSCSI screen. The Targets screen shows by default.

Add a target.
Figure 5: Add iSCSI Target Screen
a. Click Add to open the Add iSCSI Target screen.
Figure 6: 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.
Figure 7: Add iSCSI Extent Device Type
Figure 8: Edit iSCSI Extent File type
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.
Adding a Device Extent
```
  After choosing **Device** in **Extent Type**, select the zvol or zvol snapshot from the **Device** dropdown list. The zvol must already exist to add it here.
  
  Accept the default in **Logical Block Size** or change the size to what fits your use case.
```
Adding a File Extent
```
  After choosing **File** in **Extent Type**, enter or browse to select the path to an existing file.
  Enter a slash (/) followed by a file name to create a file in a dataset and append the file name to the path (/filename.ext).

  Enter the file size. Enter **0** to use the actual file size of an existing file, or specify the size to apply to the new file added in **Path to the Extent**.
```
f. Leave Disable Physical Block Size Reporting disabled unless you want to enable this function.
g. Enter a product identification for the extent in Product ID or leave it blank to use the default iSCSI Disk used when left empty.
h. Click Save.
Add initiator groups. Click on the Initiators tab, then click Add to open the Add Initiator screen.
Figure 9: 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.
Figure 10: 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.
Figure 11: 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.

Creating a Quick iSCSI Target

TrueNAS allows users to add iSCSI targets without adding the extent, portal, initiators, etc. You can create the target and add the rest later.

Go to Shares and click the Block (iSCSI) Shares Targets widget header to open the iSCSI screen with the Targets tab selected by default.

Click Add to open the Add iSCSI Target screen.
Enter a name in Target Name. Use lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in the iqn.format. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
(Optional) Enter a user-friendly name in Target Alias.
Add authorized networks. Click Add to show the Network fields where you can enter an IP address and netmask (CIDR). This allows communication between client computers and the iSCSI target. Click Add for each address you want to add. Addresses are added to the authorized networks list.
Click Add to the right of Add Groups to enter portal settings. Portal and group settings can be added later or on the Add Portal screen, and initiator groups can be added by editing the target or using the Add Initiators screen.
Select a target with a number assignment from the dropdown list in Portal ID.
Select the authentication method from the dropdown list. None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication. For more information on authentication methods, see iSCSI Screens.
Select a portal ID from the Initiator Group ID dropdown list.
The Authentication Group Number dropdown list is populated after configuration groups on the Add Authorized Access screen. Edit the target after adding these groups if you want to include them.
Click Save.

Starting the iSCSI Service

After adding a share with the iSCSI wizard or manual entry screens, the system shows a dialog prompting you to start or restart the service.

You can also start the service by clicking on the more_vert on the Block (iSCSI) Shares Targets widget and selecting Turn On Service. You can go to System > Services, locate iSCSI on the service list, and click the Start Service button to start the service.

Setting Up Fibre Channel

The Fibre Channel feature is available to Enterprise-licensed High Availability (HA) and non-HA systems. Any Enterprise system, equipped with the required fibre channel hardware can implement this feature.

This article provides instructions for VMware VCenter ESXi. If you are using a different platform for your block share backups, use the documentation for that platform for alternative instructions for the ESXi process documented in this tutorial. .

Before You Begin

When setting up iSCSI fibre channel for the first time:

(Optional) Create a zvol for each fibre channel port with a network interface associated with it.
The wizard provides an option to create a dataset on the Extents screen when adding the device. Selecting this option creates a dataset for organizational purposes and a zvol of the same name for block storage.

Configuring Fibre Channel - First-Time Install

We recommend using the iSCSI wizard to create your target, create the extents, and set up fibre channel ports.

If the system is a High Availability (HA) system, turn on ALUA.

Click on the iSCSI widget header to open the Sharing iSCSI screens. Click on Global Target Configuration. Scroll down and select Asynchronous Logic Unit Access (ALUA), then click Save.

iSCSI Global Target Configuration Screenl — Figure 1: iSCSI Global Target Configuration Screen

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.
Figure 2: iSCSI Wizard Target Screen - Fibre Channel
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.
Figure 3: iSCSI Extents Screen - Fibre Channel
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.
Figure 4: iSCSI Wizard Protocol Options 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 more_vert button, stop the service, and when the status indicates it is stopped, start it.
Log into your block storage backup platform (i.e., VCenter ESXi) and configure your adaptors, devices, and datastores. Refer to VMWare or documentation for the platform used for instructions on completing the configuration.

Using an iSCSI Share

Connecting to and using an iSCSI share can differ between operating systems.

This article provides instructions on setting up a Linux and Windows system to use the TrueNAS iSCSI block share.

Using Linux iSCSI Utilities and Service

In this section, you start the iSCSI service, log in to the share, and obtain the configured basename and target. You also partition the iSCSI disk, make a file system for the share, mount it, and share data.

Click here for more information

Before you begin, open the command line and ensure you have installed the open-iscsi utility. To install the utility on an Ubuntu/Debian distribution, enter command sudo apt update && sudo apt install open-iscsi. After the installation completes, ensure the iscsid service is running using the sudo service iscsid start command.

First, with the iscsid service started, run the iscsiadm command with the discovery arguments and get the necessary information to connect to the share.

Next, discover and log into the iSCSI share.

Run the command sudo iscsiadm \--mode discovery \--type sendtargets \--portal {IPADDRESS}. The output provides the basename and target name that TrueNAS configured.
Alternatively, enter sudo iscsiadm -m discovery -t st -p {IPADDRESS} to get the same output. Note the basename and target name given in the output. You need them to log in to the iSCSI share.
When a Portal Discovery Authentication Method is CHAP, add the three following lines to /etc/iscsi/iscsid.conf.
```
discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = user
discovery.sendtargets.auth.password = secret
```
The user for discovery.sendtargets.auth.username is set in the Authorized Access used by the iSCSI share Portal. Likewise, the password to use for discovery.sendtargets.auth.password is the Authorized Access secret. Without those lines, the iscsiadm does not discover the portal with the CHAP authentication method.
Enter comand sudo iscsiadm \--mode node \--targetname {BASENAME}:{TARGETNAME} \--portal {IPADDRESS} \--login, where {BASENAME} and {TARGETNAME} is the discovery command information.

Now you partition an iSCSI disk.

When the iSCSI share login succeeds, the device shared through iSCSI shows on the Linux system as an iSCSI Disk. To view a list of connected disks in Linux, enter command sudo fdisk -l.

Because the connected iSCSI disk is raw, you must partition it. Identify the iSCSI device in the list and enter sudo fdisk {/PATH/TO/iSCSIDEVICE}.

Use the fdisk command defaults when partitioning the disk.

Remember to type w when finished partitioning the disk. The w command tells fdisk to save any changes before quitting.

After creating the partition on the iSCSI disk, a partition slice displays on the device name. For example, /dev/sdb1. Enter fdisk -l to see the new partition slice.

Next, make a file system on the iSCSI disk.

Finally, use mkfs to make a file system on the new partition slice. To create the default file system (ext2), enter sudo mkfs {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.

Mount the iSCSI device and share the data.

Enter sudo mount {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}. For example, sudo mount /dev/sdb1 /mnt mounts the iSCSI device /dev/sdb1 to file /mnt.

This section provides instructions on setting up Windows iSCSI Initiator Client to work with TrueNAS iSCSI shares.

Click here for more information

To access the data on the iSCSI share, clients need to use iSCSI Initiator software. An iSCSI Initiator client is pre-installed in Windows 7 to 10 Pro, and Windows Server 2008, 2012, and 2019. Windows Professional Edition is usually required.

First, click the Start Menu and search for the iSCSI Initiator application.

Next, go to the Configuration tab and click Change to replace the iSCSI initiator with the name created earlier. Click OK.

Next, switch to the Discovery Tab, click Discover Portal, and type in the TrueNAS IP address.

If TrueNAS changed the port number from the default 3260, enter the new port number.
If you set up CHAP when creating the iSCSI share, click Advanced…, set Enable CHAP log on, and enter the initiator name and the same target/secret set earlier in TrueNAS.

Click OK.

Go to the Targets tab, highlight the iSCSI target, and click Connect.

After Windows connects to the iSCSI target, you can partition the drive.

Search for and open the Disk Management app.

The current state of your drive should be unallocated. Right-click the drive and click New Simple Volume….

Complete the wizard to format the drive and assign a drive letter and name.

Finally, go to This PC or My Computer in File Explorer. The new iSCSI volume should display under the list of drives. You should now be able to add, delete, and modify files and folders on your iSCSI drive.

Increasing iSCSI Available Storage

Expanding LUNs

TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage in an iSCSI share.

Zvol LUNs

To expand a Zvol LUN, go to Datasets and click the Zvol LUN name. The Zvol Details widget displays. Click the Edit button.

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.

File LUNs

Go to Shares and click Configure in the Block (iSCSI) Shares Targets screen, then select the Extents tab.

Click the 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.

Figure 1: Block (iSCSI) Share Target Widget without Shares

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 more_vert dropdown list of iSCSI share and service options. The header is a link that opens the iSCSI screen.

Wizard opens the Wizard iSCSI wizard on the Target screen. See Target Screens below.

The more_vert dropdown list shows two options available to iSCSI shares and the iSCSI service in general:

Turn Off/ON Service toggles to Turn Off Service when the iSCSI service is enabled, and to Turn On Service when the iSCSI service is disabled.
Config Service opens the iSCSI Global Configuration screen.

The more_vert dropdown list for each target shows two options:

edit Edit opens the Edit iSCSI Target screen.
delete Delete opens the Delete dialog.

Start iSCSI Service 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 Target Dialog

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.

iSCSI Global Configuration Screen

The iSCSI Global Configuration screen opens when you click Edit on the iSCSI Service row of the System > Services screen, and after clicking the Global Target Configuration button at the top of all iSCSI share screens.

Global Configuration Settings

Setting	Description
Base Name	Enter a name using lowercase alphanumeric characters. Allowed special characters are dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section RFC3721 for more information.
ISNS Servers	Enter host names or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Press `Enter` to separate each entry.
Pool Available Space Threshold (%)	Generate an alert when the pool reaches this percentage of space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port	TCP port used to access the iSCSI target. The default is 3260.

iSCSI Wizard Screens

The Wizard button opens the iSCSI wizard on the Targets screen. The wizard has three screens:

Target
Extent
Protocol Options

The wizard steps you through creating an iSCSI target, adding the extent for the target, including setting up the storage (device or file) it uses, and setting up the portal and initiators for the target.

Alternatively, you can use the individual iSCSI screens, accessible by clicking on the iSCSI widget header, to manually configure targets, extents, portals, etc. The Targets screen opens by default. For more information on iSCSI screens and settings, see iSCSI Screens below.

Next advances to the next wizard screen. Back shows the previous wizard screen. Save creates the iSCSI share.

iSCSI Wizard Target Screen

The iSCSI Wizard opens and shows the Target screen.

The Target dropdown shows Create New and any other existing targets on the system. Create New creates a target. Selecting an existing target from the dropdown list allows you to edit it, but we recommend using the iSCSI Target screen to edit an existing target rather than using the wizard screens.

iSCSI Wizard Extent Screen

The iSCSI wizard Extent screen shows settings to name the target, set the type of extent storage (device or file), and the sharing platform for the device.

Figure 8: iSCSI Wizard Extent Screen File Settings

Wizard Extent Settings

Setting	Description
Name	The name given to the iSCSI block target. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Extent Type	The storage device for the target. The dropdown list shows two options: Device and File. Selecting Device shows the Device dropdown list. File sows the Path to the Extent fields and the Filesize field.
Device	Shows if Extent Type is set to Device. Shows Create New or a list of iSCSI extents added to the system. Create New shows the Pool/Dataset fields and the Size field.
Pool/Dataset	Sets the mount path to the zvol for the extent. Shows two fields after selecting Create New in Device. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the extent parent dataset on the local file system that TrueNAS exports over the iSCSI protocol. Use the arrow_right icon to the left of to expand the dataset directory tree. Create Dataset activates after selecting the parent dataset.
Size	Sets the block size for the zvol. Shows after clicking Create New in Device and after adding the mount point to the zvol in Pool/Dataset. Enter a numerical value and a suffix to specify the block size for the zvol you are creating.
Path to the Extent	Sets the mount path to the file. Shows if Extent Type is set to File. Enter or browse to select the mount point for the directory and file for the extent to use. If a directory does not exist, after selecting the dataset where you want to add the directory, and then enter a / followed by the name to add the directory to the dataset or zvol.
Filesize	Sets the size of the file. Shows if the Extent Type is set to File. Enter the size for the directory. Leaving this set to 0 uses the actual file size and requires the file to exist. Otherwise, specify the file size for the new file.
Sharing Platform	Sets the platform type for the target extent connection. Shows for both Device and File options. Select the platform that matches your use case. Options are: VMware: Extent block size 512b, TCP enabled, no Zen compat mode, SSD speed Xen: Extent block size 512b, TCP enabled, Xen compat mode enabled, SSD speed Legacy OS: Extent block size 512b, TCP enabled, no Xen compat mode, SSD speed Modern OS: Extent block size 4k, TCP enabled, no Xen compat mode, SSD speed

iSCSI Wizard Protocol Options Screen

The iSCSI wizard Protocol Options screen shows settings to add a portal and initiators. Create New shows settings to add a new portal if one does not exist.

Wizard Protocol Options Settings

Setting	Description
Portal	Sets the portal for the target and extent. Shows a dropdown list with the Create New option and lists existing portals on the system available for the target and extent. Selecting Create New shows the IP Address field and Add button. Add shows another IP Address field each time it is clicked to allow adding multiple portals.
IP Address	Sets the network address used for the portal. The dropdown list shows several options for setting up a portal: 0.0.0.0 - Listens on all IPv4 addresses. :: - Listens on all IPv6 addresses. TrueNAS server IP address - Uses the IP address assigned to the primary network interface for the TrueNAS server being configured.
Initiators	Initiators send commands over the TCP/IP network to the target and receive responses from the target. Leave blank to allow all (recommended) or enter a list of initiator host names (to limit access). Separate each host name by pressing `Enter` after entering each host name.

iSCSI Screens

The iSCSI screen provides access to manage targets, and the extents, initiators (clients), portals, and authorized access for the targets. The iSCSI screen shows five tabs: Targets, Extents, Initiators, Portals, and Autorized Access. The iSCSI screen opens with the Targets tab selected by default.

The Block (iSCSI) Shares Targets widget header opens the iSCSI screens.

Global Target Configuration opens the iSCSI service configuration screen.

Wizard opens the iSCSI wizard configuration screens.

iSCSI Target Screen

iSCSI targets are storage resources on an iSCSI server that are made available to iSCSI initiators (clients) over a TCP/IP network. The target is a server-side storage object that encapuslates a block storage resource (e.g., a phyical disk, logical volume, or file) and makes it accessible to initiators via the iSCSI protocol. A target is identified by a unique iSCSI qualified name (IQN), and is associated with portal groups for network access and initiator groups for access control.

The Target tab shows by default when opening the iSCSI screen. Use it to manage iSCSI targets.

The Targets table lists all targets added to the system. It shows the target name and alias if one is configured for it. The first row of the table is selected by default.

Each target shows three Details for targetname widgets:

iSCSI 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.

Target Detail Widgets

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:
- Associate button
- Remove Extent Association link_off icon.
iSCSI Authorized Networks - Shows a list of authorized networks configured when you create the target or using the Authorized Network settings on the Add or Edit iSCSI Target screens.
iSCSI Connections - Shows a list of the connections.

Remove Extent Association Dialog

The Remove Extent Association link_off icon opens the Remove extent association dialog that shows the LUN link association and two buttons: Cancel and Remove.

Removing the association activates the Associate button on the Extent widget. The Associate button is inactive when the extent is associated with a LUN. Clicking the button opens the Associate target dialog.

Associate 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.

Add or Edit Target Screens

The Add Target and Edit Target screens show the same configuration settings.

Target Basic Info Settings

Setting	Description
Target Name	The name of the target, consisting of a maximum of 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Target Alias	An alternative, optional user-friendly name for the target.
Authorized Networks	Networks authorized or allowed to communicate between initiators (client computers) and iSCSI targets (storage devices) over the IP network. Add shows the Network field.
Network	Network addresses for authorized networks. Shows after clicking Add to the right of Authorized Networks. Enter the IP address for the network and select the netmask (CIDR) from the dropdown list. Address must be a public address. Adds the network address to the iSCSI Authorized Network widget.

Target iSCSI Group Settings

Setting	Description
Add Groups	Adds a collection of network interfaces, IP addresses, and TCP ports, on a storage device that an iSCSI initiator can connect to. Groups are also known as target portal groups. Add shows a group configuration field each time it is clicked.
Portal Group ID	Select the ID from the dropdown list. Shows a group for each iSCSI share added to the system with a number assignment, for example, 1 (test2) for the test2 target/share. Portal groups are created on the Add Portal screen.
Initiator Group ID	Select the group ID from the dropdown list. Shows a group for each portal ID configured on the system, for example, *1 (ALL Initiators Allowed). Initiator groups have access to the target.
Authentication Method	Select the authentication method from the dropdown list of options. Options are: None - Select to allow anonymous discovery. When set to None you can leave Discovery Authentication Group set to None or empty. CHAP - Select to use the Challenge Handshake Authentication Protocol (CHAP) method. CHAP verifies the identity of an iSCSI initiator (device trying to access storage) by sending a challenge that only the authentic initiator can correctly respond to. This prevents unauthorized access to the storage target. Think of it like a password-based authentication system for iSCSI connections. When set to CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen. Mutual CHAP- Select to use CHAP where both the iSCSI initiator (client) and target server mutually authenticate each other using the CHAP method. Each side verifies the identity of the other before establishing a connection. This provides a higher level of security compared to one-way CHAP. When set to mutual CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Authentication Group Number	Select the group from the dropdown list. An authentication group is configured on the Add Authorized Access screen. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses.

Extents Screens

The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.

Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.

Delete Extent Dialog

The Delete iSCSI Extent name deletes the specified extend. The name of the extent shows in the dialog title.

Delete iSCSI Extent Dialog — Figure 16: Deleted iSCSI Extent Dialog

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.

Add or Edit Extent Screens

The Add Extent and Edit Extent screens show the same configuration settings.

Edit iSCSI Extent File Type — Figure 18: Edit iSCSI Extent File type

Extent Basic Info Settings

Setting	Description
Name	Text entry field that accepts manual or copy/paste entry of a name for the extent. An Extent where the size is not 0 cannot be an existing file within the pool or dataset.
Description	Text entry field that accepts manual or copy/paste entry of notes about this extent.
Enabled	Enables the iSCSI extent.

Extent Compatibility Settings

Setting	Description
Enable TPC	Allows an initiator to bypass normal access control and access any scannable target when selected. Third Party Copy (TPC) enables a disk target to process Extended Copy (XCOPY) operations that would otherwise be blocked, allowing data transfers to occur directly between storage devices without passing through the initiator.
Xen initiator compat mode	Select when using Xen as the iSCSI initiator.
LUN RPM	Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. Sets the RPM in iSCSI related to a LUN based upon the option selected on the dropdown list. Options are UNKNOWN, SSD, 5400, 7200, 10000 or 15000.
Read-only	Prevents the initiator from initializing this LUN when selected.

Extent Type Settings

Setting	Description
Extent Type	Provides virtual storage access to zvols or files. Select the extent (zvol) option from the dropdown list. Dropdown options: Device - Select to specify a device (default option). Device provides virtual storage access to zvols and zvol snapshots. Shows the Device field. File - Select to specify a path to a file. File provides virtual storage access to a single file. Shows the Path to the Extent and Filesize fields.
Device	Shows after specifying Device in Extent Type. Select the unused zvol or zvol snapshot from the dropdown list.
Path to the Extent	Consists of two fields: a blank field for the mount path to the device or file, and a file browser field directly below it that allows browsing to select the file or zvol. After selecting a parent dataset, the Create Dataset link activates. Enter a slash (/) followed by a file or zvol name to create a file in a dataset, and append the file name to the path (/filename.ext).
Filesize	Enter 0 to use the actual file size of an existing file, or specify the file size for the new file added in Path to the Extent.
Product ID	Product identification string for the extent. The default is iSCSI Disk when left empty.
Logical Block Size	Shows the default 512 size. If the initiator requires a different block size, enter the numerical value.
Disable Physical Block Size Reporting	Select if the initiator does not support physical block size values over 4K (MS SQL).

Initiators Groups Screen

The Initators Groups screen manages iSCSI initiator groups for targets. Initiator groups are a logical grouping of iSCSI initiators (clients), identified by their iSCSI qualified name (IQN), that control access to iSCSI targets they are associated with, and define what operations clients can perform on storage for those targets.

The Initiators Groups screen shows after clicking the Initiator tab. The table lists initiator groups configured on the system.

Add opens the Add Initiator screen. Edit opens a version of the Add Initiator screen with only two fields. Delete opens a dialog to delete an initiator group.

Add Initiator Screen

Add opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.

Add Initiator Group Settings

Setting	Description
Allow All Initiators	Select to allows all initiators.
Allowed Initiators (IQN)	Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description	Enter any notes about the initiators.
Connected Initiators	Shows the list of connected initiators on the system.
Allowed Initiators	Shows the list of allowed initiators on the system.
Refresh	Updates the screen.

Edit Initiator Screen

Edit opens the Add Initiator edit screen showing two options: Allow All Initiators and Description. Save saves changes and closes the screen. Cancel closes the screen without saving changes.

Portals Screens

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.

Add or Edit Portals Screens

The Add Portal and Edit Portal screens show the same configuration settings.

Portal Basic Info Settings

Setting	Description
Description	Enter an optional description. Portals are automatically assigned a numeric group.
Add Listen	Click Add to show the IP Address field where you add the IP address and netmask (CIDR) for the portal.
IP Address	Shows several options for setting up a portal. Select from these options: 0.0.0.0 - Select to listen on all IPv4 addresses. :: - Select to listen on all IPv6 addresses. TrueNAS server IP address - Select to use the IPv4 address assigned to the primary network interface for the TrueNAS server being configured. IPv6 address assigned to the system.

Authorized Access Screens

The Authorized Access screen shows a table listing groups allowed to access the target. The Authorized Access table lists the group ID, user, and peer users. settings to create new authorized access networks or edit existing ones in the list.

The table shows No records have been added yet until you add access.

Figure 25: iSCSI Authorized Access Screen

Add opens the Add Authorized Access screen.

The more_vert dropdown list for each group ID shows two options:

edit Edit opens the Edit iSCSI Assoicated Access screen.
delete 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.

Add or Edit Authorized Access Screens

The Add Target and Edit Target screens show the same configuration settings.

Authentication Method and Group Settings

Setting

Description

Group ID

Enter a number. Allows configuring different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.

Discovery Authentication

Select the discovery method for authentication from the dropdown list. iSCSI supports multiple authentication methods that initiators use to discover valid devices. Options are:

None - Select to allow anonymous discovery.

CHAP - Select to use CHAP as the authentication method for discovery. If set to CHAP, configure a User and Secret.

Mutual CHAP - Select to use the Mutual CHAP two-way authentication method for discovery. To show this option, configure the Peer User and Peer Secret.

Discovery Authentication is a system-wide setting. If CHAP or Mutual CHAP are selected, it takes effect for discovery independently of whether the same Authorized Access is also used to control login access to targets.
Multiple Authorized Access entries can be configured with CHAP Discovery Authentication, but only one Mutual CHAP can be configured system-wide.

User Settings

Setting	Description
User	User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret	Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a Password does not match error until you enter the same password in Secret (Confirm).
Secret (Confirm)	Enter the same password to confirm the user password.

Peer Settings

Setting	Description
Peer User	(Optional) Enter only when configuring mutual CHAP. Usually the same value as User. Configure the peer user name and password to see Mutual CHAP in the Discovery Authentication dropdown list.
Peer Secret	Enter the mutual secret password. Required if entering a Peer User. Peer user must use a different password than the password in Secret.
Peer Secret (Confirm)	Enter the same password to confirm the mutual secret password.

Fibre Channel Screens

TrueNAS Enterprise
Fibre Channel is a TrueNAS Enterprise feature. Only TrueNAS systems licensed for Fibre Channel show iSCSI Fibre Channel screens and settings found by going to Sharing > Block Shares (iSCSI).

Enterprise systems with fibre channel hardware can access fibre channel settings and screens through various iSCSI wizard and share screens.

iSCSI Wizard Screens - Fibre Channel.

The Block (iSCSI) Shares Targets widget shows iSCSI shares configured for fibre channels. The Wizard button on the header opens the Wizard iSCSI wizard on the Target screen. See Target Screens - Fibre Channel below.

Figure 1: Block (iSCSI) Shares Targets Widget with Fibre Channel

The more_vert icon button shows two options: a toggle for Turn On Service/Turn Off Service and Config Service. Config Service opens the iSCSI Global Configuration screen.

iSCSI Target Wizard Screen - Fibre Channel

The Wizard button opens the iSCSI wizard on the Targets screen with the Fibre Channel option. The wizard has three screens:

Target
Extent
Protocol Options

To access the individual iSCSI screens click on the iSCSI widget header. The Targets screen opens by default. For more information on iSCSI screens and settings, see iSCSI Screens - Fibre Channel below.

Next advances to the next wizard screen. Back shows the previous wizard screen. Save creates the iSCSI share.

iSCSI Wizard Target Screen - Fibre Channel

The iSCSI Wizard opens showing the Target screen with the Fibre Channel option. Select to configure the target for fibre channel.

The Target dropdown shows the default Create New. Selecting Create New creates a share. Selecting an existing target from the dropdown list allows you to edit that target.

iSCSI Wizard Extent Screen - Fibre Channel

The iSCSI wizard Extent screen shows settings to name the target, set the type of extent storage (device or file), and the sharing platform for the device.

Wizard Extent Settings

Setting	Description
Name	The name given to the iSCSI block target. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Extent Type	The storage device for the target. The dropdown list shows two options: Device and File. Selecting Device shows the Device dropdown list. File sows the Path to the Extent fields and the Filesize field.
Device	Shows if Extent Type is set to Device. Shows Create New or a list of iSCSI extents added to the system. Create New shows the Pool/Dataset fields and the Size field.
Pool/Dataset	Sets the mount path to the zvol for the extent. Shows two fields after selecting Create New in Device. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the extent parent dataset on the local file system that TrueNAS exports over the iSCSI protocol. Use the arrow_right icon to the left of to expand the dataset directory tree. Create Dataset activates after selecting the parent dataset.
Size	Sets the block size for the zvol. Shows after clicking Create New in Device and after adding the mount point to the zvol in Pool/Dataset. Enter a numerical value and a suffix to specify the block size for the zvol you are creating.
Path to the Extent	Sets the mount path to the file. Shows if Extent Type is set to File. Enter or browse to select the mount point for the directory and file for the extent to use. If a directory does not exist, after selecting the dataset where you want to add the directory, and then enter a / followed by the name to add the directory to the dataset or zvol.
Filesize	Sets the size of the file. Shows if the Extent Type is set to File. Enter the size for the directory. Leaving this set to 0 uses the actual file size and requires the file to exist. Otherwise, specify the file size for the new file.
Sharing Platform	Sets the platform type for the target extent connection. Shows for both Device and File options. Select the platform that matches your use case. Options are: VMware: Extent block size 512b, TCP enabled, no Zen compat mode, SSD speed Xen: Extent block size 512b, TCP enabled, Xen compat mode enabled, SSD speed Legacy OS: Extent block size 512b, TCP enabled, no Xen compat mode, SSD speed Modern OS: Extent block size 4k, TCP enabled, no Xen compat mode, SSD speed

iSCSI Wizard Protocol Options Screen - Fibre Channel

The iSCSI wizard Protocol Options screen for fibre channel shows three setting options to configure fibre channel ports and initiators.

Figure 5: iSCSI Wizard Protocol Options Create New Virtual Port

Wizard Protocol Options for Fibre Channel Settings

Setting	Description
Do not connect to a fibre channel port	Select to configure the share to not connect to a fibre channel port.
Use an existing port	Select to connect the share to an existing fibre channel port.
Create a new virtual port	Select to create a new virtual port. Shows the Create a new virtual port field. Select from the options on the dropdown list.

Clicking on the iSCSI widget header opens the iSCSI share screens.

Global Target Configuration opens the iSCSI service configuration screen.

Wizard opens the iSCSI wizard configuration screens.

The iSCSI shares screen opens showing Targets by default.

Six tabs show for each of the following screens: Targets, Extents, Initiators, Portals, Authorized Access, and Fibre Channel Ports. Each shows what is configured on the system, and provides access to the add and edit configuration screens for each functional area.

iSCSI Global Configuration Screen

Global Configuration Settings

Setting	Description
Base Name	Enter a name using lowercase alphanumeric characters. Allowed special characters are dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section RFC3721 for more information.
ISNS Servers	Enter host names or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Press `Enter` to separate each entry.
Pool Available Space Threshold (%)	Generate an alert when the pool reaches this percentage of space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port	TCP port used to access the iSCSI target. The default is 3260.

Targets Screens - Fibre Channel

The iSCSI Targets screen shows a list of targets configured in the system and provides access to the add and edit configuration screens. Select a target to see details about that item.

iSCSI Targets Screen - Fibre Channel — Figure 7: iSCSI Wizard Targets Screen - Fibre Channel

Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.

Details for Target

The screen shows four widgets on the right side of the screen for the selected target: Fibre Channel Port, Fibre Channel Connections, Extents, and iSCSI Connections.

Fibre Channel Port shows the fibre channel port showing the two HA assignments configured on the system, one for the HA primary controller and the other for the standby controller. These are created when you add the targets for an HA system or migrate existing from an earlier TrueNAS (13.0 or 13.3) release to the latest release.

Fibre Channel Connections shows the schema name for the ports assigned to each controller in an HA system.

Extents shows a list of LUNs, and includes two options: Associate button and a Remove Extent Association link_off icon.

iSCSI Connections shows a list of the connections configured on the system.

Delete Target Dialog

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.

Remove Extent Association Dialog

The Remove Extent Association link_off icon opens the Remove extent association dialog that shows the LUN link association and two buttons: Cancel and Remove.

Associate Dialog

The Associate dialog shows the target name.

Extent shows a dropdown list of targets to select and associate the extent with.

Add and Edit iSCSI Target Screens - Fibre Channel

The Add Target and Edit Target screens show the same configuration settings.

Figure 11: Add iSCSI Target Screen - Fibre Channel

Figure 12: Edit iSCSI Target Screen - Fibre Channel

Target Basic Info Settings

Setting	Description
Target Name	Enter the name for the target using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Target Alias	Enter an optional user-friendly name.
Mode	Mode shows three options for a target: iSCSI - Select to create a standard iSCSI share target. Fibre Channel - Select to configure an iSCSI target that includes fibre channel. Both - Select to use both modes.
Authorized Networks	Authorized networks allow communication between initiators (client computers) and iSCSI targets (storage devices) over the IP network. Add shows the Network field.
Network	Shows after clicking Add to the right of Authorized Networks. Enter the IP address for the network and select the netmask (CIDR) from the dropdown list. Adds the network address to the authorized network list.
Do not connect to a fibre channel port	Select to create an iSCSI share and target withoug fibre channel.
Use an existing port	Select to use an existing iSCSI port(s) already configured on the system. Select when migrating an existing TrueNAS FreeBSD-based iSCSI fibre channel configuration to a later TruenNAS Debian Linux-based release. Shows a dropdown list with existing ports.
Create new virtual port	Select to create a new virtual iSCSI port for fibre channel configuration. Use when setting up a new iSCSI share target and fibre channel ports. Shows the Create a new virtual port field. Select from the options on the dropdown list.

Target iSCSI Group Settings

Setting	Description
Add Groups	Adds a collection of network interfaces, IP addresses, and TCP ports, on a storage device that an iSCSI initiator can connect to. Groups are also known as target portal groups. Add shows a group configuration field each time it is clicked.
Portal Group ID	Select the ID from the dropdown list. Shows a group for each iSCSI share added to the system with a number assignment, for example, 1 (test2) for the test2 target/share. Portal groups are created on the Add Portal screen.
Initiator Group ID	Select the group ID from the dropdown list. Shows a group for each portal ID configured on the system, for example, *1 (ALL Initiators Allowed). Initiator groups have access to the target.
Authentication Method	Select the authentication method from the dropdown list of options. Options are: None - Select to allow anonymous discovery. When set to None you can leave Discovery Authentication Group set to None or empty. CHAP - Select to use the Challenge Handshake Authentication Protocol (CHAP) method. CHAP verifies the identity of an iSCSI initiator (device trying to access storage) by sending a challenge that only the authentic initiator can correctly respond to. This prevents unauthorized access to the storage target. Think of it like a password-based authentication system for iSCSI connections. When set to CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen. Mutual CHAP- Select to use CHAP where both the iSCSI initiator (client) and target server mutually authenticate each other using the CHAP method. Each side verifies the identity of the other before establishing a connection. This provides a higher level of security compared to one-way CHAP. When set to mutual CHAP you must enter or create a new group in Discovery Authentication on the Add or Edit Authorized Access screen.
Authentication Group Number	Select the group from the dropdown list. An authentication group is configured on the Add Authorized Access screen. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses.

Extents Screens - Fibre Channel

The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.

Figure 13: iSCSI Extents Screen - Fibre Channel

Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.

Delete Extent Dialog

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.

Add or Edit Extent Screens - Fibre Channel

The Add Extent and Edit Extent screens show the same configuration settings.

Extent Basic Info Settings

Setting	Description
Name	Text entry field that accepts manual or copy/paste entry of a name for the extent. An Extent where the size is not 0 cannot be an existing file within the pool or dataset.
Description	Text entry field that accepts manual or copy/paste entry of notes about this extent.
Enabled	Enables the iSCSI extent.

Extent Compatibility Settings

Setting	Description
Enable TPC	Allows an initiator to bypass normal access control and access any scannable target when selected. Third Party Copy (TPC) enables a disk target to process Extended Copy (XCOPY) operations that would otherwise be blocked, allowing data transfers to occur directly between storage devices without passing through the initiator.
Xen initiator compat mode	Select when using Xen as the iSCSI initiator.
LUN RPM	Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. Sets the RPM in iSCSI related to a LUN based upon the option selected on the dropdown list. Options are UNKNOWN, SSD, 5400, 7200, 10000 or 15000.
Read-only	Prevents the initiator from initializing this LUN when selected.

Extent Type Settings

Setting	Description
Extent Type	Provides virtual storage access to zvols or files. Select the extent (zvol) option from the dropdown list. Dropdown options: Device - Select to specify a device (default option). Device provides virtual storage access to zvols and zvol snapshots. Shows the Device field. File - Select to specify a path to a file. File provides virtual storage access to a single file. Shows the Path to the Extent and Filesize fields.
Device	Shows after specifying Device in Extent Type. Select the unused zvol or zvol snapshot from the dropdown list.
Path to the Extent	Consists of two fields: a blank field for the mount path to the device or file, and a file browser field directly below it that allows browsing to select the file or zvol. After selecting a parent dataset, the Create Dataset link activates. Enter a slash (/) followed by a file or zvol name to create a file in a dataset, and append the file name to the path (/filename.ext).
Filesize	Enter 0 to use the actual file size of an existing file, or specify the file size for the new file added in Path to the Extent.
Product ID	Product identification string for the extent. The default is iSCSI Disk when left empty.
Logical Block Size	Shows the default 512 size. If the initiator requires a different block size, enter the numerical value.
Disable Physical Block Size Reporting	Select if the initiator does not support physical block size values over 4K (MS SQL).

Initiators Screens - Fibre Channel

The Initiators Groups screen shows a table listing initiator groups configured on the system.

Figure 17: iSCSI Initiator Screen - Fibre Channel

Add opens the Add Initiator screen. Edit opens a version of the Add Initiator screen with only two fields. Delete opens a dialog to delete an initiator group.

Add Initiator Screen - Fibre Channel

Add opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.

Add Initiator Group Settings

Setting	Description
Allow All Initiators	Select to allows all initiators.
Allowed Initiators (IQN)	Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description	Enter any notes about the initiators.
Connected Initiators	Shows the list of connected initiators on the system.
Allowed Initiators	Shows the list of allowed initiators on the system.
Refresh	Updates the screen.

Edit Initiator Screen - Fibre Channel

Portal Screens - Fibre Channel

The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.

Figure 20: iSCSI Portals Screen - Fibre Channel

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.

Add and Edit Portal Screens - Fibre Channel

The Add Portal and Edit Portal screens show the same configuration settings.

Portal Basic Info Settings

Setting	Description
Description	Enter an optional description. Portals are automatically assigned a numeric group.
Add Listen	Click Add to show the IP Address field where you add the IP address and netmask (CIDR) for the portal.
IP Address	Shows several options for setting up a portal. Select from these options: 0.0.0.0 - Select to listen on all IPv4 addresses. :: - Select to listen on all IPv6 addresses. TrueNAS server IP address - Select to use the IPv4 address assigned to the primary network interface for the TrueNAS server being configured. IPv6 address assigned to the system.

Authorized Access Screens - Fibre Channel

The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.

If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.

Figure 23: iSCSI Authorized Access Screen - Fibre Channel

After adding authorized access to the system, the Authorized Access screen displays a list of users. Delete opens the Delete dialog for the selected portal ID. Confirm enables the delete option. Delete deletes the selected portal and closes the dialog.

Add opens the Add Authorized Access screen.

Edit opens the Edit Authorized Access screen. Delete opens a dialog to delete the authorized access for the selected user.

The Add and Edit screens display the same settings.

Add Authorized Access Screen - Fibre Channel

The Add Target and Edit Target screens show the same configuration settings.

Authentication Method and Group Settings

Setting

Description

Group ID

Enter a number. Allows configuring different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.

Discovery Authentication

Select the discovery method for authentication from the dropdown list. iSCSI supports multiple authentication methods that initiators use to discover valid devices. Options are:

None - Select to allow anonymous discovery.

CHAP - Select to use CHAP as the authentication method for discovery. If set to CHAP, configure a User and Secret.

Mutual CHAP - Select to use the Mutual CHAP two-way authentication method for discovery. To show this option, configure the Peer User and Peer Secret.

Discovery Authentication is a system-wide setting. If CHAP or Mutual CHAP are selected, it takes effect for discovery independently of whether the same Authorized Access is also used to control login access to targets.
Multiple Authorized Access entries can be configured with CHAP Discovery Authentication, but only one Mutual CHAP can be configured system-wide.

User Settings

Setting	Description
User	User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret	Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a Password does not match error until you enter the same password in Secret (Confirm).
Secret (Confirm)	Enter the same password to confirm the user password.

Peer Settings

Setting	Description
Peer User	(Optional) Enter only when configuring mutual CHAP. Usually the same value as User. Configure the peer user name and password to see Mutual CHAP in the Discovery Authentication dropdown list.
Peer Secret	Enter the mutual secret password. Required if entering a Peer User. Peer user must use a different password than the password in Secret.
Peer Secret (Confirm)	Enter the same password to confirm the mutual secret password.

Fibre Channel Ports Screens

The Fibre Channel Ports screen shows a table listing fibre channels configured on the system. Virtual ports show as child elements to physical ports.

Figure 25: iSCSI Fibre Channel Ports Screen

Ports are configured while setting up targets and extents. When migrating from earlier versions of TrueNAS, ports map from the earlier release to the latest TrueNAS release.

The Edit icon opens the Change Number of Virtual Ports dialog.

Change Number of Virtual Ports Dialog

The Change Number of Virtual Ports dialog shows the Virtual Ports field where you enter a numeric value to specify the number of ports for the selected fibre channel.

NVMe-oF Subsystems

Overview of NVMe-oF

NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for “fused commands” required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.

Configuring NVMe-oF: Information on NVMe-oF subsystems and instructions to create a subsystem and configure enterprise-level subsystem settings.

Managing NVMe-oF Subsystems: Provides information on managing NVMe-oF subsystems, namespaces, hosts, and ports.

NVMe-oF Share Screens: Provides information on NVMe-oF share screens and settings.

Configuring NVMe-oF

Configuring the NVMe-oF Service

You can access the NVMe-of service screen from the:

more_vert dropdown menu on the NVMe-oF Subsystems widget on the Shares screen
Global Configuration button at the top of the NVMe-oF screen
NVMe-oF service option on the System > Services screen

The NVMe-oF Global Configuration shows the base NQN for the service.

What is the Base NQN?

The Base NQN is the standardized NVMe Qualified Name for the service. It is the prefix used when a new subsystem is created. The NQN standard structure follows the format defined in the base specification. The maximum length/size is 223 bytes. TrueNAS subsystems use the Base NQN as the root identifier for the NVMe subsystems in fabric deployments. Discovery controllers use the standardized NQN to advertise available subsystems. Storage systems use the Base NQN to authenticate and authorize host connections. The Base NQN format provides the foundation for all NVMe-oF naming, ensuring interoperability, and preventing naming conflicts across different vendors and implementations.

NVMe-oF Global Configuration Screen — Figure 1: NVMe-oF Global Configuration Scree

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.

Adding Remote Direct Memory Access (RDMA)

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.

Adding Asymmetric Namespace Access (ANA)

Go to the NVMe-oF Global Configuration screen. Select the Enable Asymmetric Namespace Access (ANA) option, and click Save.

This allows storage systems to inform hosts about the optimal controller path to access a namespace on Enterprise licensed systems. It is similar to Asymmetric Logical Unit Access (ALUA) in iSCSI.

ANA helps storage arrays communicate to hosts which controller provides the best (lowest latency) path to specific namespaces, enabling intelligent multipathing and improved performance in NVMe-oF environments.

Adding a Subsystem

Subsystems correlate to iSCSI targets. Each subsystem has a namespace and port, hosts are optional for added security. The Add Subsystem wizard steps through the subsystem creation process.

You can access the Add Subsystem wizard from the:

Add button on the NVMe-oF Subsystems widget on the Shares screen
Add Subsystem button at the top of the NVMe-oF screen

Go to the Add Subsystem wizard, then:

Figure 2: Add Subsystem What to Share Screen

Enter a name for the subsystem. We recommend keeping the name short to avoid any possible issues with accessing the subsystem. A name can consist of upper and lowercase alphabetical characters, numbers, and some special characters such as the dash (-) and underscore (_).
Figure 3: Add Subsystem Access Screen
Leave the NQN set to Generate from global setting. To change it, click on it or the edit 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.
Figure 4: Add Namespace Screen
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.
Figure 5: Edit Namespace Existing File Tab
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.
Figure 6: Edit Namespace New File Tab
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.
Figure 7: Add Subsystem 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.
Figure 8: Add Host Screen
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.
Figure 9: Add Host Screen Require Authentication
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.
Figure 10: Add Port Screen
a. Select the transport type. TCP is the default setting. If you have an Enterprise license and your system can support RDMA, this option shows as an available choice.
b. Enter an available port number of at least four digits in length.
c. Select the IP address from the dropdown list.
d. Click Save.
e. Click on the breadcrumb at the top of the screen to close the Add Port screen and return to the Add Subsystem wizard.
Click Save at the bottom of the Add Subsystem wizard screen to add the subsystem.

Creating a Zvol

The Add Zvol screen is accessed from the Add Subsystem wizard after clicking Add to the right of Namespaces. You can also access it from the Namespace widget on the NVMe-oF screen.

Select the subsystem row on the NVMe-oF screen table, then click Add on the Namespaces widget to show the options.

Select Create New to open the Add Namespace screen. Browse to and select the dataset where you want to add the zvol, then click on Create New to open the Add Zvol screen.

To add a new zvol:

Enter a name. We recommend keeping the name short. You can use standard name alpha-numeric, upper or lower case letters, and approved special characters in the name.
Figure 11: Add Zvol Screen
Enter the size for the zvol. For example, 10 GiB.
Accept the default settings for the remaining settings, or click the edit edit icon to show a text entry or dropdown selection field. Enter or select the desired new settings.
(Optional) Set encryption for the zvol.
If the parent dataset where you add the zvol is unencrypted, you can set encryption by clearing the Inherit (unencrypted) checkbox.
If the parent dataset is encrypted you can only change the type of encryption as key or passphrase type. Clear the Inherit (encrypted) checkbox to see the encryption type options.
Click Save, then click the breadcrumb at the top of the screen to return to the previous screen.

Managing NVMe-oF Subsystems

NVME Structure

NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for “fused commands” required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.

Editing a Subsystem

After configuring 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 more_vert 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.

Renaming the Subsystem

To change a subsystem name, while on the NVMe-oF screen, select the subsystem row in the table, then click on the subsystem name or the edit icon in the Details 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.

Copying the NQN

To copy the NQN identification number for the subsystem, while on the NVMe-oF screen, select the subsystem row in the table, then click Copy in the Details card. TrueNAS copies the identification number to the clipboard.

Deleting a Subsystem

Before deleting a namespace subsystem, delete the port and any associated host. TrueNAS shows an error if the subsystem has an active port and 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.

Deleting a Zvol Namespace

To delete a zvol namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the zvol in the Namespace 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.

Deleting a File Namespace

To delete a file namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the file in the Namespace card.

The Delete Namespace dialog opens with the option to delete the underlying file.

Figure 2: Delete Namespace and File Dialog

Select the Also delete the underlying file option, then click Delete to delete both the namespace and the file.

Editing Ports

You can add new ports or edit existing ports from the Ports 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.

Adding a Port

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.

Editing a Port

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 edit icon for the port listed in the table to open the Edit Port screen. The Edit Port screen shows current port settings for the selected subsystem.

Select the transport type from the dropdown list. Leave TCP as the default option unless your system has an Enterprise license and it supports RDMA.

Enter a port number that is at least four digits in length. 4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.

Leave the IP address for the TrueNAS system, or select any static IP address shown on the list.

Click Save.

Removing a Port from the Subsystem

You can change the port number assigned to the subsystem using the RemoveFromSubsystem 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

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 delete icon at the right of the port row on the Ports window.

The Delete Port confirmation dialog opens. You are asked to confirm that you want to delete the port.

Delete Anyway removes the port assignment from the subsystem specified in the dialog.

Adding a Host

The Associated Hosts 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.

Figure 7: Subsystem Associated Hosts Card

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.

Figure 9: Add Host Screen Require Authentication

Accept the default in Hash or click the edit edit edit icon and select a hash option from the dropdown list. Options are SHA-256, SHA384, and SHA-512.

Obtain the DH-CHAP key from the host you are allowing to connect to the subsystem, and enter or copy/paste it in the Key For Host To Present field. Alternatively, TrueNAS can create a key for the host system if you click Generate Key directly under the field. Copy this key from TrueNAS, and paste it into the host system as the key it presents to TrueNAS to authenticate the connection.

To use bidirectional authentication, click Generate Key directly below the Key For TrueNAS To Present (Optional). It populates the field with a secret key. Copy this key from TrueNAS, and paste it into the host system to validate the TrueNAS connection.

For additional authentication security, select Also use Diffie-Hellman key exchange for additional security.

Click Save, then close the screen.

Hosts added to the subsystem show in the Associated Hosts card with options to edit, delete, or remove them from the host.

Removing a Host

Click the RemoveFromSubsystem Removes this host from the subsystem icon to remove the host from the subsystem. This does not delete it from TrueNAS; the removed host shows on the Add dropdown list if you want to add the host to the subsystem again.

Editing a Host

To edit a host, click Add, then select Manage Hosts. The Hosts window opens.

The Hosts window shows a table listing the host NQN, if it requires authentication, and the number of subsystems that use it.

Click the edit edit icon to the right of the host row to open the Edit Host screen.

The Edit Host screen shows the fields associated with the subsystem and allows you to change the host settings.

Make the desired change, then click Save.

Delete Host Dialog

To delete a host from the subsystem, click Add, then select Manage Hosts. The Hosts window opens. click the delete delete icon to the right of the host.

The Delete Host confirmation dialog opens, showing the hosts associated with the subsystem.

Click Delete Anyway to delete the host from the subsystem(s) specified in the dialog.

Activating SPDK

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.

What is the difference between SPDK and Linux Kernel?

Linux Kernel runs in the kernel space (standard Linux drivers). Choose when you need the rich Linux ecosystems features (filesystem, LVM, encryption, snapshots, and standard tools) or when you want maximum compatibility, and if you prefer lower idle CPU and easier power management.

SPDK (Userspace) runs entirely in the user space. Choose when you need maximum performance (lowest latency, highest IOPS/core, best tail latency), when the system has many NVMe drives, if you have high-speed networking (100 GbE+) requirements, and when CPU efficiency under heavy load is critical.

Figure 12: NVMe-oF Global Configuration with SPDK

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.

NVMe-oF Subsystems Card

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 more_vert dropdown menu with two options:

Turn Service On/Off toggle. You can also turn the service on/off from the System > Services screen or set it to automatically restart after a system restart.
Config Service that opens the NVMe-oF Global Configuration screen. You can access this configuration screen by going to System > Services or using the Global Configuration button on the NVMe-oF screen.

Figure 1: NVMe-oF Screen without Subsystems

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 more_vert 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.

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.

NVMe-oF Screen

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.

Subsystems Table

The NVMe-oF screen Subsystem table lists subsystems added to TrueNAS. Each row shows the subsystem name, the number of namespaces associated with the subsystem, the number of ports available through the subsystem, and the number of hosts allowed or restricted from accessing the subsystem.

Figure 4: NVMe-oF Screen with Subsystems

TrueNAS allows adding a subsystem without configuring a namespace, port, or host, which can be added later. An report_problem alert icon shows beside the namespace name in the table and on the Ports and Namespaces cards until these are added.

Details Cards

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:

Details
Namespaces
Ports
Associated Hosts

Details Card

The Details card shows the name and NQN ID associated with the TrueNAS subsystem. The NQN shows an edit edit icon that changes the NQN to a text-entry field.

Settings

Setting	Description
Name	Shows the name given to the subsystem at creation. The edit edit icon opens an edit field. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), etc.
NQN	The NVMe Qualified Name (NQN) that identifies the subsystem, includes the base NQN and the name of the subsystem. The edit edit icon changes the NQN ID to a text-entry field. It accepts copy/paste of a new properly formatted NQN ID number.

Namespaces Card

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.

Ports Card

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:

TCP - xx.xxx.x.xxx:#### if a TCP port is assigned this does not show on the list. If a port is not assigned, any available port IP address:port number for a host shows on the list.
Create New - Opens the Add Ports screen.
Manage Ports - Opens the Ports dialog.

The RemoveFromSubsystem Remove this port from the subsystem icon removes the port from the subsystem but does not delete the port from TrueNAS. After removing a port, the Add button dropdown list shows the removed port and all available ports on the system in the format IP address:port.

Associated Hosts Card

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 RemoveFromSubsystem Removes this host from the subsystem icon that only removes the host from the subsystem but does not delete it from TrueNAS.

Figure 9: Associated Hosts Card with a Host

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.

NVMe-oF Global Configuration Screen

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 edit icon on the NVMe-oF row on the System > Services screen open the NVMe-oF Global Configuration screen.

TrueNAS Enterprise
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.
Figure 11: NVMe-oF Global Configuration with SPDK
What is the difference between SPDK and Linux Kernel?
Linux Kernel runs in the kernel space (standard Linux drivers). Choose when you need the rich Linux ecosystems features (filesystem, LVM, encryption, snapshots, and standard tools) or when you want maximum compatibility, and if you prefer lower idle CPU and easier power management.
SPDK (Userspace) runs entirely in the user space. Choose when you need maximum performance (lowest latency, highest IOPS/core, best tail latency), when the system has many NVMe drives, if you have high-speed networking (100 GbE+) requirements, and when CPU efficiency under heavy load is critical.

Settings

Setting	Description
Base NQN	Text-entry field that shows the TrueNAS NVMe NQN identification number and accepts manual or copy/paste entry of a NQN. It is used as the prefix of a subsystem NQN at creation if a subNQN is not supplied. Modifying this value does not change the subNQN of any existing subsystems.
Enable Asymmetric Namespace Access (ANA)	When enabled, it allows an Enterprise-licensed High Availability (HA) storage system to inform a host about the optimal controller path to access a namespace. It is equivalent to Asymmetric Logical Unit Access (ALUA) in iSCSI. ANA helps storage arrays communicate with hosts and inform the host which controller provides the best (lowest latency) path to specific namespaces, enabling intelligent multipathing and improving performance in NVMe-oF environments.
Enable Remote Direct Memory Access (RDMA)	When enabled, it allows configuring one or more ports after enabling and selecting RDMA as the transport. It requires an Enterprise license, an RDMA-capable system, and network equipment. Inactive on systems without an Enterprise license. If the system does not have the required hardware, it shows Not enabled, because this system does not support RDMA.
Generate Cross-port Referrals for Ports on This System	When enabled, allows xport_referral. If ANA is active, referrals are always generated between the peer ports on each TrueNAS controller node.

Add Subsystem Wizard

The Add Subsystem wizard opens after clicking Add on the NVMe-oF Subsystem 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.

Settings

Setting	Description
Subsystem Name	Text-entry field for the name of the subsystem. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#).
NQN	Shows Generate from global settings and the edit edit icon. Clicking on the edit edit icon or the text changes to a text-entry field that allows manually entering an NVMe Qualified Name (NQN) that is used to identify the subsystem. TrueNAS creates an NQN using the base NQN shown on the NVMe-oF Global Configuration screen.
Add	Opens the Add Namespaces screen.

Access

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.

Figure 14: Add Subsystem Access with Allowed Hosts

The Add button to the right of Ports shows a dropdown list of options:

TCP - xx.xxx.x.xxx:#### if a TCP port is assigned this does not show on the list. If a port is not assigned, any available port IP address:port number for a host shows on the list.
Create New - Opens the Add Ports screen.
Manage Ports - Opens the Ports dialog.

Save saves changes, creates the subsystem, closes the wizard screen, and returns to the previous screen.

Add Namespace Screens

The Add Namespace ** screens show settings and options to create namespaces. Use to select or create the storage device (zvol or file) for the NVMe-oF share.

Add to the right of Namespaces on the What to Share option of the Add Subsystem wizard opens the Add Namespace screen. Add on the Namespaces card on the NVMe-oF screen opens the Add Namespaces screen.

These screens have three tabs:

Zvol (selected by default)
Existing File
New File

Zvol Tab

The Zvol tab on the Add Namespace screen allows selecting an existing or creating a new zvol namespace. There are two Path to Zvol fields: the blank field and the file browser field. The top blank field populates with the path for the existing zvol or parent dataset selected using the file browser field below it.

Create Zvol only shows on the Zvol tab. It activates after selecting the parent dataset in the file browser field. It opens the Add Zvol screen.

Existing File Tab

The Existing File tab on the Add Namespace allows selecting an existing file as a namespace. There are two Path to File fields: the blank field and the file browser field. The top blank field populates with the path for the existing file selected using the file browser field below it.

New File Tab

The New File tab on the Add Namespace screen allows creating a new file for a namespace.

Settings

Setting	Description
Parent Directory	Shows two fields: a blank text-entry field and a file browser field. The top blank field populates with the path to the parent directory selected using the file browser field below it.
Filename	Text-entry field for the name of the file. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#).
File Size	Text-entry field for the storage capacity (size) you want to grant this file.

Save saves the settings, closes the screen, and returns to the previous screen.

Delete Namespace Dialog

The Delete Namespace opens after clicking the delete icon to the right of a zvol on the Namespaces card.

The delete icon to the right of a file opens a Delete Namespace dialog showing the option to delete the file.

Add Zvol Screen

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.

Settings

Setting	Description
Name	Text-entry field for the name given to the zvol. Best practice is to enter a short name that does not exceed 63 characters to prevent issues with accessing the zvol. Names can consist of upper and lower case alphabetic, numeric, and special characters such as the dash (-), underscore (_), ampersand (&), at (@), or hashtag (#), etc.
Size	Text-entry field to specify the size and value allocated to the file. For example, enter 10 GiB.
Force size	When enabled, the system restricts creating a zvol that brings the pool to over 80% capacity. Set to force creation of the zvol (not recommended).
Sparse	Enables using thin provisioning where disk space for this volume is allocated on demand as new writes are received. Use caution when enabling this feature, as writes can fail when the pool is low on space.
Sync	Sets the data write synchronization. Options are: Inherit takes the sync settings from the parent dataset. Standard uses the settings requested by the client software. Always waits for data writes to complete. Disabled never waits for writes to complete.
Compression	Encodes information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of saved space. LZ4 is generally recommended because it maximizes performance and dynamically identifies the best files to compress. GZIP options range from 1 for least compression and best performance, through 9 for maximum compression with the greatest performance impact. ZLE is a fast algorithm that only eliminates runs of zeroes.
ZFS Deduplication	Transparently reuses a single copy of duplicated data to save space. Deduplication can improve storage capacity, but it is RAM-intensive. Compressing data is generally recommended before using deduplication. Deduplicating data is a one-way process. Deduplicated data cannot be undeduplicated!
Read-only	When enabled, it prevents modifying the zvol.
Block size	Shows a dropdown list of options to set the zvol default block size. Block size is automatically chosen based on the number of disks in the pool for a general use case.
Snapdev	Dropdown list of options to control whether the volume snapshot devices under /dev/zvol/⟨pool⟩ are hidden or visible. The default value is Inherit (hidden).

Encryption Settings

Encryption settings secure data within this zvol. These settings establish the level and type of encryption applied. The default setting is Inherit (non-encrypted) when the root or parent dataset for the new storage is unencrypted. If encrypted, this shows Inherit (encrypted).

Clearing the checkbox shows the Encryption Type setting with two options: Key and Passphrase. Each option shows different settings.

Key Type 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.

Settings

Setting	Description
Generate Key	Randomly generates an encryption key to secure the zvol. Disable to manually enter an encryption key. WARNING: The encryption key is the only means to decrypt the information stored in this zvol. Store the encryption key in a secure location.
Key	Text-entry field that accepts manually entering or copy/pasting an alphanumeric string to use as the encryption key for this zvol.
Algorithm	Dropdown list of mathematical instruction sets that determine how plain text is converted into cipher text. See [Advanced Encryption Standard (AES)(https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)] for more details.

Passphrase Type Settings

The Passphrase settings set encryption to a passphrase of your choice to encrypt the data in the zvol.

Figure 24: Add Zvol Passphrase Encryption

Settings

Setting	Description
Passphrase	Text-entry field that accepts manual or copy/paste of a user-defined string that decrypts the zvol. Use instead of an encryption key. WARNING: The passphrase is the only means to decrypt the information stored in this dataset. Be sure to create a memorable passphrase or physically secure the passphrase.
Confirm Passphrase	Confirms the user-defined string entered in Passphrase. Entries must match.
pbkdf2iters	The pencil icon shows a dropdown list of options to set the number of password-based key derivation function 2 (PBKDF2) iterations to reduce vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Algorithm	The pencil icon shows a dropdown list of options to set the mathematical instruction that determines how plain text is converted into cipher text. See Advanced Encryption Standard (AES) for more details.

Add and Edit Host Screens

The Add Host screen specifies a host and adds it to a subsystem when the Allow any host to connect option on the Add Subsystem > Access screen is not enabled. The Edit Host screen shows the fields associated with the subsystem and allows you to change the host settings.

Require Host Authentication shows the additional setting options.

Settings

Setting	Description
Host NQN	Text-entry field that accepts manual or copy/paste of the unique identifier obtained from the host you allow to access the subsystem. Format of the NQN is nqn.2019-05.com.example:storage-array-01.
Require Host Authentication	When selected/enabled, shows additional authentication settings: Hash, Key For Host To Present, Key For TrueNAs To Present (Optional), generate keys for each key option, and Also use Diffie-Hellman key exchange for additional security.
Hash	Shows the current hash option SHA-256 and the edit edit icon that shows a dropdown list of hash options. Options are SHA-256, SHA0384, and SHA-512.
Key For Host To Present	The DH-CHAP key, obtained from the host, to authenticate access to the subsystem. Accepts manual or copy/paste entry of a hash. Use Generate Key directly under the field to have TrueNAS create a key to copy/paste into the host to use as the authentication key for that host.
Generate Key	Populates the Key For Host To Present field with a TrueNAS system-generated DH-CHAP key for the host.
Key For TrueNAs To Present (Optional)	The secret key the TrueNAS system presents to the host that further validates the connection between the host and TrueNAS when the host connects to the subsystem (bi-directional authentication). Accepts copy/paste of a key or use the Generate Key directly below this field to populate with a system-generated key. Provide this key to the host connecting with TrueNAS to authenticate the TrueNAS system in the connection authorization.
Generate Key	Populates the Key For TrueNAS To Present field with a system-generated bi-directional authentication key.
Also use Diffie-Hellman key exchange for additional security	Enables further security through a Diffie–Hellman key exchange. This affords greater authentication security than using only the CHAP keys for authentication.

Hosts Window

The Hosts window shows a table listing the host NQN, if it requires authentication, and the number of subsystems that use it. The host row shows the edit edit icon and the delete delete icons.

Add New opens the Add Host screen.

Edit opens the Edit Host screen.

Delete opens a delete confirmation dialog for the port.

Delete Host Dialog

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.

Add Port Screen

The Add Port Screen shows settings to add or select a port to associate with the subsystem. Ports are formatted as IP address:port. 4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.

Settings

Setting	Description
Transport Type	Sets the transport type. Options are: TCP, RDMA, or Fibre Channel. The RDMA and Fibre Channel options require Enterprise licenses and systems with compatible/supporting hardware.
Port	Sets the current port assignment. 4420 is the default and recommended port number. We recommend using this port rather than entering a custom port number.
Address	Sets an existing static IP address for the port assignment.

Edit Port Screen

The Edit Port screen shows current port settings for the selected subsystem. The edit edit icon on the port row listed on the Ports dialog opens the Edit Port screen.

Settings

Setting	Description
Transport Type	Dropdown list of options for the transport type. Options are TCP, RDMA, or Fibre Channel. The RDMA and Fibre Channel options require Enterprise licenses and systems with compatible/supporting hardware.
Port	Text-entry field that shows the current port assignment and allows manual or copy/paste entry of a new port number.
Address	Dropdown list that shows the current static IP address assignment and any other static IP on the system that the subsystem can use.

Ports Window

The Ports window shows a table showing the port name, type, IP address, communication port number, and the number of subsystems that use it. The port row shows the edit edit icon and the delete delete icon.

Add New opens the Add Port screen.

Edit opens the Edit Port screen.

Delete opens a delete confirmation dialog for the port.

Delete Port Dialog

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.

The WebShare widget displays Open WebShare and Add buttons, and a more_vert 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.

Configuring WebShare: Tutorials to configure WebShare, a web-based file sharing feature in TrueNAS.

WebShare Shares Screens: Provides information on WebShare share screens and settings.

Configuring WebShare

Prerequisites

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

Configuring the WebShare Service

Configure the WebShare service before creating shares.

Go to Shares and locate the WebShare widget.
Click the more_vert 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.

Creating a WebShare

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.

Editing a WebShare

To modify an existing WebShare, click the edit icon on the share row. The Edit WebShare screen allows you to change the path, name, and home share setting.

Deleting a WebShare

To delete a WebShare, click the delete icon on the share row. A confirmation dialog displays before TrueNAS removes the WebShare.

Configuring User Access

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.

Accessing WebShare

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.

Using WebShare

The WebShare interface provides a file browser with toolbar buttons for common actions.

Navigating Files

The file list displays columns for file name, owner, size, and modified date. Click a folder to open it. Click the arrow_back icon in the column header to navigate to the parent directory. Click the Name column header to sort files alphabetically.

Uploading Files

Click the cloud_upload 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.

Creating Folders

Click the create_new_folder icon to create a new folder in the current directory.

The toolbar provides additional options:

filter_list Filter - Filter the file list
refresh Refresh - Refresh the current directory
history Timeline - View snapshots of the current directory
share Share - Create a shareable link
visibility_off Hidden files - Toggle visibility of hidden files
info File details - Open the file details panel

File Actions

Click the more_vert icon on a file row to access file-specific actions such as download, rename, copy, move, and delete.

Using TrueSearch

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.

Figure 1: WebShare Widget without Shares

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.

Figure 2: WebShare Share Widget with Shares

The WebShare launch 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 more_vert 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.

WebShare Table

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:

launch Open - Launches a web browser showing access to the WebShare.
edit Edit - Opens the Edit Webshare.
delete Delete - Opens a delete confirmation dialog.

The delete 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.

WebShares Screen

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.

Add and Edit WebShare Screens

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.

Browsing to select a path

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.

Migrating AFP Shares

To prevent data corruption that could result from the sidegrade operation, in TrueNAS, go to Windows (SMB) Shares, select the more_vert for the share, then select Edit to open the Edit SMB screen. Click Advanced Options and scroll down to the Other Options section. Select Legacy AFP Compatibility to enable compatibility for AFP shares migrated to SMB shares. Do not select this option if you want a pure SMB share with no AFP relation.

AFPCompatibilityCheckbox

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.

MigratedAFPShareSCALE

Connecting Migrated Shares

Since AFP shares migrate to SMB, you must use SMB syntax to mount them.

On your Apple system, press +K or go to Go > Connect to Server….

Enter smb://ipaddress/mnt/pool/dataset, where:

ipaddress* is your TrueNAS IP address
pool is the name of the pool
dataset is the name of the shared dataset

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: Configuration tutorials and UI reference for TrueCloud backup tasks in TrueNAS.

Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.
TrueCloud Backup Tasks Screens: Provides information on the TrueCloud Backup Tasks screens and settings.

Cloud Sync Tasks: Tutorials to configure and manage data backups from TrueNAS to various third-party cloud service providers.

Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.
Managing Cloud Sync Tasks: Tutorials to configure and manage data backups from TrueNAS to various third-party cloud service providers.
Adding a Google Photos Cloud Sync Task: Provides instructions on how to set up Google Photos API credentials and use them to create a cloud sync task.
Cloud Sync Tasks Screens: Provides information on the Cloud Sync task screens and settings.

Periodic Snapshot Tasks: Configuration tutorials and UI reference for periodic snapshot tasks in TrueNAS.

Adding Periodic Snapshot Tasks: Provides instructions on creating periodic snapshot tasks in TrueNAS.
Periodic Snapshot Tasks Screens: Provides information on the Data Protection and Periodic Snapshot Task screens and settings.

Rsync Tasks: Configuration tutorials and UI reference for rsync tasks in TrueNAS.

Configuring Rsync Tasks: Provides instructions on adding rsync tasks with two methods, SSH connection and module.
Rsync Tasks Screens: Provides information on the Rsync Tasks screens and settings.

Replication Tasks: Tutorials to configure ZFS snapshot replication tasks in TrueNAS.

Setting Up a Local Replication Task: Provides instructions on adding a replication task using different pools or datasets on the same TrueNAS system.
Setting Up a Remote Replication Task: Provides instructions on adding a replication task with a remote system.
Replication Task Screens: Provides information on the Replication screens, wizard, and settings used to add or edit replication tasks.
Advanced Replication Tasks: Instructions to configure advanced ZFS snapshot replication tasks in TrueNAS.

VMware Snapshots: Configuration tutorials and UI reference for VMware snapshot integration in TrueNAS.

Creating VMWare Snapshots: Provides instructions for creating ZFS snapshots when using TrueNAS as a VMWare datastore.
VMWare Snapshots Screen: Provides information on the VMWare-Snapshot Add screen settings and functions.

Data Protection Screens: Describes the screens and options contained within the Data Protection section in TrueNAS.

TrueCloud Backup Tasks

TrueCloud backup tasks allow TrueNAS to back up data to Storj iX cloud storage.

Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.

TrueCloud Backup Tasks Screens: Provides information on the TrueCloud Backup Tasks screens and settings.

Managing TrueCloud Backup Tasks

TrueNAS can send, receive, or synchronize data with the cloud storage providers available in TrueNAS.

TrueCloud backup tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.

This article provides instructions on configuring a TrueCloud backup task using Storj and covers setting up the Storj iX account and TrueNAS credential.

To take advantage of the lower-cost benefits of the TrueCloud backup service, you must create your Storj iX account using the link provided on the Add Cloud Credentials screen.
You must also create and authorize the storage buckets on Storj for TrueNAS to use.
iXsystems is not responsible for charges incurred using a third-party vendor with the TrueCloud backup feature.

TrueCloud Backup Task Requirements

You must configure all system storage (pool and datasets or zvols) and have them ready to receive or send data.

Creating a TrueCloud Backup Task

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.

Adding Storj Cloud Credentials

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.

Setting up S3 Access

After creating your Storj iX account, add S3 access credentials.

Click Access Keys to open the Access Keys dashboard, then click New Access Key.
Figure 3: Storj Access Keys Screen
The New Access window opens.
Enter the name you want to use for this credential. Select S3 Credentials for access type, then click Next.
Figure 4: Storj New Access Key Window
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.
Figure 5: Storj Access Permissions Window.
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.
Figure 6: Storj Access Select Permissions
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.
Figure 7: Storj Access Select Buckets.
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.
Figure 8: Storj Create Access Select Duration
d. Review access details and then click Create Access.
Figure 9: Storj Create Access Confirm Details
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.
Figure 10: Storj S3 Credentials Generated
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.
Figure 11: Verify Cloud Credentials
Click Save.

Creating a TrueNAS Storj Bucket

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.
Figure 12: TrueCloud Add New Bucket Settings
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.

Adding a Storj TrueCloud Backup Task

To add the TrueCloud backup task, go to Data Protection > TrueCloud Backup Tasks:

Click Add to open the Add TrueCloud Backup Task screen.
Figure 14: Add TrueCloud Backup Task
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 more_vert on the task and select Run Job to start the task apart from the scheduled time.

The task status changes to SUCCESS when complete.

Figure 15: TrueCloud Backup Task Complete

Using Advanced Options

Advanced Options and Advanced Remote Options contain additional settings for advanced users.

Figure 16: Add TrueCloud Backup Task Advanced Options

Select Use Snapshot to create and use a snapshot to back up or synchronize the operation between TrueNAS and the TrueCloud backup solution. This snapshot is automatically removed after the operation completes.

Advanced users can write scripts that run immediately before or after the TrueCloud backup task. Enter environment variables in either the Pre-script or Post-script fields. The Post-script field only runs when the TrueCloud backup task succeeds. See TrueCloud Backup Tasks Screens for information on available environment variables.

Use Exclude to enter a list of files and directories to exclude from sync. Press Enter to separate entries. See TrueCloud Backup Tasks Screens for syntax examples.

Use Transfer Settings to prevent excess resource consumption by setting the pack size and read concurrency.

Managing TrueCloud Tasks

To edit an existing TrueCloud backup task, click the vertical ellipses more_vert on the task and select Edit to open the Edit TrueCloud Backup Task screen. After making changes, click Save.

To run a scheduled task before the defined time, click the vertical ellipses more_vert on the task and select Run Job to start the task immediately.

To delete a task, click the vertical ellipses more_vert on the task and select Delete for the task to delete.

See TrueCloud Backup Tasks Screens for more information on TrueCloud Backup Task screens.

Restoring Data from TrueCloud Snapshots

To restore data from a TrueCloud backup, locate an existing snapshot on the Snapshots widget.

Click the vertical ellipses more_vert on the task and select 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.

Removing TrueCloud Snapshots

To delete an existing snapshot, locate it on the Snapshots widget. Click the vertical ellipses more_vert on the snapshot and select Delete 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 more_vert icon that opens a dropdown menu with four options for various functions:

edit Edit opens the Edit TrueCloud Backup Task screen populated with with the settings for that task.
Run Now starts and runs the backup task outside of the scheduled time.
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 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.

TrueCloud Logs Dialog

The state oval opens the Logs dialog for that task. Download Logs saves a copy of the current task logs.

TrueCloud Backup Tasks Screen

The TrueCloud Backup Tasks screen lists all tasks configured on the system. The TrueCloud Backup Tasks on the widget title or View Details on a task opens the TrueCloud Backup Tasks screen.

Task options perform the same functions as the icons on the widget:

edit Edit opens the Edit TrueCloud Backup Task screen populated with with the settings for that task.
Run Now starts and runs the backup task outside of the scheduled time.
delete 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.

Restore opens the Restore from Snapshot screen.

delete Delete opens a confirmation dialog before the system deletes the snapshot.

Restore from Snapshot Screen

The Restore from Snapshot screen shows the date and time of the selected snapshot. It shows Remote and Local configuration options to restore the TrueCloud snapshot.

Remote Settings

Remote Settings specify all data in the backup or exclude some data from a restoration. Additional settings show depending on the Include/Exclude selection.

Settings	Description
Include Everything	Select to restore all backed-up data from the remote snapshot to the selected local path.
Include from subfolder	Select to restore data from a subfolder within the backed-up data.
Subfolder	Shows when Include from subfolder is selected. Enter or browse to the subfolder within the snapshot with the data to restore.
Included Paths	Shows when Include from subfolder is selected. Select files and directories to include from the backup. Leave empty to include everything in the selected subfolder.
Select paths to exclude	Select to exclude only certain paths from the data to restore.
Excluded Paths	Shows when Select paths to exclude is selected. Enter or select files and directories to exclude from the backup. Select as many checkboxes as desired to select multiple paths or separate multiple entries with a comma.
Exclude by pattern	Select to exclude files and directories matching defined glob patterns.
Pattern	Shows when Exclude by pattern is selected.

Local Settings

Use Local settings to select the target mount point on the current (local) system where files are restored. Be cautious when setting the restore target to avoid overwriting existing files.

Target settings allow entering the path to the dataset or directory or browse to the location to populate the field with the local directory where files are restored.

Browsing to select a path

Create Dataset opens a dialog to name and create a new dataset at the selected target.

Save starts restoring data from the snapshot.

Add and Edit TrueCloud Backup Task Screen

The Add TrueCloud Backup Task and Edit TrueCloud Backup Task screens contain options to configure a new backup task. The edit screen opens populated with the existing task settings. Each screen shows the Local, Remote, Task Settings, and Control settings. The Advanced and Advanced Remote Options are for advanced users.

Figure 7: Add TrueCloud Backup Task - Basic Options

Local Settings

Local settings set the dataset or directory used in the task. Selecting the dataset populates the Source Path field.

Browsing to select a path

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_right arrow to the left of the /mnt folder to expand and show datasets and directories within that folder. This is the dataset or directory location with the data the TrueCloud backup task sends to the cloud storage provider. Click the arrow_right arrow to the left of the /mnt folder again to collapse the directory tree.

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.

Remote Settings

The Remote settings specify the TrueCloud credential and destination storage locations.

Settings	Description
Credential	Select an existing Storj iX credential from the dropdown list. TrueNAS automatically validates the selected credential. Select Add New to open the Cloud Credentials screen. This is the same configuration screen that opens when you click Add on the Credentials > Backup Credentials screen.
Bucket	Displays after selecting the Storj credential. Select a pre-configured Storj bucket. Only TrueNAS-compatible Storj buckets are selectable. Select Add New to create a new Storj bucket from the TrueNAS UI.
New Bucket Name	Displays when Add New is selected in the Bucket field. Enter a name for the new bucket. Only lowercase letters, numbers, and hyphens are allowed.
Folder	Enter or browse to select the dataset or directory to receive the backed-up data. Click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task. Enter `/name`, where name is a folder that does not exist, to create a new folder in the bucket.

Task Settings

Task Settings specify the task name, snapshot retention policy, and password for the backup repository.

Settings	Description
Name	Enter a name for the TrueCloud backup task.
Keep Last	Enter a number for the past snapshot copies to retain before removing older snapshots.
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

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.

Schedule Presets

The Schedule dropdown list preset options are:

Hourly at the start of each hour
Daily At 00:00 (12:00 AM)
Weekly On Sundays at 00:00 (12:00 AM)
Monthly On the first day of the month at 00:00 (12:00 AM)
Create Custom schedule that opens the Advanced Scheduler window.

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 N^th 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

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.

Script Environment Variables

The following environment variables can be used in pre and post-scripts.

CLOUD_BACKUP_ID

CLOUD_BACKUP_DESCRITPION

CLOUD_BACKUP_PASSWORD

CLOUD_BACKUP_KEEP_LAST

CLOUD_BACKUP_TRANSFER_SETTING

CLOUD_BACKUP_ACCESS_KEY_ID

CLOUD_BACKUP_FOLDER

CLOUD_BACKUP_BUCKET

CLOUD_BACKUP_FAST_LIST (always zero (0) for false, planned removal in Fangtooth)

Advanced Remote Options

Advanced Remote Options settings are intended for advanced users.

Settings	Description
Transfer Settings	Select the option from the dropdown list to set the number of simultaneous file transfers to allow. Options: Default - Select to use the Restic PACK_SIZE of 16 Mib and READ_CONCURRENCY to two files. Perfromance - Select to set the Restic PACK_SIZE to 29 MiB and READ_CONCURRENCY to two files. Fast Storage - Select to set the Restic PACK_SIZE to 58 MiB and READ_CONCURRENCY to 100 files.

Cloud Sync Tasks

This section has tutorials to configure and manage data backups from TrueNAS to various third-party cloud service 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:

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.

Cloud Sync Task Requirements

You must have:

All system storage configured and ready to receive or send data. A cloud storage provider account and location (like an Amazon S3 bucket).

You can create cloud storage account credentials using Credentials > Backup Credentials > Cloud Credentials before adding the sync task or add it when configuring the cloud sync task using Add on the Data Protection > Cloud Sync Task widget to open the Cloudsync Task Wizard. See the Cloud Credentials article for instructions on adding a backup cloud credential.

Cloud Sync Tasks Contents

Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.

Managing Cloud Sync Tasks: Tutorials to configure and manage data backups from TrueNAS to various third-party cloud service providers.

Adding a Google Photos Cloud Sync Task: Provides instructions on how to set up Google Photos API credentials and use them to create a cloud sync task.

Cloud Sync Tasks Screens: Provides information on the Cloud Sync task screens and settings.

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.

Setting up Google Drive Credentials

You can add Google Drive credentials using the Add Cloud Credentials screen accessed from the Credentials > Backup Credentials > Cloud Credentials screen, or you can add them when you create a cloud sync task using the Add Cloud Sync Task screen accessed from the Data Protection > Cloud Sycn Task screen.

Adding Google Drive Credentials Using Cloud Credentials

To set up a cloud credential, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.

Enter a credential name.

Select Google Drive on the Provider dropdown list. The Google Drive authentication settings display on the screen.
Enter the Google Drive authentication settings.
a. Click Log In To Provider. The Google Authentication window opens.
b. Click Proceed to open the Choose an Account window.
c. Select the email account to use. Google displays the Sign In window. Enter the password and click Next to enter the password. Click Next again. Google might display a Verify it’s you window. Enter a phone number where Google can text an verification code, or you can click Try another way.
d. Click Allow on the TrueNAS wants to access your Google Account window. TrueNAS populates Access Token with the token Google provides.
Click Verify Credentials and wait for TrueNAS to display the verification dialog with verified status. Close the dialog.
Click Save. The Cloud Credentials widget displays the new credentials. These are also available for cloud sync tasks to use.

Adding A Google Drive Cloud Sync Task

You must add the cloud credential on the Backup Credentials screen before you create the cloud sync task.

To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloudsync Task Wizard opens.

Select Google Drive on the Credential dropdown list, then enter your credentials.
Click Next.

Select the direction for the sync task. PULL brings files from the cloud storage provider to the location specified in Directory/Files (this is the location on TrueNAS). PUSH sends files from the location in Directory/Files to the cloud storage provider location you specify in Folder.
Select the transfer method from the Transfer Mode dropdown list. Sync keeps files identical on both TrueNAS and the remote cloud provider server. If the sync encounters an error, destination server files are not deleted. Copy duplicates files on both the TrueNAS and remote cloud provider server. Move transfer the files to the destination server and then deleted the copy on server that transferred the files. It also overwrites files with the same names on the destination.
Enter or browse to the dataset or folder directory. Click the arrow_right arrow to the left of folder/ under the Directory/Files and Folder fields. Select the TrueNAS dataset path in Directory/Files and the Google Drive path in Folder. If PUSH is the selected Direction, this is where on TrueNAS the files you want to copy, sync or move transfer to the provider. If Direction is set to PULL this is the location where on TrueNAS you want to copy, sync or move files to.
Click the arrow_right to the left of folder/ to collapse the folder tree.
Select the preset from the Schedule dropdown that defines when the task runs. For a specific schedule, select Custom and use the Advanced Scheduler. Clearing the Enable checkbox makes the configuration available without allowing the specified schedule to run the task.
To manually activate a saved task, go to Data Protection > Cloud Sync Tasks, click for the cloud sync task you want to run. Click CONTINUE or CANCEL for the Run Now operation.
(Optional) Click Advanced Options to set any advanced option you want or need for your use case or to define environment variables. Scroll down to and enter the variables or scripts in either the Pre-script or Post-script fields. These fields are for advanced users.
Click Dry Run to test your settings before you click Save. TrueNAS connects to the cloud storage provider and simulates a file transfer but does not send or receive data.

The new task displays on the Cloud Sync Tasks widget with the status of PENDING until it runs. If the task completes without issue the status becomes SUCCESS.

CloudSyncTaskGoogleDrivePending

See Using Scripting and Environment Variables for more information on environment variables.

Working with Google Created Content

One caveat is that Google Docs and other files created with Google tools have their own proprietary set of permissions and their read/write characteristics unknown to the system over a standard file share. Files are unreadable as a result.

GoogleDriveBadPermissions

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.

GoogleDriveShareLink

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

Creating a Cloud Sync Task

To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.

Select an existing backup credential from the Credential dropdown list.
If not already added as a cloud credential, click Add New to open the Cloud Credentials screen to add the credential. Click Save to close the screen and return to the wizard.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the option from Direction and in Transfer Mode. Select the location where to pull from or push data to in the Folder field.
Figure 2: Cloud Sync Task Wizard - What and When
Select the dataset location in Directory/Files. Browse to the dataset to use on TrueNAS for data storage. Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 3: File Explorer Folder Icons
Select or enter the required settings that include where files are stored. Cloud provider settings change based on the credential selected. If shown, select the bucket on the Bucket dropdown list.
Select the time to run the task from the Schedule options.
Click Save to add the task.

Use Dry Run to test the configuration before clicking Save or select the option on the Cloud Sync Task widget after you click Save. TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule.

Encrypting Cloud Sync Tasks

The option to encrypt data transferred to or from a cloud storage provider is available in the Advanced Options settings.

Select Remote Encryption to use rclone crypt encryption during pull and push transfers. With Pull selected as the Transfer Direction, the Remote Encryption decrypts files stored on the remote system before the transfer. This requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.

With Push selected as the Transfer Direction, data is encrypted before it is transferred and stored on the remote system. This also requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.

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.

Troubleshooting Transfer Mode Problems

Sync keeps all the files identical between the two storage locations. If the sync encounters an error, it does not delete files in the destination.

Dropbox Issues

One common error occurs when the Dropbox copyright detector flags a file as copyrighted.

BackBlaze B2 Issues

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.

Amazon S3 Issues

Sync cannot delete files stored in Amazon S3 Glacier or S3 Glacier Deep Archive. First restore these files by another means, like the Amazon S3 console.

Using Scripting and Environment Variables

Advanced users can write scripts that run immediately before or after the cloud sync task.

Use either the Advanced Options screen accessed from the Cloudsync Task Wizard or Edit Cloud Sync Task screen, scroll down to the Advanced Options to locate and then enter environment variables in either the Pre-script or Post-script fields. The Post-script field only runs when the cloud sync task succeeds.

Running an Unscheduled Cloud Sync Task

Saved tasks activate based on the schedule set for the task. Click Run Now on the Cloud Sync Task widget to run the sync task before the saved scheduled time. You can also expand the task on the Cloud Sync Tasks screen and click Run Now on the task details screen.

An in-progress cloud sync must finish before another can begin. Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.

To view logs about a running task, or its most recent run, click on the State oval.

Using Cloud Sync Task Restore

To create a new cloud sync task that uses the same options but reverses the data transfer, click the vertical ellipses more_vert on an existing cloud sync task on the Data Protection page and select 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.

Before You Begin

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.

Choosing a Sync Direction and Mode

A Google Photos cloud sync task can either push local files to Google Photos or (limited) pull files from Google Photos to a local TrueNAS dataset. Select the direction that fits how you want to manage your media files.

Pull is restricted by the Google Photos API and only accesses albums created by the TrueNAS sync client. Pulling your full library or from shared albums is not possible.

Push uploads local files into albums created by the TrueNAS sync client. Use push to manage media in your local dataset and back it up to Google Photos.

Next, select the data transfer mode that fits how you want to manage file retention between the source and destination. There are three options:

SYNC - Matches files on the destination to the source. Deletes files from the destination if they do not exist on the source. Only affects albums created by the sync client.
COPY - Duplicates each source file into the destination. Overwrites files with the same name. Only affects albums created by the sync client.
MOVE - Transfers files from the source to the destination and deletes them from the source. Overwrites files with the same name. Only affects albums created by the sync client.

Choosing a Target Folder

After choosing the direction and mode for your cloud sync task, select the remote Google Photos folder that rclone targets.
Each folder option has specific file management and structure requirements due to API restrictions.
Cloud sync tasks cannot target the root folder (/).

Folder	Recommended	Direction	Description
/album	Yes	Push or Pull	Use this folder for push tasks or to organize media into albums. Only albums created by the TrueNAS cloud sync client are accessible. Pull returns only items in these albums; push uploads work as expected. All local files must be in child directories (albums) under the dataset.
/media/all	No	Pull	API restrictions prevent reading your full Google Photos library. Only items in app-created albums are accessible. Do not use this option for full-library sync.
/upload	No	Push	Temporary upload location. Files pushed here are not sorted into albums, metadata can be lost, and repeated sync tasks can produce duplicates or unstable filenames. Use only for temporary transfers.

Selecting the Dataset and Organizing Files

Select a TrueNAS local dataset or create a new one to use as the source or destination.

Creating a Dataset

To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.

Select a dataset (root, parent, or child), then click Add Dataset.

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.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	Inherit
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.

If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.

Click Save.

Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.

For push tasks, organize files in the local dataset so they map to albums created by the TrueNAS cloud sync client.
For pull tasks, the Google Photos API only provides access to items in albums created by the sync client. Full-library pulls or shared albums are not accessible. Configure your dataset accordingly based on your chosen direction, mode, and target folder.

Creating the API Credentials

Tokens generated before March 31, 2025 do not provide full access to your Google Photos library under the new API rules.
When creating credentials, ensure that your OAuth client and token are intended for use with albums created by the TrueNAS cloud sync client. Only these app-created albums can be accessed for push or pull tasks.

On the Google API dashboard, click the dropdown menu to the right of the Google Cloud logo and select your project.

If you do not have a project, click NEW PROJECT and enter a value in Project name, Organization, and Location. Click Create.

Enable API

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.

Configure Authentication

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.

Figure 7: Enter Developer Contact Information

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.

Can I leave the app in testing mode?

You can leave the app in testing mode, but testing app credentials expire after seven days. Cloud sync tasks fail when testing mode credentials expire.

Create Credentials

Click Credentials on the left menu, then click + CREATE CREDENTIALS and select OAuth client ID.

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.

Configuring Rclone

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.

Figure 14: Configure rclone Client ID and Secret

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.

Adding Google Photos Cloud Credentials

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.

Creating the Cloud Sync Task

Go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.

Select the Google Photos backup credentials from the Credentials dropdown list.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the Direction as PUSH or PULL and select the Transfer Mode as SYNC, COPY, or MOVE. Select the Google Photos location to back up data to or from in Folder. Browse to and select the album folder or enter /album.
Note: Pull tasks only access albums created by the TrueNAS cloud sync client. Full-library pulls or shared albums are not accessible.
Select the local dataset in Directory/Files. This is the dataset sent to Google Photos for push tasks or the write destination for pull tasks.
Push tasks containing media files saved to the local dataset root level fail with the error: Failed to sync: can’t upload files here.
Save files to child directories, not to the root level of the TrueNAS dataset. Directories under the local dataset correspond to albums created by the TrueNAS cloud sync client in Google Photos.
Enter a Description for the cloud sync task.
Select the time to run the task from the Schedule options.
Click Save to add the task.

TrueNAS adds the task to the Cloud Sync Task widget with the status Pending, until the task runs on schedule.

Click Dry Run to test the task by connecting to Google Photos and simulating transferring a file. During a dry run, TrueNAS sends or receives no data. A dry run can report successful even for a task that fails to transfer data due to misconfiguration

Click the vertical ellipses more_vert on the task and select Run Job to start the cloud sync task immediately.

Troubleshooting

If a Google Photos cloud sync task fails, go to Data Protection and click the FAILED status in State on the Cloud Sync Tasks widget. Review the logged error messages. Common error messages for failed Google Photos tasks include:

Failed to copy: can't upload files here

Problem: A push task attempts to upload files to the root level / folder or the /upload folder.

Solution: Reconfigure the push task to target the /album folder and organize your files into child directories (albums). Directories under the local dataset correspond to albums the TrueNAS cloud sync client creates in Google Photos. Only albums the sync client creates are accessible to cloud sync tasks.

Pulling from the root directory is not allowed. Please, select a specific directory

Problem: A pull or push task targets the root level / folder.

Solution: Change the target folder to /album. Pull tasks transfer only media that exist in albums created by the TrueNAS cloud sync client. Full-library pulls and shared albums are not accessible via the API. Do not rely on /media/all for a full export.

Failed to copy: directory not found

Problem: A pull task targets the /upload folder.

Solution: The /upload folder functions as a temporary upload queue. rclone cannot pull from /upload. Change the target folder to /album and organize files accordingly. Remember that only albums created by the TrueNAS cloud sync client are accessible for pull tasks.

If a pull task runs but some or all files never appear in the local dataset, those files are not in albums created by the TrueNAS cloud sync client and the API does not expose them to the sync client. To get originals from Google Photos you can:

Export your account via Google Takeout (download the archive and import the files into TrueNAS).
Download desired photos directly from Google Photos and copy them into your TrueNAS dataset.

If you want the sync client to manage media going forward, create and sync albums via TrueNAS. Those albums then remain accessible to the TrueNAS cloud sync client.

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:

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 more_vert opens a dropdown menu with five options for various functions for each task:

edit Edit opens the Edit Cloud Sync Task screen populated with with the settings for that task.
play_circle_filled Run Now starts the cloud sync, running it outside of the scheduled time.
loop 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 Restore creates a new cloud sync task from an existing task. The new task has the same settings but reverses the data transfer.
delete 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.

Cloud Sync Task Screen

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.

Cloudsync Task Wizard

The Cloud Sync Task wizard screens simplify the task creation process. The wizard has two screens, Provider and What and When.

Provider Wizard Screen

The Provider wizard screen allows you to 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.

Figure 5: Cloudsync Task Wizard Provider Screen

Add New opens the Cloud Credentials screen. The same configuration screen opens when you click Add on the Credentials > Backup Credentials screen.

Advanced Options opens a screen with the same settings as the Edit Cloud Sync Task screen.

Verify Credentials tests the settings before you advance to the settings on the What and When wizard screen.

What and When Wizard Screen

The What and When screen sets the direction (push or pull), transfer mode (move, copy, or sync), 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 and Edit Cloud Sync Task Screens

Advanced Options accessed from the Cloudsync Task Wizard and Edit Cloud Sync Task show the same settings, and settings are grouped into Transfer, Remote, Control, and Advanced Options.

Manage Credentials opens the Backup Credentials screen.

Transfer Settings

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.

Figure 7: Add Cloud Sync Task Remote Settings

Browsing to select a path

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: COPY - Select to copy files from the source to the destination. Files that are identical on source and destination (same size and modification time) are skipped. If files differ, the destination version is overwritten. MOVE - Select to transfer files from the source to the destination and delete source files. Copies files from the source to the destination and then deletes them from the source. Files with the same names on the destination are overwritten. SYNC - Select to change files on the destination to match those on the source. If a file does not exist on the source, it is also deleted from the destination.
Directory/Files	Enter or browse to select the source or receiving dataset or folder. Click the arrow_right arrow to the left of /mnt folder to expand and show datasets and directories within that folder. After selecting the dataset or directory location (source) to send to the cloud for push syncs, or as the destination to write to for pull syncs. Be cautious with pull destinations to avoid overwriting existing files. Click the arrow_right arrow to the left of /mnt folder again to collapse the directory tree. Note: Clear the checkmark to the left of /mnt. Not clearing this checkmark can result in an All selected directories must be at the same level error message.

Remote Settings

The Remote settings specify the cloud sync provider and destination storage locations. The option selected in Credential changes settings in the Remote settings area. The Manage Credentials link opens the Backup Credentials screen, where you can add a new provider credential.

Settings	Description
Credential	Defines which preconfigured cloud storage account participates in this task. A Bucket setting displays after selecting a credential that uses S3, like Amazon S3. TrueNAS automatically validates the selected credential.
Bucket	Sets the pre-defined bucket to use. For Storj-iX credentials, select Add New to open the Add Bucket screen and create a new bucket on your Storj account from the TrueNAS UI.
Folder	Enter or browse to select the dataset. Click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task.

Add Bucket Screen

The Add Bucket screen opens when Add New is selected from the Bucket dropdown in Remote Settings. It is only available for Storj-iX provider credentials.

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

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.

Schedule Presets

The Schedule dropdown list preset options are:

Hourly at the start of each hour
Daily At 00:00 (12:00 AM)
Weekly On Sundays at 00:00 (12:00 AM)
Monthly On the first day of the month at 00:00 (12:00 AM)
Create Custom schedule that opens the Advanced Scheduler window.

Advanced Scheduler

Choosing a Presets option populates the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

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 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 N^th 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

Advanced Options settings are for advanced users. Selecting Push in Direction adds the Use Snapshot option.

Figure 10: Add Cloud Sync Task Control and Advanced Options

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). See rclone filtering for more details about the `--exclude` option.

Advanced Remote Options

The Advanced Remote Options settings are for advanced users to configure remote encryption (if selected), transfer bandwidth speed, and bandwidth limit. The Edit Cloud Sync Task screen Advanced Remote Options screen has an additional setting not found on the Add Cloud Sync Task screen.

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: Provides instructions on creating periodic snapshot tasks in TrueNAS.

Periodic Snapshot Tasks Screens: Provides information on the Data Protection and Periodic Snapshot Task screens and settings.

Adding Periodic Snapshot Tasks

Periodic snapshot tasks allow you to schedule creating read-only versions of pools and datasets at a given point in time. You can also access VMWare snapshot integration and TrueNAS storage snapshots from the Periodic Snapshot Tasks widget.

How should I use snapshots?

Snapshots do not make copies of the data so creating one is quick and if little data changed, they take very little space. It is common to take frequent snapshots as soon as every 15 minutes, even for large and active pools. A snapshot where no files changed takes no storage space, but as files changes happen, the snapshot size changes to reflect the size of the changes. In the same way as all pool data, after deleting the last reference to the data you recover the space.

Snapshots keep a history of files, providing a way to recover an older copy or even a deleted file. For this reason, many administrators take snapshots often, store them for a period of time, and store them on another system, typically using the Replication Tasks function. Such a strategy allows the administrator to roll the system back to a specific point in time. If there is a catastrophic loss, an off-site snapshot can restore data up to the time of the last snapshot.

Creating a Periodic Snapshot Task

Create the required datasets or zvols before creating a snapshot task.

Go to Data Protection > Periodic Snapshot Tasks and click Add.

AddPeriodicSnapshotTaskScreen

First, choose the dataset (or zvol) to schedule as a regular backup with snapshots, and how long to store the snapshots.

Next, define the task Schedule. If you need a specific schedule, choose Custom and use the Advanced Scheduler section below.

Configure the remaining options for your use case. For help with naming schema and lifetime settings refer to the sections below.

Click Save to save this task and add it to the list in Data Protection > Periodic Snapshot Tasks.

You can find any snapshots taken using this task in Storage > Snapshots.

To check the log for a saved snapshot schedule, go to Data Protection > Periodic Snapshot Tasks and click on the task. The Edit Periodic Snapshot Tasks screen displays where you can modify any settings for the task.

Using the Advanced Scheduler

Advanced Scheduler

Choosing a Presets option populates in the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

An asterisk (*) means match all values.

You can set specific time ranges by entering hyphenated number values. For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.

You can also enter lists of values. Enter individual values separated by a comma (,). For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).

A slash (/) designates a step value. For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.

Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.

TrueNAS has an option to select which Months the task runs. Leaving each month unset is the same as selecting every month.

The Days of Week schedules the task to run on specific days in addition to any listed days. For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.

The Schedule Preview displays when the current settings mean the task runs.

Examples of CRON syntax

Syntax	Meaning	Examples
*	Every item.	* (minutes) = every minute of the hour. * (days) = every day.
*/N	Every N^th 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.

Using Naming Schemas

The Naming Schema determines how automated snapshot names generate. A valid schema requires the %Y (year), %m (month), %d (day), %H (hour), and %M (minute) time strings, but you can add more identifiers to the schema too, using any identifiers from the Python strptime function.

For Periodic Snapshot Tasks used to set up a replication task with the Replication Task function:
You can use custom naming schema for full backup replication tasks. If you are going to use the snapshot for an incremental replication task, use the default naming schema.

This uses some letters differently from POSIX (Unix) time functions. For example, including %z (time zone) ensures that snapshots do not have naming conflicts when daylight time starts and ends, and %S (second) adds finer time granularity.

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.

Setting Snapshot Lifetimes

A snapshot lifetime value defines how long the snapshot schedule ignores that snapshot when it looks for obsolete snapshots to remove. For example, defining a lifetime of two weeks on a snapshot created after a weekly snapshot schedule runs can result in that snapshot actually being deleted three weeks later. This is because the snapshot has a timestamp and defined lifetime that preserves the snapshot until the next time the scheduled snapshot task runs.

TrueNAS also preserves snapshots when at least one periodic task requires it. For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for 3 years. Each has an hourly snapshot taken. After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task. These snapshots get destroyed at the end of 3 years.

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.

Periodic Snapshot Task Widget without Task

Periodic Snapshot Task Widget with Tasks

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 more_vert at the right of the task on the Periodic Task Widget opens a dropdown menu with two task options: Edit and Delete.

The delete 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.

Logs Window

PeriodicSnapshotTaskLog

Download Logs saves a copy of the current task logs.

Periodic Snapshot Task Screen

Periodic snapshot tasks show on both the Periodic Snapshot Task widget on the Data Protection screen and the Periodic Snapshot Tasks screen.

DataProtectionPeriodicSnapshotTasksList

Add opens the Add Periodic Snapshot Task screen.

DataProtectPeriodicSnapshotTasksDetailsNoTasks

The Columns dropdown list shows options to customize the list view. Options are Select All, Recursive, Naming Schema, When, Frequency, Next Run, Keep snapshot for, VMWare Sync, Enabled, State, and Reset to Defaults.

State shows the current state of the task.

The expand_more expand shows the details for the selected task.

DataProtectionPeriodicSnapshotTasksDetails

Edit opens the Edit Periodic Snapshot Task screen.

Delete opens the delete dialog that removes the task from the system.

Add and Edit Periodic Snapshot Screens

The Add Periodic Snapshot Task and Edit Periodic Snapshot Task show the same settings.

Dataset Options

Dataset settings show on both the add and edit configuration screens.

AddPeriodicSnapshotTaskScreen

Dataset Settings

Setting	Description
Dataset	Sets the pool, dataset, or zvol you want to take a snapshot of.
Exclude	Excludes specific child datasets from the snapshot. Use with recursive snapshots. List paths to any child datasets to exclude. Example: `pool1/dataset1/child1`. A recursive snapshot of pool1/dataset1 includes all child datasets except child1. Separate entries by pressing `Enter`.
Recursive	Sets the task to take separate snapshots of the dataset and each of its child datasets. Leave the checkbox clear to take a single snapshot only of the specified dataset without child datasets.

Schedule Settings

Schedule settings show on both the add and edit configuration screens.

Setting	Description
Snapshot Lifetime	Sets the length of time to retain a snapshot on this system. Enter a numeric value and a single lowercase letter for units. Examples: 3h is three hours, 1m is one month, and 1y is one year. Does not accept minute values. After the time expires, the snapshot is removed during the next snapshot scheduled execution finds 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.

Schedule Presets

The Schedule dropdown list preset options are:

Hourly at the start of each hour
Daily At 00:00 (12:00 AM)
Weekly On Sundays at 00:00 (12:00 AM)
Monthly On the first day of the month at 00:00 (12:00 AM)
Create Custom schedule that opens the Advanced Scheduler window.

Advanced Scheduler

Choosing a Presets option populates the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

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 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 N^th 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: Provides instructions on adding rsync tasks with two methods, SSH connection and module.

Rsync Tasks Screens: Provides information on the Rsync Tasks screens and settings.

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.

Before You Configure the Rsync Mode

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 user’s home directory
SSH connection from 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.
Figure 1: Name and Method Settings
Enter the authentication settings.
Figure 2: 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.
Figure 3: More Options Settings
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 for the new keypair on the SSH Keypairs widget. To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.

TrueNAS allows configuring multiple admin users on the system. All admin users configured in the TrueNAS system show in the rsync task User dropdown list.

Adding an Rsync Task Using SSH

Enable SSH on both the local host TrueNAS and the remote destination system.

You can use the SSH connection created in Using an SSH Connection or create a new connection while configuring the rsync task.

Go to Data Protection and click Add on the Rsync Tasks card to open the Add Rsync Task screen.
Figure 4: Add Rsync Task - SSH Mode
Enter or browse to the dataset or folder to sync with the remote server. Use the arrow_right to the left of the /mnt folder and each folder listed on the tree to expand and browse through, then click on the name to populate the Path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 5: File Explorer Folder Icons
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 and 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, then select the connection method from the Connect using dropdown list. The setting fields for the selected connection type show.
If selecting SSH private key stored in user’s home directory, the user selected in User must already have an SSH private key saved in their home directory.
If selecting SSH connection from the keychain, choose an existing SSH connection 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 displays a message describing the problem so you can correct it.
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.

Figure 6: Add Rsync Task Schedule and More Options

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.

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 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 N^th 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 card.

To run the rsync task at any time, select it on the Rsync Tasks card, click more_vert for the task, and select Run Now.

Using an SSH Connection

The TrueNAS UI allows users to select an existing SSH connection or to create a new connection while configuring the task. The New SSH Connection screen opened using the Add New option in the rsync task and accessed while on the Backup Credentials screen are essentially the same and show the same setting options.

To set up a new SSH connection before adding an rsync task, go to Credentials > Backup Credentials and click Add on the SSH Connections card. 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 from 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.
Figure 7: Name and Method Settings
Enter the authentication settings.
Figure 8: 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.
Figure 9: More Options Settings
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.

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.
Figure 10: Manual Name and Method
Enter the authentication settings.
Figure 11: Manual 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.
Figure 12: Manual More Options
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. Go to Credentials > Users, click Edit, and paste the key into the SSH public key field.

After adding the SSH connection, go to System > Services to turn on the SSH service. For security hardening, do not leave the SSH service turned on when it is not in use. Turn it on before the rsync task is scheduled to run, then turn it off again after the task completes. (Optional) To start the SSH service automatically after each system restart, enable that option in the SSH service settings. Enable the SSH service on the remote system following the configuration process for that system.

Setting Up an Rsync Task Using Module Mode

Before you create an rsync task in module mode, you must define at least one module per rsyncd.conf(5) on the remote rsync server. The Rsync Daemon application is available in situations where configuring TrueNAS as an rsync server with an rsync module is necessary.

After configuring the remote server with rsync and a module, configure the rsync task in TrueNAS.

Setting Up an Rsync Module

If the non-TrueNAS remote server includes an rsync service, make sure it is turned on. To configure a module on the remote server:

Create a dataset. Write down the host and path to the data on the remote system you plan to sync with.
Create an rsync module.
If the remote system is not a TrueNAS and has an rsync app installed, create a module according to the configuration process for that app and system. If the remote system is not a TrueNAS, install an rsync app, such as Rsyncd, and configure it per the instructions for the app and your remote non-TrueNAS system.
If the remote system is another TrueNAS, install an rsync app. Debian-based TrueNAS systems include the Rsync Daemon app in the Community app catalog. Install the app and use it to configure a module.
Configuring a module in the TrueNAS RsyncD app
To create the module, you need the IP address or host name of your TrueNAS (host) server. The host server is configured with the rsync task that transfers your data to the remote server.
When the remote system is a Debian-based TrueNAS system, go to Apps > Discover Apps and search for the Rsync Daemon app.
Click on the card, and then click Install to open the installation wizard.
To add a module, click Add to the right of Rsync Modules, then:
1. Assign a name. This name is added in the Add Rsync Task screen on your TrueNAS system when you set up a task using Module in the Rsync Mode field.
2. (Optional) Enter a comment to help you remember the purpose of this module or where it is used.
3. Select the host path for the rsyncd app. You can use Create Dataset to add a new dataset, and repeat to add a new child dataset if not selecting an existing dataset.
4. Set the level of access by selecting the option on the Access Mode dropdown list.
5. (Optional) Add IP addresses to the Host Allow or Host Deny options if you want to narrow access to this module.
6. Take note of the name of the module and its host path to use later when you add the rsync task in your TrueNAS system.
Complete the rest of the app configuration to suit your use case, and click Install. The app shows in the TrueNAS UI on the Applications screen as Running when fully deployed.

Adding an Rsync Task Using Module Mode

To configure the rsync task using module mode, you need:

The name of the module
The IP address or host name for the remote server
The path to the dataset

Go to Data Protection and click Add on the Rsync Tasks card to open the Add Rsync Task screen.
Figure 13: Add Rsync Task - Module Mode
Enter or browse to and select the dataset or folder to sync with the remote server. Clicking on the dataset name populates the Path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 14: File Explorer Folder Icons
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 and 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.

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 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 N^th 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 to enable the task. Clear the checkbox to disable the task without deleting the configuration.
Click Save.

To run the rsync task at any time, select it on the Rsync Tasks card, click more_vert for the task, and select Run Now.

Rsync Tasks Screens

The Rsync Task card 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.

Rsync Task Card

The Rsync Tasks card shows a description of rsync tasks until the first task is configured. After that, it shows a list of the tasks configured on the system, with details about each task and the task status.

The card header opens the Rsync Task screen.

Add opens the Add Rsync Task screen.

The vertical ellipses more_vert icon to the right of each task opens a dropdown menu with three options for various functions:

edit Edit opens the Edit Rsync Task screen populated with with the settings for that task.
The Run job starts the rsync operation, running it outside of the scheduled time.
delete Delete opens a confirmation dialog.

State displays the status of the rsync 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.

Rsync Task Screen

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 more_vert icon to the right of each task opens a dropdown menu with three options for various functions:

edit Edit opens the Edit Rsync Task screen populated with with the settings for that task.
The Run job starts the rsync operation, running it outside of the scheduled time.
delete Delete opens a confirmation dialog.

Add opens the Add Rsync Task screen.

Add and Edit Rsync Task Screens

The Add Rsync Task and Edit Rsync Task screens show the same settings. The sections below group settings by functional area.

Local and Remote Options

Local settings specify the location of the data on the TrueNAS system to sync, the user that performs the task, and the direction of the transfer (send or receive data). The Remote settings specify the mode for the task and the remote host connection information. Settings change based on the option (Module or SSH) set in Rsync Mode.

Figure 3: Rsync Task Local and Remote Module Settings

Figure 4: Rsync Task Local and Remote SSH Settings

Browsing to select a path

Local and Remote Settings

Setting	Description
Path	(Required) Enter or browse to the dataset or directory on the TrueNAS system to sync. Use the arrow_right to the left of the /mnt folder to expand the folder tree, then click on the name to select and populate the Path field. Linux file path limits apply. Other operating systems can have different limits, which might affect how to use them as sources or destinations.
User	(Required) Select the user to run the rsync task. The user must have permission to write to the destination directory: the directory on the remote host for a Push, or the local dataset for a Pull. If setting Rsync Mode to SSH, the user must have an SSH private key in their home directory when Connect using is set to SSH private key stored in user’s home directory.
Direction	(Required) Select the direction of the flow of data to or from the remote host. Options are: Push - Copies data from the local TrueNAS system to the remote system. Pull - Copies data from the remote system to the local TrueNAS system.
Description	(Optional) Enter a description of the rsync task.
Rsync Mode	Select the mode from the dropdown list. Options are: Module - Uses a custom-defined remote module from the rsync server. SSH - Uses an SSH configuration for the rsync task. The remote system must have SSH enabled. The local system needs an established SSH connection to the remote system for the rsync task. SSH displays more settings.
Remote Host	(Required) Enter the IP address or host name and domain of the remote system. Use the format `username@remote_host` if the user name differs on the remote host.
Remote Module Name	(Required) If Rsync Mode is set to Module, specify the name of the module on the remote rsync server. Define at least one module per rsyncd.conf(5) on the remote rsync server. Enter the Module Name exactly as it appears on the remote system.
Connect using	(Required) When Rsync Mode is set to SSH, shows two options: SSH private key stored in user’s home directory - The user entered in User must have an SSH private key added and stored in the home directory for the user. Create the SSH connection and key pair, download the keys, then add the private key to the user in the UI and to the home directory either from the Shell using Linux CLI commands or while in an SSH session with the system. SSH connection from the keychain - Requires creating an SSH connection and key pair before setting up the rsync task. Shows the SSH Connection dropdown list of SSH connections configured in the system.
SSH Keyscan	Shows when Rsync Mode is set to SSH, Connect using is set to SSH private key stored in user’s home directory, and a Remote Host is entered. Select to retrieve the remote host SSH key and store it on the local system. This lets the local system verify the remote host identity when it connects.
SSH Connection	Shows when Rsync Mode is set to SSH and Connect using is set to SSH connection from the keychain. Shows a dropdown list of SSH connections added in TrueNAS. Sets the rsync task to use the selected SSH connection to authenticate sync operations with the remote server.
Remote SSH Port	(Required) If Rsync Mode is set to SSH, enter the SSH port number of the remote system. By default, 22 is reserved in TrueNAS.
Remote Path	Enter an existing path on the remote host. Maximum path length is 255 bytes.
Validate Remote Path	Shows when Rsync Mode is set to SSH. Set to test the remote server connection and verify that the defined Remote Path exists.

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 and More Options

Schedule defines when the remote sync task occurs. The More Options specify other settings related to when and how the rsync occurs.

Figure 6: Rsync Task Schedule and Other Options Settings

Schedule Settings

Setting	Description
Schedule	Shows a list of schedule preset options. See Schedule Presets below for more info.
Recursive	Select to include all subdirectories of the specified directory. When cleared, only the specified directory is included.
Enabled	Select to enable this rsync task. Clear to disable this rsync task without deleting it.

Schedule Presets

The Schedule dropdown list preset options are:

Hourly at the start of each hour
Daily At 00:00 (12:00 AM)
Weekly On Sundays at 00:00 (12:00 AM)
Monthly On the first day of the month at 00:00 (12:00 AM)
Create Custom schedule that opens 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.

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 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 N^th 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.

More Options Settings

Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.

Setting	Description
Times	Select to preserve modification times of files.
Compress	Select to reduce the size of data to transmit. Recommended for slow connections.
Archive	Select to preserve symlinks, permissions, modification times, group, and special files. When selected, rsync runs recursively. When run as root, owner, device files, and special files are also preserved. Equal to passing the flags `-rlptgoD` to rsync.
Delete	Select to delete files in the destination directory that do not exist in the source directory. The destination is the remote system for a Push and the local system for a Pull.
Quiet	Select to suppress informational messages from the remote server.
Preserve Permissions	Select to preserve original file permissions. Useful when the user is set to root.
Preserve Extended Attributes	Select to preserve extended attributes, but this must be supported by both systems.
Delay Updates	Select to save a temporary file from each updated file to a holding directory until the end of the transfer. All transferred files are renamed after the transfer is complete.
Auxiliary Parameters	Enter additional rsync(1) options to include. Separate entries by pressing `Enter`. Note: Escape the `` character with a backslash (`\.txt`) or place it inside single quotes (`'*.txt'`).

Replication Tasks

TrueNAS replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their TrueNAS system as a way to back up stored data. When properly configured and scheduled, replication takes regular snapshots of storage pools or datasets and saves them in the destination location either on the same system or a different system.

Setting Up a Simple Replication Task Overview

Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication. Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication. Both local and remote replication can involve encrypted pools or datasets.

The sections below provide overviews on what to do before you begin configuring a replication task.

Before You Begin Local Replication

Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions. Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.

Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots). TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up. TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task. You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard. Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens. Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.

Before You Begin Remote Replication

Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks. Setting options change based on the source and destination selections.

When setting up remote replication:

Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen. After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems. The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Figure 1: Adding A Home Directory
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: Provides instructions on adding a replication task using different pools or datasets on the same TrueNAS system.

Setting Up a Remote Replication Task: Provides instructions on adding a replication task with a remote system.

Replication Task Screens: Provides information on the Replication screens, wizard, and settings used to add or edit replication tasks.

Advanced Replication Tasks: Instructions to configure advanced ZFS snapshot replication tasks in TrueNAS.

Configuring Advanced Replication Tasks: Instructions to configure advanced ZFS snapshot replication tasks in TrueNAS.
Setting Up an Encrypted Replication Task: Provides instructions on adding a replication task to a remote system and using encryption.
Unlocking a Replication Encrypted Dataset or Zvol: Provides information on three methods of unlocking replicated encrypted datasets or zvols without a passphrase.

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.

Before You Begin Local Replication

Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots). TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up. TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task. You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard. Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens. Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.

To configure the local replication task, follow the instructions in the section below.

Configuring a Local Replication Task

Use the Replication Task Wizard to create and copy ZFS snapshots to another system, which streamlines creating simple replication tasks. After creating the replication task, TrueNAS automatically creates a periodic snapshot task for sources that have no existing snapshots.

If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list. This loads the configuration settings for that task into the wizard, where you can make changes such as assigning it a different destination, setting a new schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task originally loaded into the wizard. This saves some time when creating multiple replication tasks between the same two systems.

Before you begin configuring the replication task, first verify that the destination dataset where you plan to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.

After completing the basic preparation steps in the section above, go to Data Protection > Replication and click Add to open the replication wizard. To configure advanced settings, click Advanced Replication Creation to open the Add Replication Task screen before you enter any settings in the wizard. Refer to the Advanced Replication Tasks for configuration instructions using the Add Replication Task screen.

On the What and Where replication wizard screen:

Select an existing replication task from the Load Previous Replication Task dropdown. If one does not exist, leave this set to the default, which is the double dashes.
Select the source and destination locations. You can select these in any order. Local replication sends or receives data from one storage location to another on the same (local) system. Remote replication sends data to or receives data from a storage location on a different (remote) TruNAS system.
To set up a local replication in the replication wizard, set both Source Location and Destination Location to On this System.
To set up a push remote replication in the replication wizard, set the Source Location to On this System and set Destination Location to On a Different System. To set up a pull remote replication in the replication wizard, set the Source location to On a Different System and the Destination Location to On this System.
Setting either source or destination to On a Different System automatically sets the other to On This System. You cannot set both to On a Different System.
Click on Source Location or Destination Location to show additional setting options and the file browser. Additional settings shown are based on the selection.

Configure the settings for local replication after selecting On This System in either Source Location or Destination Location.
Figure 1: New Local Replication Task
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 2: File Explorer Folder Icons
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.
Figure 3: Set Replication Task Schedule
Select the destination and source snapshot retention options. The Destination Snapshot Lifetime option specifies 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.
The Source Snapshot Lifetime sets how long Truenas should store snapshots on the source system before TrueNAS deletes it. Set the duration and select the unit of time. The default retention period is two weeks.
Click Save.

The task shows on the Replication Task widget with the status as PENDING.

Figure 4: Replication Task in Pending State

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.

Figure 5: Snapshot List in Destination Dataset

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.

Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.

Before You Begin Remote Replication

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.
Figure 1: Adding A Home Directory
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials. The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task. If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair. You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential. Add a new credential to the remote system if one does not exist, and then edit it to see the public key. Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit. Verify the account configuration has SSH Access selected. If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon. Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.

To configure the remote replication task, follow the instructions in the section below.

Creating a Remote Replication Task

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.

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.
Figure 2: Set Source and Destination for Remote
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.
Figure 3: File Explorer Folder Icons
a. Select an existing SSH connection from the dropdown list or select Add New to open the New SSH Connection screen. If you created the SSH connection in the section above, select it.
When adding a new connection in the wizard, if TrueNAS detects other configuration issues, such as the user not correctly set up, an error indicating what the issue is shows in the wizard. Exit the replication wizard to correct issues, then return to the wizard to begin the task configuration again.
After completing the replication wizard task creation, where you added a new SSH connection in the wizard, return to the remote system user configuration to add the new public key for the SSH connection to the admin user configuration.
b. Use the file browser to browse and select the parent dataset with the data to replicate. Clicking on the dataset(s) populates the path.
When setting up the Source, you can select multiple sources or manually type the names into the Source field.
When setting up the Destination, the Destination path allows adding a directory/dataset by entering /name, where rname is the name of a directory or dataset. The source path does not allow adding a new dataset/directory. You cannot use zvols as a remote replication destination. Add a name to the end of the path to create a new dataset in that location.
c. Select Use Sudo for ZFS Commands. A dialog opens prompting you to add this capability. Selecting this removes the need to issue the cli zfs allow command in Shell on the remote system. Click Use Sudo for ZFS Commands. If the dialog closes before clicking this option, you can select this option on the wizard screen.
Figure 4: Select Use Sudo for ZFS Commands
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.
Figure 5: Set Replication Task Schedule
Select the destination and source snapshot retention options. The Destination Snapshot Lifetime option specifies 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.
The Source Snapshot Lifetime sets how long Truenas should store snapshots on the source system before TrueNAS deletes it. Set the duration and select the unit of time. The default retention period is two 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.

For information on replicating encrypted pools or datasets, see Setting Up an Encrypted Replication Task.

Configuring a New SSH Connection

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.
Figure 8: 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.

Using SSH Transfer Security

We always recommend using encryption for SSH transfer security.

In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer. However, the data is completely unprotected from eavesdropping.

Choosing No Encryption for the task is less secure but faster. This method uses common port settings but you can override these when using the Advanced Replication Creation options or by editing the task after creating it in the wizard.

Figure 9: Replication Security and Task Name

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 more_vert to the right of each task opens a dropdown menu of options:

edit Edit icon opens the Edit Replication Task screen.
play_arrow Run Now Run job opens a dialog.
restore Restore Restore to opens the Restore Replication Task window.
delete 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.

Replication Tasks Screen

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.

Replication Task Details

The details view of each replication task shows the Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, and Auto settings.

play_arrow Run Now opens a Run Now dialog.

restore Restore opens the Restore Replication Task window.

edit Edit opens the Edit Replication Task screen.

delete Delete opens a delete confirmation dialog.

Run Now Dialog

play_arrow Run Now opens the Run Now dialog.

Continue starts the replication task.

Restore Window

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.

Download Encryption Keys

When a replication task involves a key-encrypted source or destination, the icon shows in the task options. This downloads any encryption keys to your local system.

Delete Dialog

The Delete confirmation dialog shows the task name with both source and destination information.

Confirm activates Delete.

Delete removes the task from the system.

Add Replication Task Options

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:

Encryption
Also include snapshots with the name
Schedule

Add opens the wizard.

Replication Task Wizard

The wizard has two screens:

What and Where settings specify the task name, data source, and destinations, the type of replication (local or remote), transport options (SSH connection), schema or regular expression that names the snapshot created by the task, and, 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.

What and Where Wizard Screen

The What and Where screen shows settings for both the source and destination information (path to the dataset), the source and destination transfer direction, encryption settings for the data transfer, remote replication SSH connections, naming schema to apply to the snapshot taken through the replication task, and the name for the task.

The Encryption and SSH Connection options show when the source or destination is set to On a Different System. Encryption applies another layer of protection to the data transfer; it is not the encryption of the data stored or the dataset. You can use an existing SSH connection created using the Credentials > Backup Credentials > SSH Connection screen or create a new connection through the replication task wizard or screens. SeeConfigure SSH for more information on adding a Backup Credential SSH credentials.

Settings 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.

Browsing to select a path

Also include snapshots with the name options show different snapshot settings based on the naming option selected.

Figure 7: Replication Task Wizard What and When

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.

Figure 8: Replication Task Wizard What and When All Settings

What and Where Settings

Setting	Description
Load Previous Replication Task	Shows a list of previous replication tasks that, when selected, load settings from the saved replication task. Select an existing snapshot to populate the Source Location, Destination Locations, Source, and Destination fields. Also populates Task Name with a name that is a combination of the source and destination for the selected task.
Source Location	Shows the storage location of the original replicated snapshots. Options: On this System (local replication) - Allows setting On a Different System to a local or remote destination. On a Different System (remote replication) - When set to On a Different System, the Destination Location automatically changes to On this System and the Destination field displays the path to the snapshot location. For more information on these setting options, see Source Location Setting Options.
Source	(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Location	Select the storage location for the replicated snapshots. Options are On this System or On a Different System, but if Source is set to On a Different System, the Destination Location automatically changes to On this System, and the Destination field displays.
Destination	(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Destination field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
SSH Connection	Shows a list of existing SSH connections saved on the system and the option to add a new SSH connection. Select an existing SSH connection to a remote system or select Create New to open the New SSH Connection window to configure a new SSH connection to a remote system. Shows the Use Sudo for ZFS Commands dialog to enable sudo for SSH sessions.
Use Sudo For Zfs Commands	Select if setting up remote replication tasks when logged in as an admin user.
Recursive	Select to also replicate all snapshots contained within the selected source dataset snapshots. Leave clear to only replicate the selected dataset snapshots.
Replicate Custom Snapshots	Shows after setting Source Location to On this System. Select to replicate snapshots that are not created by an automated snapshot task. After selecting, it shows the Also include snapshots with the name setting options. This setting requires setting a naming schema for the custom snapshots through one of the two methods: Naming Schema or Snapshot Name Regular Expression.
Also include snapshots with the name	Select the option to set the snapshot naming pattern as either a naming schema or regular expression. Options: Naming Schema and Snapshot Name Regular Expression.
Naming Schema	Shows after selecting Naming Schema under Also include snapshots with the name. Enter the pattern of naming custom snapshots to replicate. Enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Naming schema must include %Y, %m, %d, %H and %M. Separate entries by pressing `Enter`. The number of snapshots matching the patterns displayed on the screen.
Snapshot Name Regular Expression	Shows after selecting Snapshot Name Regular Expression under Also include snapshots with the name. Enter the regular expression that the replicated snapshot(s) should match. This option replicates all snapshots with names matching the specified regular expression. Performance on systems with large numbers of snapshots is lower as this process reads snapshot metadata to determine snapshot creation order. Naming of regular expressions include name followed this pattern, `auto-[0-9-]+\|manual-[0-9]+`.
SSH Transfer Security	Shows after selecting Replicate Custom Snapshots. Applies data transfer security. Shows two options: Encryption (more secure, but slower) and No Encryption (less secure, but faster). The connection is authenticated with SSH. Encryption is recommended, but can be disabled for increased speed on secure networks.
Encryption	Select to apply an extra layer of encryption on the data transfer when replicating data. For more information on all options, see Encryption below.
Task Name	Shows the name the system adds from the source and destination options or enter a different name for this replication configuration to overwrite the automatically populated task name. By default, the system populates Task Name with the source-destination names selected or loaded by selecting a task in Load Previous Replication Tasks. The system prompts you to change the name if a task uses the name. Changing the name can be as simple as adding an iteration number, such as 2 or 3, to the default name.

Encryption Options

The Encryption option shows additional settings on the Add Replication Task screen and the What and Where wizard screen below the Destination settings.

Figure 9: Add Replication Task Wizard Hex Encryption

Encryption Settings

Setting	Description
Encryption	Select to apply an extra layer of encryption when replicating data to a remote server. Shows additional encryption settings Encryption Key Format and Store Encryption key in Sending TrueNAS database options.
Inherit Encryption	Select for the target dataset to inherit encryption from its parent dataset.
Encryption Key Format	Select the encryption option from the dropdown list. Hex (base 16 numeral) or Passphrase (alphanumeric) style encryption key. Selecting Hex displays the Generate Encryption Key option. Selecting Passphrase displays the Passphrase option.
Generate Encryption Key	Displays after selecting Hex in Encryption Key Format. Selected by default. Clearing the checkbox displays the Encryption Key field.
Encryption Key	Displays after clearing the Generate Encryption key checkbox. Use to import a custom hex key.
Passphrase	Displays when Encryption Key Format is set to Passphrase. Enter the alphanumeric passphrase to use as an encryption key.
Store Encryption key in Sending TrueNAS database	Displays after selecting Encryption. Selected by default. Select to store the encryption key in the TrueNAS database. Clearing the checkbox displays the Encryption Key Location in Target System field.
Encryption Key Location in Target System	Displays after clearing the Store Encryption key in sending TrueNAS database checkbox. Enter a temporary location for the encryption key that decrypts replicated data.

New SSH Connection

The New SSH Connection window opens after selecting Create New in the SSH Connection field. It allows you to set up a new SSH connection for the remote system.

New SSH Connection Settings

Setting	Description
Name	(Required) Enter a unique name for this SSH connection.
Setup Method	Select how to configure the connection from the dropdown list. Options: Manual - Select to configure authentication on the remote system. This option can include copying SSH keys and modifying the root user account on that system. Semi-Automatic - Select when configuring an SSH connection with a remote TrueNAS system. This method uses the URL and login credentials of the remote system to connect with and exchange SSH keys. This option only works when the other system is a TrueNAS system.
TrueNAS URL	(Required) Ener the host name or IP address of the remote system. A valid URL scheme is required. For example, https://10.235.12.20.
Admin Username	(Required) Enter the user name for logging into the remote system via the UI.
Admin Password	(Required) Enter the password for logging into the remote system.
One-Time Password (if necessary)	Enter the one-time password if two-factor authentication is enabled.
Username	(Required) Enter the user name for logging into the remote system via SSH.
Private Key	(Required) Select a saved SSH keypair or Generate New to create a new keypair to use for this connection.
Connect Timeout	Enter the time (in seconds) before the system stops attempting to establish a connection with the remote system.

When Wizard Screen

The When wizard screen sets the schedule for running the task and the retention period for keeping replicated snapshots. Replication Schedule and Destination Snapshot Lifetime options change the setting displayed on the screen.

Replication Schedule Options

The Replication Schedule options set when to run the task based on the schedule defined in Schedule or to run it one time.

Figure 11: Add Replication Task When Run on Schedule

Replication Schedule Settings

Setting	Description
Run On a Schedule	Displays the Schedule option where you select a preset time or select Custom to use the advanced scheduler.
Run Once	Runs the replication task after you click Start Replication. Displays the Make Destination Dataset Read-only? option. Removes the Schedule option.
Schedule	Displays after selecting the Run On a Schedule radio button. Shows a list of schedule preset options. See Schedule Preset Options below for more info.
Make Destination Dataset Read-only?	Displays after selecting the Run Once radio button. Select to change the destination dataset to be read-only. To continue using the default or existing dataset read permissions, leave this checkbox cleared.

Snapshot Lifetimes

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.

Source Snapshot Lifetime specifies how long TrueNAS retains a source snapshot before TrueNAS deleteds it. The default lifetime is two weeks. Unit sets the time measure, such as hours, days, weeks, etc. The digit entered in the other time field sets the number of units.

Destination Snapshot Lifetime specifies how long TrueNAS retains a replicated snapshot in the dataset on the destination server.

Destination Snapshot Lifetime Settings

Setting	Description
Same as Source	Uses the configured snapshot lifetime value from the source dataset periodic snapshot task.
Never Delete	Never deletes snapshots from the destination system.
Custom	Defines how long the snapshot remains on the destination system. Shows the number-of and measure-of-time fields to set the schedule.
Number-of	Enter a numeric value to work with the measure of time selection to set the custom lifetime of the snapshot.
Measure-of-time	Select the option for Hours, Days, Weeks, Months, or Years to work with the number-of field to set the custom lifetime of the snapshot.

Add and Edit Replication Task Screens

Advanced Replication Creation opens the Add Replication Task screen.

The Edit icon button opens the Edit Replication Task screen. The Add Replication Task and Edit Replication Task screens show the same setting options.

The Add Replication Task screen shows the Switch to Wizard button at the bottom of the screen.

Switch to Wizard, like Advanced Replication Creation shows the dialog asking you to confirm you want to leave the screen. After clicking Yes the wizard or Add Replication Task screen opens. Settings entered on either screen do not carry over when switching from one screen to the other.

General and Transport Options Settings

The settings in General and Transport Options specify the name of the task, the direction of the data transfer, the transport connection type, and method settings for each type. The Transport setting changes options displayed in the Transport Options area (SSH is the default setting). All three Transport field options share the two settings displayed for Local, and the SSH Connection field displays for both the SSH and SSH+NETCAT transport selections.

Figure 12: Advanced Add Replication Task SSH Transport

General Settings

Setting	Description
Name	(Required) Enter a descriptive name for the replication.
Direction	Select the direction for the replication from the dropdown list. Push sends snapshots to a destination system. Pull connects to a remote system and retrieves snapshots matching the value specified in Naming Schema.
Transport	Select the method of connecting to a remote system for exchanging data from the dropdown list. Options: SSH - Default option that is supported by most systems, but does not achieve great performance. Transfers the snapshot via an SSH connection. It requires a previously created SSH connection on the system. SSH+NETCAT - Uses SSH to establish a connection to the destination system, then uses py-libzfs to send an unencrypted data stream for higher data transfer speeds. This can only be used in trusted networks and requires a port to be open on the NETCAT active side. This only works when replicating to a FreeNSAS, TrueNAS, or other systems with py-libzfs installed. LOCAL - Efficiently replicates snapshots to another dataset on the same system without using the network. Removes Transport Options SSH setting options from the screen.
Use Sudo For Zfs Commands	Select if setting up remote replication tasks when logged in as an admin user. Controls whether the user used for SSH/SSH+NETCAT replication have passwordless sudo enabled to execute zfs commands on the remote host. If not selected, `zfs allow` must be used to grant non-user permissions to perform ZFS tasks. Mounting ZFS file systems by non-root is notpossible due to Linux restrictions.
Number of retries for failed replications	Enter the number of times the replication is attempted before stopping and marking the task as failed.
Logging Level	Select the level of message verbosity in the replication task log from the dropdown list. Options are Default, Debug, Info, Warning, and Error.
Enabled	Select to enable the replication schedule.

Transport Options Settings - Local Transport Option

These settings display for all three Transport options.

Figure 13: Advanced Add Replication Task Local Transport

Local Transport Settings

Setting	Description
Allow Blocks Larger than 128KB	Selected by default. If the system does not support large block transfers this is not selected by default. Allows replication to send large data blocks. The destination system must also support large blocks. This setting cannot be changed after it is enabled and the replication task is created. See sfs(8) for more information.
Allow Compressed WRITE Records	Selected by default. If enabled, allows using compressed write records to make the stream more efficient. The destination system must also support compressed write records. See zfs(8).

Transport Options Settings - SSH Transport Option

When Transport is set to SSH, the settings listed below show in addition to the setting options the Allow Blocks Larger than 128KB and Allow Compressed WRITE Records options shown when Transport is set to Local.

SSH Transport Settings

Setting	Description
SSH Connection	Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Stream Compression	Select a compression algorithm from the dropdown list to reduce the size of the data being replicated. Only appears when SSH is chosen as the Transport type.
Limit (Examples: 500 KiB, 500M, 2 TB)	Enter the number of bytes per second to limit replication speed to this number of bytes per second.

Transport Options Settings - SSH+NETCAT Transport Option

When Transport is set to SSH+NETCAT, the settings listed below show in addition to the setting options the Allow Blocks Larger than 128KB and Allow Compressed WRITE Records options shown when Transport is set to Local.

Figure 15: Advanced Add Replication Task SSH+NETCAT Transport

SSH+NETCAT Transport Settings

Setting	Description
SSH Connection	Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Netcat Active Side	Select the option for the system that opens ports from the dropdown list. Options are Local or Remote. Establishing a connection requires that one of the connection systems has open TCP ports. Consult your IT department to determine which systems are allowed to open ports.
Netcat Active Side Listen Address	Enter the IP address on which the connection Active Side listens. Defaults to 0.0.0.0.
Netcat Active Side Min Port	Enter the lowest port number of the active side listen address that is open to connections.
Netcat Active Side Max Port	Enter the highest port number of the active side listen address that is open to connections. The first available port between the minimum and maximum is used.
Netcat Active Side Connect Address	Enter the host name or IP address used to connect to the active side system. When the active side is Local, this defaults to the SSL_CLIENT environment variable. When the active side is Remote, this defaults to the SSH connection host name.

Advanced Source Options

Source settings specify the location of files you push or pull in the replication task, and the properties applied to the replicated data. Selections made in Recursive and Replicate Specific Snapshots change the Source setting options, and each option shows additional setting options.

Figure 16: Advanced Add Replication Task Source and Destination

Advanced Source Settings

Setting	Description
Source	(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset. Click the arrow_drop_down at the /mnt to collapse the dataset tree.
Recursive	Select to replicate all child dataset snapshots. When selected, Exclude Child Datasets displays.
Exclude Child Datasets	Displays after selecting Recursive. Enter the specific child dataset snapshots to exclude from the replication. Separate each entry by pressing `Enter`.
Include Dataset Properties	Select to include ZFS dataset properties with the replicated snapshots. Shows additional settings: Properties Overide and Properties Exclude. For more information on ZFS dataset properties, see ZFS manpages. Note: 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.
Full Filesystem Replication	Select to completely replicate the selected dataset. The target dataset gets all the properties of the source dataset, child datasets, clones, and snapshots that match the specified naming schema. Hides the Recursive and Include Dataset Properties options, and shows Properties Override and Properties Exclude. Set Snapshot Name Regular Expression to .* to replicate all snapshots.
Properties Override	Enter properties to replace existing dataset properties within the replicated files.
Properties Exclude	Enter any existing dataset properties to remove from the replicated files.

Advanced Destination Options

The settings in Destination specify the location of files you push or pull in the replication task, and the properties applied to the replicated data. Selections made in Encryption and Snapshot Retention Policy change the destination setting options, and each show additional setting options.

Figure 17: Advanced Add Replication Task Destination Options

Advanced Destination Settings

Setting	Description
Destination	(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. Selecting a location defines the full path to that location as the destination. Appending a name to the path creates a new zvol at that location. For example, selecting pol1/dataset1 stores snapshots in dataset 1, but adding /zvol1 after dataset1 creates zvol1 for snapshot storage. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Dataset Read-Only Policy	Select the policy from the dropdown list. Options: Set - Select to change all destination datasets to read only after a successful replication. Require - Select to stop replication unless all existing destination datasets are read only. Ignore - Select to disable checking read only during replication.
Encryption	Select to use encryption when replicating data. For more information on all options, see Encryption.
Replication from scratch	Select if the destination system has snapshots, but does not have any data in common with the source snapshot, destroy all data in destination snapshots, and do a full replication. WARNING! Enabling this option can cause data loss or excessive data transfer if the replication is misconfigured.
Snapshot Retention Policy	Select the policy from the dropdown list to apply when replicated snapshots are deleted from the destination system. Options are: Same as Source - When selecting Same as Source use the Snapshot Lifetime from the source periodic snapshot task. Custom - When selecting Custom define a Snapshot Lifetime for the destination system. Also displays the Snapshot Lifetime and Unit options. None - When selecting None never delete snapshots from the destination system.
Snapshot Lifetime	Use to enter a numeric value to work with the measure of time field below to specify how long a snapshot remains on the destination system.
Unit	Select the measure of time from the dropdown list to work with the numeric value in Snapshot Lifetime. Options are Hour(s), Day(s), Week(s), Month(s), and Year(s).

Various Snapshot Options

The snapshot settings below change options displayed based on selections made.

Figure 18: Add Replication Task Snapshot

Snapshot Settings

Setting	Description
Periodic Snapshot Tasks	Select the snapshot schedule for this replication task from the dropdown list. Select from previously configured periodic snapshot tasks. This replication task must have the same Recursive and Exclude Child Dataset values as the selected periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
Replicate Specific Snapshots	Select to only replicate snapshots that match a defined creation time. Selecting this option shows the By snapshot creation time field. Select the preset schedule or Custom to use the advanced scheduler.
Begin	Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created before this selected time are not included in the replication.
End	Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created after this selected time are not included in the replication.
Also include snapshots with the name	These radio buttons change the naming schema setting option below it. See Snapshot Naming in the wizard section for details on this option and the radio buttons.
Matching naming schema	Displays the Also Include Naming Schema setting.
Matching regular expression	Displays the Matching regular expression setting.
Also Include Naming Schema	Displays after selecting Matching naming schema. Enter the pattern of naming custom snapshots to include in the replication with the periodic snapshot schedule. Enter the strftime(3) strings that match the snapshots to include in the replication. When a periodic snapshot is not linked to the replication, enter the naming schema for manually created snapshots. Has the same %Y, %m, %d, %H, and %M string requirements as the Naming Schema in a Add Periodic Snapshot Task. Separate entries by pressing `Enter`.
Matching regular expression	Displays after selecting Matching regular expression. Replicates all snapshots that match the specified regular expression. This process reads snapshot metadata to determine the snapshot creation order. This slows regular performance on the systems with a large number of snapshots.
Save Pending Snapshots	Prevents source system snapshots that have failed replication from being automatically removed by the Snapshot Retention Policy.

Replication Schedule Advanced Options

These schedule setting options are common to both the Replication Task Wizard and Add Replication Task screens.

Figure 19: Advanced Add Replication Task Schedule

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.

Schedule Presets

The Schedule dropdown list preset options are:

Hourly at the start of each hour
Daily At 00:00 (12:00 AM)
Weekly On Sundays at 00:00 (12:00 AM)
Monthly On the first day of the month at 00:00 (12:00 AM)
Create Custom schedule that opens the Advanced Scheduler window.

Advanced Scheduler

Choosing a Presets option populates the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

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 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 N^th 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.

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.

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.

Advanced Replication Contents

Configuring Advanced Replication Tasks: Instructions to configure advanced ZFS snapshot replication tasks in TrueNAS.

Setting Up an Encrypted Replication Task: Provides instructions on adding a replication task to a remote system and using encryption.

Unlocking a Replication Encrypted Dataset or Zvol: Provides information on three methods of unlocking replicated encrypted datasets or zvols without a passphrase.

Configuring Advanced Replication Tasks

Setting Up a Replication Task Overview

This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps you should take prior to configuring a replication task.

Setting Up a Simple Replication Task Overview

The sections below provide overviews on what to do before you begin configuring a replication task.

Before You Begin Local Replication

Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots). TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up. TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task. You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard. Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens. Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.

Before You Begin Remote Replication

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.
Figure 1: Adding A Home Directory
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.

Creating a Simplified Advanced Replication Task

To access advanced replication settings, click Advanced Replication Creation at the bottom of the first replication wizard screen. The Add Replication Task configuration screen opens.

Give the task a name. Unlike the wizard, the Name does not automatically populate with the source/destination task name after you set the source and destination for the task. Each task name must be unique, and we recommend naming it in a way that makes it easy to remember what the task is doing.
Select the direction of the task. Pull pulls data from a remote system to the local system. Push sends data from the local system to the remote.
Select the transfer method for this replication from the Transport dropdown list.
- Select LOCAL to replicate data to another location on the same system.
- Select SSH is the standard option for sending or receiving data from a remote system. When selected, also select an SSH connection from the SSH Connection dropdown list.
- Select SSH+Netcat is a faster option for replication when it occurs within a completely secure network. SSH+Netcat requires defining NETCAT ports and addresses to use for the NETCAT connection.
With SSH-based replications, select the SSH Connection with the remote system from which you want to receive snapshots or send snapshots to. To create a new connection to use for replication from a destination to this local system, select newpullssh.
Select Use Sudo for Zfs Commands to control whether the user for SSH/SSH+NETCAT replication has passwordless sudo enabled to execute zfs commands on the remote host. If not selected, you must enter zfs allow on the remote system to 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-%M finds and replicates snapshots like custom-2020-03-25_09-15. Enter multiple schemas by pressing Enter to separate each schema.

Set the replication schedule to use and define when the replication task runs. Leave Run Automatically selected to use the snapshot task specified and start the replication immediately after the related periodic snapshot task completes. Select Schedule to display scheduling options for this replication task, and to run the task according to its own schedule.

Selecting Schedule allows scheduling the replication to run at a separate time. Choose a time frame that gives the replication task enough time to finish and is during a time of day when network traffic for both source and destination systems is minimal. Use the custom scheduler (recommended) when you need to fine-tune an exact time or day for the replication.

Advanced Scheduler

Choosing a Presets option populates in the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

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 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 N^th 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.

Setting up Replication with SSH+NETCAT

When setting Transport to SSH+NETCAT, the replication administration user on the remote system requires passwordless sudo access for both /usr/sbin/zfs and /usr/bin/python3. The automatic SSH configuration only grants sudo rights for /usr/sbin/zfs. Without the additional python3 entry, the task fails with:

[EFAULT] Unknown SSH+NETCAT transport error: ‘sudo: a terminal is required to read the password’

First, verify the root user password is enabled on the remote TrueNAS system. Go to Credentials > Users, select the root user, and confirm the password is not disabled and has a password set.

Next, add the required sudo entry on the remote TrueNAS system:

Log in to the remote system as root through an SSH session or use the TrueNAS Shell.
Run visudo to open the sudoers file.
Add the following line for the replication user, replacing username with the actual user:
username ALL=(ALL) NOPASSWD: /usr/bin/python3
Save and exit.

You can then create the replication task on the local system using the Add Replication Task screen. Click Add on the Data Protection > Replication card to open the wizard, then click Advanced Replication Task to open the Add Replication Task screen.

Setting a Replication Compression Level

Options for compressing data, adding a bandwidth limit, or other data stream customizations are available. Stream Compression options are only available when using SSH. Before enabling Compressed WRITE Records, verify that the destination system also supports compressed write records.

Setting Block Size

Allow Blocks Larger than 128KB is a one-way toggle. Replication tasks using large block replication only continue to work as long as this option remains enabled.

Setting Full File System Replication

By default, the replication task uses snapshots to quickly transfer data to the receiving system. Selecting Full Filesystem Replication means the task completely replicates the chosen Source, including all dataset properties, snapshots, child datasets, and clones. When using this option, we recommend allocating additional time for the replication task to run.

Replicating Dataset Properties

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.

Replicating Child Datasets

Select Recursive to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.

Defining Replication Properties

Enter newly defined properties in Properties Override to replace existing dataset properties with the newly defined properties in the replicated files.

List any existing dataset properties to remove from the replicated files in Properties Exclude.

Saving Pending Snapshots

When a replication task 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.

Changing Destination Dataset from Read-Only

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).

Adding Transfer Encryption

The Encryption option adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system. Selecting Encryption adds the additional setting options HEX key or PASSPHRASE. You can store the encryption key either in the TrueNAS system database or in a custom-defined location.

Synchronizing Destination and Source Snapshots

Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots. TrueNAS also does a full replication of the source snapshots as if the replication task had not run, which can lead to excessive bandwidth consumption.
This can be a very destructive option. Make sure that any snapshots deleted from the destination are obsolete or otherwise backed up in a different location.

Defining Snapshot Retention

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.

Replicating Snapshots Matching a Schedule

Selecting Only Replicate Snapshots Matching Schedule restricts the replication to only those snapshots created at the same time as the replication schedule.

Setting Up an Encrypted Replication Task

Using Encryption in Replication Tasks

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.

Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.

Remote replication with datasets also require an SSH connection in TrueNAS. You can use an existing SSH connection if it has the same user credentials you want to use for the new replication task.

Creating a Remote Replication Task for an Encrypted Dataset

To streamline creating simple replication tasks, use the Replication Task Wizard to create and copy ZFS snapshots to another system. The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.

If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make changes such as assigning it a different destination, selecting other options like encryption, schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard. This saves some time when creating multiple replication tasks between the same two systems.

Unlock the source dataset and export the encryption key to a text editor such as Notepad. Go to Datasets select the source dataset, locate the ZFS Encryption widget and unlock the dataset if locked. Export the key and paste it in any text editor such as Notepad. If you set up encryption to use a passphrase, you do not need to export a key.

Configure the remote replication as described in the Creating a Remote Replication Task.

Unlocking the Destination Dataset

After the replication task runs and creates the snapshot on the destination, you must unlock the dataset to access the data. Click the from the replication task options to download a key file that unlocks the destination dataset.

Replicating to an Unencrypted Destination Dataset

TrueNAS does not support preserving encrypted dataset properties when trying to re-encrypt an already encrypted source dataset.

To replicate an encrypted dataset to an unencrypted dataset on the remote destination system, follow the instructions above to configure the task, then to clear the dataset properties for the replication task:

Select the task on the Replication Task widget. The Edit Replication Task screen opens.
Scroll down to and select Include Dataset Properties to clear the checkbox.

Figure 1: Edit Replication Task Include Dataset Properties

Click Save.

This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.

Using Additional Encryption Options

When you replicate an encrypted pool or dataset, you have one level of encryption applied at the data storage level. Use the passphrase or key created or exported from the dataset or pool to unlock the dataset on the destination server.

To add a second layer of encryption at the replication task level, select Encryption on the Replication Task Wizard or on the Add Replication Task screen, then select the type of encryption you want to apply.

Figure 2: Replication Task Encryption Options

Select either Hex (base-16 numeral format) or Passphrase (alphanumeric format) from the Encryption Key Format dropdown list to open settings for that type of encryption.

Selecting Hex displays Generate Encryption Key preselected. Select the checkbox to clear it and display the Encryption Key field where you can import a custom hex key.

Selecting Passphrase displays the Passphrase field where you enter your alphanumeric passphrase.

Select Store Encryption key in Sending TrueNAS database to store the encryption key in the sending TrueNAS database or leave unselected to choose a temporary location for the encryption key that decrypts replicated data.

Unlocking a Replication Encrypted Dataset or Zvol

Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase

Method 1: Construct JSON Manifest.

Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this: {"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.

Method 2: Replicate Encrypted Dataset/zvol Without Properties.

Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.

Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.

Method 3: Replicate Key Encrypted Dataset/zvol.

Go to Datasets on the system you are replicating from. Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset. Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.

VMware Snapshots

VMware snapshot integration allows TrueNAS to coordinate ZFS snapshots with VMware datastores.

Creating VMWare Snapshots: Provides instructions for creating ZFS snapshots when using TrueNAS as a VMWare datastore.

VMWare Snapshots Screen: Provides information on the VMWare-Snapshot Add screen settings and functions.

Creating VMWare Snapshots

Use this procedure to create ZFS snapshots when using TrueNAS as a VMWare datastore.

You must have a paid edition of VMWare ESXi to use the TrueNAS VMWare Snapshots feature. ESXi free has a locked (read-only) API that prevents using TrueNAS VMWare Snapshots.
This tutorial uses ESXi version 8.

When creating a ZFS snapshot of the connected dataset, VMWare automatically takes a snapshot of any running virtual machines on the associated datastore. VMware snapshots can integrate VMware Tools, making it possible to quiesce VM snapshots, sync filesystems, take shadow copy snapshots, and more. Quiescing snapshots is the process of bringing VM data into a consistent state, suitable for creating automatic backups. Quiesced snapshots can be file-system consistent, where all pending data or file-system changes complete, or application consistent, where applications complete all tasks and flush buffers, prior to creating the snapshot.See Manage Snapshots from VMWare for more information.

VM snapshots are included as part of the connected Virtual Machine File System (VMFS) datastore and stored as a point-in-time within the scheduled or manual TrueNAS ZFS snapshot of the data or zvol backing that VMWare datastore. The temporary VMware snapshots are automatically deleted on the VMWare side, but still exist in the ZFS snapshot and are available as stable restore points.

TrueNAS Enterprise
TrueNAS Enterprise customers with TrueNAS 12.0 and newer and TrueNAS 22.12.4 (Bluefin) and newer deployed can access the iXsystems TrueNAS vCenter plugin. This activates management options for TrueNAS hardware attached to vCenter Server and enables limited management of TrueNAS systems from a single interface.
Please contact TrueNAS Enterprise Support to learn more and schedule a time to deploy or upgrade the plugin.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Before You Begin

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.
Figure 1: Configure iSCSI Screen
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.
Figure 2: 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.
Figure 3: Devices Screen
Go to Datastores and click New Datastore to create a new VMFS datastore using the TrueNAS device. Then go to Virtual Machines and create your new virtual machine(s), using the new datastore for storage.

Creating a VMWare Snapshot

To configure TrueNAS to create VMWare snapshots, go to Data Protection and click the VMware Snapshot Integration button in the Periodic Snapshot Tasks widget to open the VMWare Snapshots screen.

Note that you can organize information in the columns of the table(s) below by clicking on each column title. This allows you to toggle the information between a descending an ascending order.

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.
Figure 6: Add VMware Snapshot Screen
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.
Figure 7: VMWare Snapshot Configured
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.

Reverting to a ZFS Snapshot in VMWare ESXi

To revert a VM using a ZFS snapshot, first clone the snapshot as a new dataset in TrueNAS, present the cloned dataset to ESXi as a new LUN, resignature the snapshot to create a new datastore, then stop the old VM and re-register the existing machine from the new datastore.

Clone the snapshot to a new dataset.
a. Go to Data Protection and click Snapshots on the Periodic Snapshot Tasks widget and locate the snapshot you want to recover and click on that row to expand details.
b. Click Clone to New Dataset. Enter a name for the new dataset or accept the one provided then click Clone.
The cloned zvol appears on the Datasets screen.
Figure 8: Cloned Zvol
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.
Figure 9: Cloned Extent
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.
Figure 10: Cloned Associated Target
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.
Figure 11: Devices Screen with Snapshot
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.
Figure 12: Datastores Screen with Snapshot
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.
Figure 13: Virtual Machines Screen
b. Click Create / Register VM to open the New virtual machine screen.
Figure 14: Create New Virtual Machine
c. Select Register an existing virtual machine and then click next.
d. Click Select and use the Datastore Browser to select the snapshot datastore.
Figure 15: Select Existing VMs
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.

TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Interface Configuration: Tutorials to configure the various types of network interfaces available in TrueNAS.

Configuring Network Interfaces: Tutorials to configure the various types of network interfaces available in TrueNAS.
Setting Up a Network Bridge: Provides instructions on setting up a network bridge interface.
Setting Up a Link Aggregation: Provides instructions on setting up a link aggregation (bond) interface.
Setting Up a Network VLAN : Provides instructions on setting up a network VLAN interface.
Network Interface Screens: Provides information on the Network screen Interfaces widget and configuration screens.

Network Configuration: Configuration tutorials and UI reference for global network settings, IPv6, and HA network configuration in TrueNAS.

Managing Network Configurations: Provides instructions on configuring or managing global network configuration settings.
Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.
Managing Network Settings (Enterprise HA): Provides instructions on how to make changes to network settings on TrueNAS Enterprise (HA) systems.
Network Configuration Screens: The Network Configuration widget shows the general TrueNAS network settings not specific to any interface.

Static Routes: Configuration tutorials and UI reference for static routes in TrueNAS.

Configuring Static Routes: Provides instructions on configuring a static route using the TrueNAS web UI.
Static Routes Screens: The Static Routes widget displays existing static routes or sets up new ones.

IPMI: Configuration tutorials and UI reference for Intelligent Platform Management Interface (IPMI) in TrueNAS.

Setting Up IPMI: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.
IPMI Screens: Provides information on the Network screen IPMI widget and configuration screen.

Accessing NAS from VMs and Containers: Provides instructions on how to create a bridge interface for virtual machines or applications and provides Linux and Windows examples.

Network Screen: Describes the screens and fields in the TrueNAS Network section.

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 Network Interfaces: Tutorials to configure the various types of network interfaces available in TrueNAS.

Setting Up a Network Bridge: Provides instructions on setting up a network bridge interface.

Setting Up a Link Aggregation: Provides instructions on setting up a link aggregation (bond) interface.

Setting Up a Network VLAN : Provides instructions on setting up a network VLAN interface.

Network Interface Screens: Provides information on the Network screen Interfaces widget and configuration screens.

Configuring Network Interfaces

Why should I use different interface types?

A Link Aggregation (bond interface) optimizes multi-user performance, balances network traffic, and provides network failover protection. In a failover it prevents a network outage by dynamically reassigning traffic to another interface when a physical link, like a cable or NIC, fails.

A network bridge enables communication between two networks and provides a way for them to work as a single network. Bridges can serve IP addresses to multiple VMs on one interface, which allows your VMs to be on the same network as the host.

A VLAN (virtual LAN) segments a single physical network into multiple logical networks, allowing network traffic isolation and security boundaries without requiring separate physical hardware. VLANs provide separate traffic management for storage (iSCSI/NFS), VMs, and multi-tenant environments while improving security, reducing broadcast domains, and enabling multiple networks on a single NIC.

The Network screen shows network settings for interfaces, global network settings, adding static routes, and IPMI connections. This article describes adding new or changing existing network interfaces. For information on configuring IPv6 addresses, see Configuring IPv6.

You must know the DNS name server and default gateway addresses for your IP address.

Static IP or DHCP-Assigned?

By default, TrueNAS configures the primary network interface for Dynamic Host Configuration Protocol (DHCP) IP address management during installation. However, some administrators might choose to assign a static IP address to the primary network interface. This choice can be made if TrueNAS is deployed on a system that does not allow DHCP for security, stability, or other reasons.

In all deployments, only one interface can be set up for DHCP, which is typically the primary network interface configured during the installation process. Any additional interfaces must be manually configured with one or more static IP addresses.

Before You Begin

You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server. Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.

To prepare before making changes:

Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes. You only have 60 seconds to change and test new network settings before they revert to the current settings. For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.

Before making network interface changes:

Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.

Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.

Adding an Interface

TrueNAS uses DHCP to assign an IP address to the primary network interface during installation to provide access to the web UI. DHCP provides the IP address for only one network interface.
After initially installing TrueNAS, you can change the DHCP-assigned IP address to a static IP address by:
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 more_vert for the interface. This resets the interface from a static IP address to a DHCP-assigned address and resets the domain to the TrueNAS default local.

Enter a name for the interface using the format that corresponds to the type of interface you are adding. Naming differs between physical and virtual interfaces. The name assigned to the primary physical network interface on your system is based on the systemd predictable naming scheme, and reflects the hardware type and location. The names vary based on your hardware configuration. For example, eno1 for onboard NICs, ens3 for PCIe slot NICs, and you might see eno1np0, which is an onboard NIC with more than one port on the NIC.

When selecting a virtual interface type, enter a name based on the type. For example, bondX, vlanX, or brX and where X is a number.

To allow DHCP to assign the interface IP address, select Get IP address Automatically from DHCP.

To use a fixed (static) IP address, select the Define Static IP Addresses, and then click Add to the right of Static IP Addresses to show the IP address and netmask (CIDR) fields. Enter the assigned IP address and select the netmask from the dropdown list.

Click Add for each IP address you want to associate with the interface.

If adding an IPv6 IP address, refer to Configuring IPv6 for details on this type of network configuration.

Click Save when you are certain of your configuration. You cannot change the interface type or name after clicking Save!

Testing Network Interface Changes

TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.

TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.

Click the Test Changes button to test access to the UI after making a change and before making it a permanent change. This safeguard is intended to prevent changes that can break access to the UI.

Revert Changes discards any changes made to the interface within the same 60-second period.

The test timer starts after you click Save on the Add Interface or Edit Interface screens. After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.

To test the change in a different browser tab:

Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter. The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.

If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change. Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.

If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.

Editing an Interface

To change an existing interface, click on the more_vert icon at the right of the interface, and then click Edit to open the Edit Interface screen.

The Edit Interface and Add Interface screen settings are identical, but the Type and Name fields are not editable for an existing interface. If you created the wrong type of virtual interface (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 an Interface Configuration

Resetting the configuration for a network interface can result in lost access to the TrueNAS UI and losing the connection to TrueNAS!
Clicking Reset Configuration resets the domain name back to the default value, and changes the static IP address to DHCP-assigned.
When saved, changes cause lost access to the UI. You might need command line knowledge, and either IPMI or physical access to the TrueNAS system to fix misconfigured network settings. If using IPMI or a physical connect to the system, you can change network and interface settings through the Console Setup menu.
The TrueNAS UI does not offer a way to delete the interface. Do not delete the primary network interface in the CLI!

Click on the more_vert dropdown list for the interface, then select Reset Configuration. The current IP address resets to a DHCP-assigned IP address and the domain name reverts to the default setting.

Confirm validates the reset activity and activates the Reset button.

Reset clears the configuration for that interface. After making the changes and clicking Save, the test change options show on the Network screen. Follow the procedure above to test your changes and validate you still have access to the UI and the TrueNAS system.

Changing from DHCP to a Static IP Address

TrueNAS allows assigning static IP addresses to an interface when not using a DHCP-assigned address. Static IP addresses set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access. You can add an additional IP address for a network interface configured with another primary IP address.

Verify the default gateway and nameservers for the DHCP-assigned address and new static IP address are the same before making a change. If not the same, edit the global network settings before changing the interface so you can properly test the change.

Changing the Global Network Settings

Go to System > Network:

Check the name servers and default router information in the Global Information widget. If the current settings are not on the same network, click Settings and modify each setting as needed to allow the static IP to communicate over the network.
Enter the IP addresses for the DNS name servers in the Primary, Secondary, and the optional Tertiary fields.
Figure 4: Add Name Server and Default Gateway
For home users, enter 8.8.8.8 for a DNS name server address so you can communicate with external networks.
Enter the IP address for the default gateway in the appropriate field. If the static network is IPv4 enter the gateway in IPv4 Default Gateway, if the static network is IPv6 use IPv6 Default Gateway.
Click Save.

If in an IPMI session, you can use the Console Setup menu to change settings. Enter 2 to configure general network settings like the default gateway and name servers.

Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (bond) or network bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance. However, ethernet network topology allows only one interface to communicate at a time. Additionally, both interfaces must handle broadcast messages since they are listening on the same network. This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation configured with Link Aggregation Control Protocol (LACP). A single link aggregation (bond) interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups. LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network. If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.

To use the UI to change an interface from DHCP to a static IP address, go to System > Network:

Verify the default gateway and name servers work with the new static IP address. If not, click the link above and follow the instructions to update the global network settings.
Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Figure 5: Adding a Static IP Address
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!
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (bond) or network bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance. However, ethernet network topology allows only one interface to communicate at a time. Additionally, both interfaces must handle broadcast messages since they are listening on the same network. This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation configured with Link Aggregation Control Protocol (LACP). A single link aggregation (bond) interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups. LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network. If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
If an error displays or the Save button remains inactive when setting the IP addresses on multiple interfaces, check the subnet and ensure the netmask (CIDR) numbers are different.
Click Save.
Click Test Changes when prompted. Follow the procedure above to test nework changes.

Returning to a DHCP-Assigned IP Address

Only one interface can use DHCP to assign the IP address and that is likely the primary network interface. If you do not have an existing network interface set to use DHCP you can convert an interface from static IP to DHCP.

To switch back to using DHCP:

Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Select Get IP Address Automatically from DHCP.
Click Save.
Verify the current default gateway and name servers work with the new DHCP-assigned IP address. If yes, test the network change. Click on 60 above the Test Changes button to extend the number of seconds you have to test the network change.
If the current settings do not work with the new DHCP-assigned IP address, click the link in the Changing from DHCP to a static IP Address section, and follow the directions to change these settings.
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 FEC Mode

TrueNAS Enterprise
FEC Mode configuration is available in TrueNAS Enterprise systems. Administrators should contact TrueNAS Enterprise Support before changing network settings.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Forward Error Correction (FEC) is a link-layer mechanism that detects and corrects transmission errors on high-speed Ethernet connections, such as 25 GbE and 100 GbE links. The TrueNAS network interface card (NIC) and the upstream switch must agree on the FEC mode for the link to come up. In most environments, the NIC negotiates the correct mode automatically.

TrueNAS does not set an FEC mode by default. The NIC uses the factory-default behavior, which is typically automatic negotiation. Set the mode to AUTO to explicitly direct the NIC to negotiate.

The FEC Mode dropdown on the Edit Interface screen shows only when both of these conditions are true:

The interface is a physical NIC, not a bridge, link aggregation, or VLAN.
The NIC reports at least one supported FEC mode.

TrueNAS reads the supported modes from the NIC when you open the Edit Interface screen. The dropdown lists only the modes valid for that hardware.

An FEC mode mismatch with the upstream switch can disconnect the interface from the network. Change this setting only when TrueNAS Support directs you to, for troubleshooting link negotiation failures.

To change the FEC mode for an interface:

Go to System > Network. Click Edit on the more_vert menu for the interface to open the Edit Interface screen.
If the FEC Mode dropdown does not appear, the NIC does not support FEC.
Select the FEC mode from the FEC Mode dropdown. The dropdown lists only the modes the NIC supports. See Network Interface Screens for descriptions of each mode.
Click Apply. The test changes options show on the Network screen.
Test the change as described in Testing Network Interface Changes. Verify the system is reachable on the network.

Setting FEC Mode

TrueNAS Enterprise
FEC Mode configuration is available in TrueNAS Enterprise systems. Administrators should contact TrueNAS Enterprise Support before changing network settings.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

TrueNAS does not set an FEC mode by default. The NIC uses the factory-default behavior, which is typically automatic negotiation. Set the mode to AUTO to explicitly direct the NIC to negotiate.

Edit Interface screen showing the FEC Mode dropdown — Figure 6: Edit Interface FEC Mode Dropdown

The FEC Mode dropdown on the Edit Interface screen shows only when both of these conditions are true:

The interface is a physical NIC, not a bridge, link aggregation, or VLAN.
The NIC reports at least one supported FEC mode.

The Add Interface screen creates only virtual interfaces - bridges, link aggregations, and VLANs - none of which support FEC. TrueNAS detects physical interfaces from the hardware, so FEC Mode appears only when you edit an existing physical interface.

TrueNAS reads the supported modes from the NIC when you open the Edit Interface screen. The dropdown lists only the modes valid for that hardware.

An FEC mode mismatch with the upstream switch can disconnect the interface from the network. Change this setting only when TrueNAS Support directs you to, for troubleshooting link negotiation failures.

To change the FEC mode for an interface:

Go to System > Network. Click Edit on the more_vert menu for the interface to open the Edit Interface screen.
If the FEC Mode dropdown does not appear, the NIC does not support FEC.
Select the FEC mode from the FEC Mode dropdown. The dropdown lists only the modes the NIC supports. See Network Interface Screens for descriptions of each mode.
Click Apply. The test changes options show on the Network screen.
Test the change as described in Testing Network Interface Changes. Verify the system is reachable on the network.

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.

Before You Begin

You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server. Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.

To prepare before making changes:

Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes. You only have 60 seconds to change and test new network settings before they revert to the current settings. For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.

Testing Network Interface Changes

TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.

TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.

Revert Changes discards any changes made to the interface within the same 60-second period.

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 you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.

Adding a Bridge

To set up a bridge interface:

Go to Apps and the Containers screens to verify all apps and containers are stopped. If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM. Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Figure 2: Network Interfaces and Global Configuration Widgets
Click the more_vert icon for the interface, to open the Edit Interface screen. Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
Figure 3: Edit Interface for a Bridge
Click Add to open the Add Interface screen. Configure the interface:
Figure 4: Bridge Interface Settings
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.

Troubleshooting Network Changes

Occasionally, a misconfigured bridge or a conflict with a running application, VM, or service can cause the network changes test to fail. Typically, this is because the bridge is configured using an IP address that is already in use. If the system does not receive a Save Changes check-in before the test times out (default 60 seconds), TrueNAS automatically reverts all unsaved changes.

The following troubleshooting options are available if you cannot save the new bridge and network changes. Options are ordered from the least to the most disruptive. Try options one and two before proceeding with options three and four.

Ensure that there are no currently running applications.
Stop any running VMs.
(Optional) Go to Services. Click edit Configure to view the current configuration of sharing services, including SMB and NFS. Stop any services that have a bind IP address matching the bridge IP address. Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.

Setting Up a Link Aggregation

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.

Before You Begin

You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server. Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.

To prepare before making changes:

Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes. You only have 60 seconds to change and test new network settings before they revert to the current settings. For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.

Before making network interface changes:

Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.

Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.

If configuring an LACP link aggregation, configure a port-channel or link aggregation group on your network switch before creating the 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.

Testing Network Interface Changes

TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.

TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.

Revert Changes discards any changes made to the interface within the same 60-second period.

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 you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.

Adding a Link Aggregation Interface

To set up a 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.

Figure 2: Add Link Aggregation Interface

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.
LACP
LACP is the most common protocol for link aggregation interfaces based on IEEE specification 802.3ad.
In LACP mode, the interfaces negotiate with the network switch to form a group of ports that are all active at once. The network switch must support LACP for this option to function.
a. Select the hash policy from the Transmit Hash Policy dropdown list. LAYER2+3 is the default selection.
b. Select the LACPDU Rate options are Slow or Fast.
SLOW (default) sets the heartbeat request to every second and the timeout to a three-consecutive heartbeat loss that is three seconds.
FAST sets the timeout rate at one per second, even after synchronization. FAST allows for rapid detection of faults.
FAILOVER
Select FAILOVER to send traffic through the primary interface of the group. If the primary interface fails, traffic diverts to the next available interface in the bond group.
LOADBALANCE
Select LOADBALANCE to accept traffic on any port of the bond group and balance the outgoing traffic on the active ports in the bond group. LOADBALANCE is a static setup that does not monitor the link state or negotiate with the switch.
Select the Transmit Hash Policy option from the dropdown list. LAYER2+3 is the default selection.
Select the interfaces to use in the aggregation from the Link Aggregation Interface dropdown list.
(Optional) Click Add to the right of Static IP Addresses to show additional IP address fields for each additional IP address to add to this 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

Before you begin, make sure you have an Ethernet card connected to a switch port and configured for your VLAN. Ensure that you have also preconfigured the VLAN tag in the switched network. Consult with your IT department to obtain this VLAN tag if you are not the network administrator for your systems.

You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server. Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.

To prepare before making changes:

Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes. You only have 60 seconds to change and test new network settings before they revert to the current settings. For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.

Before making network interface changes:

Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.

Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.

Testing Network Interface Changes

TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.

TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.

Revert Changes discards any changes made to the interface within the same 60-second period.

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 you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.

Adding a VLAN Interface

To set up a VLAN interface, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:

Select VLAN from the Type dropdown list. You cannot change the Type field value after clicking Apply.
Figure 2: Add VLAN Interface Settings
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 more_vert at the right of each interface shows a dropdown list with two options:

Edit - Opens the Edit Interface screen.
Reset Configuration - Opens the Reset Configuration dialog.

TrueNAS Enterprise
High Availability (HA) Enterprise systems cannot reset or edit interface settings with failover enabled. On systems with HA failover enabled, the Reset Configuration or Edit options are disabled. Go to System > Failover to disable failover before attempting to modify interfaces on HA systems.
Figure 2: Network Interfaces Widget with HA Enabled

Reset Configuration Dialog

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.

Add/Edit Interface Screens

The Add Interface screen allows you to configure the settings for a new interface. The Edit Interface screen allows changes to settings for an existing interface. Both screens show the test changes options to validate settings and prevent losing access to the TrueNAS system if the interface is incorrectly configured.

The setting on the Add Interface and Edit Interface screens are almost identical.

Type only shows on the Add Interface screen. It cannot be changed on the Edit Interface screen. Type is a required field. The additional settings show on the Add Interface screen based on the selected type.

Apply saves setting changes, and shows the test changes options.

Interface Settings

Interface settings configure the network interface name, type, and IP address assignment. These settings are common to the three interface types.

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: Bridge - Creates a logical link between multiple networks. Link Aggregation (bond) - Combines multiple network connections into a single interface. VLAN - Partitions and isolates a segment of the connection. Each type of interface shows additional configuration settings for that type. The type cannot be changed after clicking Apply, and testing and accepting the interface change.
Name	(Required) Accepts manual or copy/paste entry of a name for the interface. Names must use the format bondX for a 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.
FEC Mode	(Enterprise only) Sets the Forward Error Correction (FEC) mode for a physical interface. Only shows on the Edit Interface screen for physical interfaces that support FEC. Does not appear for bridges, link aggregations, or VLANs. The available modes depend on the network interface card (NIC) and can include: AUTO - The NIC negotiates the best FEC mode based on cable and port capabilities. OFF - Disables FEC. RS - Reed-Solomon FEC, often used for 25 GbE and 100 GbE NICs. BASER - BaseR FEC (also called FireCode). LLRS - Low Latency Reed-Solomon FEC, used for 25GBASE-KR/CR. Changes to this setting can disconnect the interface from the network. See Setting FEC Mode for guidance on when to use it.

Bridge Settings

Bridge settings show after setting Type to Bridge. TrueNAS automatically populates the Name with the default br1. Use Description to further define or clarify how or where the bridge is used.

Bridge Members sets the network interfaces to include in the bridge to the option selected on the dropdown list. |

Link Aggregation Settings

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.

Figure 6: Link Aggregation LACP Protocol

Setting	Description
Link Aggregation Protocol	The protocol determines the outgoing and incoming traffic ports. Shows a dropdown list with three link aggregation protocol options: LACP - Use if the network switch is capable of active LACP (this is the recommended protocol). LACP shows additional settings. Failover - Use if the network switch does not support active LACP. This is the default protocol choice and is only used if the network switch does not support active LACP. Failover uses only the Link Aggregation Interfaces setting. Loadbalance - Use to set up loadbalancing. This does not use any other link aggregation settings.
Link Aggregation Interfaces	(Required) Shows a dropdown list of interfaces in the system. Select the interfaces to use in the aggregation. Warning! Link Aggregation creation fails if any of the selected interfaces are manually configured! Failover shows the interfaces that can be enabled for failover. Enabling the toggle select the interface. Loadbalance shows the Transmit Hash Policy setting.
Transmit Hash Policy	Shows when the protocol is set to LCAP or Loadbalance. Dropdown list shows three hash policy options, LAYER2, LAYER2+3 the default, or LAYER3+4.
LACPDU Rate	Shows when the protocol is set to LCAP. Shows a dropdown list with two options: Slow or Fast.

VLAN Settings

VLAN settings show after setting Type to VLAN. TrueNAS automatically populates the Name with the default vlan1. Use Description to further define or clarify how or where the bridge is used.

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).

Test Changes

These options show above the Interfaces widget after applying changes to a network interface that can affect access to the UI., and are used to test network changes when creating a new or changing an existing network interface

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: Provides instructions on configuring or managing global network configuration settings.

Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.

Managing Network Settings (Enterprise HA): Provides instructions on how to make changes to network settings on TrueNAS Enterprise (HA) systems.

Network Configuration Screens: The Network Configuration widget shows the general TrueNAS network settings not specific to any interface.

Managing Network Configurations

Use the Network Configuration Settings widget shows existing general network settings like the default gateway and DNS servers, set services allowed to externally communicate, enter an HTTP proxy, or host name database.

You can lose your TrueNAS connection if you change the network interface that the web interface uses! You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Do not configure network settings to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers. This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started.

Can I configure these options elsewhere?

Users can configure many of the interface, DNS, and gateway options using the Console Setup menu. Be sure to check both locations when troubleshooting network connectivity issues.

Adding Network Settings

Use the Network Configuration widget to add general network settings like the default gateway and DNS name servers to allow external communication.

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.
Figure 1: Global Configuration Host and Domain Name Settings
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.
Figure 2: Global Configuration Nameserver Settings
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
Figure 3: Global Configuration Outbound Settings
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.

Configuring IPv6 Addresses

After configuring your network infrastructure for IPv6, assign the IP addresses for your TrueNAS system. Use the TrueNAS UI to configure your network settings. If setting TrueNAS up for the first time after a clean install, use the Console Setup menu to enter IPv6 addresses.

If configuring your network settings using the Console Setup menu for the first time after installing TrueNAS, first configure the interface address. Type 1, then press Enter. Enter eno1 in name, then the IPv6 address in aliases.

Save, then select a to apply and p to make it persist. Type q to return to the Console Setup menu.

Next, configure the IPv6 gateway address, and the nameserver addresses. Type 2, then press Enter. Enter the name server addresses provided by your IT department or Internet Service Provider (ISP), and then the gateways. Save, then select a to apply and p to make it persist.

Adding an IPv6 Interface in the UI

Navigate to System > Network screen to enter your network settings.

Click on Add in the Interfaces to open the Add Interface screen.

Enter en8s0 as the name for the interface if it is the primary interface.
Clear the DHCP checkbox, then select Autoconfigure IPv6 if you want to create the IP address using SLAAC. This automatically configures the IPv6 address. You can only use this option one time to configure an IPv6 address for the system.
Enter the IPv6 address assigned to the NIC port if using a fixed IP address assignment.
Click Save
Test the change. If adding the primary interface test the network connection by opening a new browser window. Enter the IPv6 address inside square brackets in the URL address field, for example, [ipv6 address]. After the system comes up, save the changes to the network interface.

To access the UI after configuring an IPv6 address, enter the IPv6 address inside square brackets in the browser URL field. You cannot access the UI with the assigned host name when the system is configured on an IPv6 network.

Configuring Dual Stacking

TrueNAS supports dual-stacking IPv4 and IPv6 addresses in the same interface. An IPv4 network cannot see or communicate with an IPv6 network unless some gateway is configured to allow IPv6 communication. Dual stacking these two protocols allows TrueNAS to see and communicate with an all IPv6 address or website.

You must have IPv6 configured in your networking infrastructure. Add IPv6 to your network router to permit the incoming and outgoing traffic. This provides the required gateway to permit communication with this IP protocol. Assign a static IPv6 address and netmask, the network gateway address, and name servers to configure in TrueNAS.

When configuring dual stacking, the order in which you configure the two network IP protocols does not matter.

If IPv4 networking is already configured in TrueNAS, to set up dual stacking of IPv6 in the UI, go to System > Network:

Add the IPv6 gateway information.
Click Settings on the Global Configuration widget to open the Edit Global Configuration screen.
Enter the IPv6 address for the gateway in IPv6 Default Gateway.
Click Save.
Add the IPv6 static IP address to the primary interface.
Select the primary interface, en8s0, then click Edit.
Click Add* to the right of Aliases to add another set of IP Address fields.
Enter the IPv6 address, then select the netmask.
Click Save
Test the network change. To verify the IPv6 address, in a new browser window, enter the address inside square brackets. For example, [ffff:ff:59f8:100::12].
Log into the UI, and click Save Changes.
Log out of that browser session, return to your other UI session. Both IPv4 and IPv6 addresses should show on the screen for the primary interface.

After installing TrueNAS and using the Console Setup menu to configure system networking and set up dual stacking, add the name servers and both IP protocol default gateways in general network settings (option 2 on the menu), then add both IP address, with netmasks as aliases, on the primary network interface (option 1 on the menu).

If using the Console Setup menu to set up IPv6 on an already IPv4-configured system, add the v6 default gateway in general network, then add the IPv6 IP address with netmask as an alias on the primary interface.

Connecting to the UI IPv6 Address

Unlike IPv4, you must enter the IPv6 address with a square bracket preceding and following the address. You cannot enter the host name assigned to the TrueNAS system to access the UI. For example, enter [ffff:ff:59f8:100::12] into the URL field of the browser window to access the UI.

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.

Configuring an SSH Connection

Both replication to a remote server and rsync tasks require configuring an SSH connection credential. When both systems are using IPv6 addresses and the protocol to communicate, you must enclose the IPv6 address in square brackets when defining the remote system URL in the TrueNAS URL field on the New SSH Connection configuration screen.

Managing Network Settings (Enterprise HA)

TrueNAS Enterprise
The instructions in the article only apply to TrueNAS Enterprise (HA) systems.

Configuring Enterprise (HA) Network Settings

Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready, click Sync to Peer to haveTrueNAS apply settings to controller 2.

TrueNAS Enterprise (HA) systems use three static IP addresses for access to the UI:

VIP to provide UI access regardless of which controller is active. If your system fails over from controller 1 to 2, then fails back over to controller 1 later you might not know which controller is active.
IP for controller 1. Do not use DHCP to assign the IP address! If enabled, DHCP assigns an IP to the primary network interface on non-HA systems. Disable DHCP, and then manually enter the Controller 1 static IP address your network administrator assigned for this controller.
IP for Controller 2. Manually enter the second IP address assigned for this controller.

Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.

TrueNAS safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes. This is to prevent users from breaking their network connection in TrueNAS.

To configure network settings on controller 1:

Disable the failover service. Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure. Select Enable Automatic Failover to clear the checkmark, then select Default TruNAS Controller to enable it, and then click Save to disable failover.
Go to System > Network and click Settings to edit the global network settings. Add the controller and virtual host names and update any other network settings.
Edit the primary network interface to add failover settings. Click on the more_vert to the right of the the primary interface eno1, and select Edit to open the Edit Interface screen for this interface.
Figure 1: Edit Network Interface Settings
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.
Figure 2: Edit Failover Setting
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.
Figure 3: Re-Enable Failover

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.
Figure 4: Failover Sync To Peer

Network Configuration Screens

The Network Configuration widget shows the general networking settings for the TrueNAS system.

Newtork Configuration Widget — Figure 1: Network Configuration Widget

DNS Servers shows the IP addresses for the primary and secondary name servers.

Default Route shows the IP address for the default gateway.

The remaining general network settings shown in the widget are the system host name, domain name, HTTP proxy address, any configured service announcement, additional domains, the host name database, and the outbound network setting.

Settings opens the Edit Global Configuration screen, where you can add or change global network settings for the TrueNAS system.

You can lose your TrueNAS connection if you change the network interface that the web interface uses! You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Do not configure network settings to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers. This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started.

Edit Global Configuration Screen

The Edit Global Configuration screen manages general network settings for your TrueNAS system that are not specific to any interface.

Hostname and Domain Settings

Many of these fields have default values, but users can change them to meet local network requirements.

Some fields only show in the Edit Global Configuration screen when the appropriate hardware is present.

Setting	Description
Hostname	Sets the system host name. The default value is truenas. Some applications require setting this to a value other than truenas. If using Active Directory or SMB services, the hostname is also used as the NetBIOS name and must comply with NetBIOS naming restrictions: maximum 15 characters, cannot contain `\ / : * ? " < >
Inherit domain from DHCP	Sets the domain to be inherited from DHCP when selected.
Hostname (TrueNAS Controller 2)	Sets the system host name for a second controller in High Availability (HA) systems where there is a second TrueNAS controller. A name can consist of upper and lower case alphanumeric and allowed special characters dot (.) and/or dash (-).
Hostname (Virtual)	Sets a virtual host name that shows when using a virtual host, for example, on a TrueNAS High Availability system. Also used as the Kerberos principal name. Enter the fully qualified host name plus the domain name. A name can consist of upper and lower case alphanumeric and the allowed special characters, dot (.) and/or dash (-).
Domain	Enter a system domain name, for example, example.com.
Additional Domains	Specifies additional domains to search. Separate entries by pressing `Enter`. Adding search domains can cause slow DNS lookups.

Service Announcement Settings

Setting	Description
NetBIOS-NS	Sets TrueNAS to use a legacy NetBIOS name server. This advertises the SMB service NetBIOS name. Setting this might be required for legacy SMB1 clients to discover the server. When advertised, the server appears in Network Neighborhood.
mDNS	Sets TrueNAS to use multicast DNS. This uses the system host name to advertise enabled and running services. For example, it controls whether the server shows under Network on MacOS clients.
WS-Discovery	Sets TrueNAS to use the SMB service NetBIOS name to advertise the server to WS-Discovery clients. This can cause the computer to appear in the Network Neighborhood of modern Windows operating systems.

DNS Servers and Default Gateway Settings

Figure 3: Global Configuration Nameserver Settings

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.

Outbound Network and Other Settings

The Outbound Network setting should match the preferred system services allowed to communicate externally for your use case. The Other Settings allow setting an HTTP proxy and any host name database preferences.

Figure 4: Global Configuration Outbound Settings

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: Provides instructions on configuring a static route using the TrueNAS web UI.

Static Routes Screens: The Static Routes widget displays existing static routes or sets up new ones.

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.
Figure 1: Add Static Routes
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: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.

IPMI Screens: Provides information on the Network screen IPMI widget and configuration screen.

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.

Configuring IPMI

Click on the channel you wish to edit to open the IPMI configuration screen.

TrueNAS Enterprise
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.
Figure 3: IPMI Remote Controller Selection for HA systems
Select the controller you want to configure IPMI settings for or use the identify light feature on. All IPMI configuration changes and the identify light feature apply only to the selected controller.

To configure a static IPv4 connection for IPMI, do not select DHCP.

Enter the IPv4 address for the IPMI web interface. Enter the IPv4 address subnet mask in IPv4 Netmask, such as 255.255.240.0. Enter the IPv4 connection default gateway.

If needed, enter the VLAN identifier of the IPMI interface in VLAN ID. We recommend configuring IPMI on a separate VLAN that is isolated from the main TrueNAS network. This allows for IPMI access even if the main network is down.

Click Save to update IPMI configuration.

After saving the configuration, access the IPMI interface using a web browser and the IP address specified in Network > IPMI or click to open the IPMI manager in a new browser tab. The management interface prompts for login credentials. IPMI utility appearance and available functions vary by hardware. Refer to your IPMI device documentation to learn the default administrator account credentials.

After logging in to the management interface, change the default administrative user name. We recommend setting a strong IPMI password. Refer to your IPMI device documentation for password requirements. Document your password in a secure location.

Alternately, enter a new password in IPMI Password Reset on the IPMI configuration screen.

IPMI Alerts

Click Show Events on the IPMI widget to show the IPMI Events log.

Use the Alert Settings Screen under the Hardware category to adjust IPMI alerts. Configure the minimum warning level and frequency to display IPMI alerts in the TrueNAS UI.

The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues. Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL. Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.

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.

Network with IPMI — Figure 1: Network screen with IPMI channels.

Click to open the IPMI manager in a new browser tab where users can log into the IPMI web interface.

Click to go to the IPMI configuration screen.

Click Show Events to show the IPMI Events log.

IPMI Configuration Screen

Click on the channel you wish to edit to open the configuration screen.

TrueNAS Enterprise
On TrueNAS Enterprise High Availability (HA) systems, the IPMI configuration screen includes the Remote Controller section.
Figure 4: IPMI Remote Controller Selection for HA systems

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.

Using Default Network Settings

Leave Use default network settings selected while creating a new instance to allow TrueNAS to automatically assign the default network bridge. This is the simplest way to allow communication between containers and the TrueNAS host.

Creating a Bridge - Single Physical Interface

If your system only has a single physical interface, and you prefer to manually configure a network bridge, complete these steps.

Before making network interface changes:

Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.

Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.

Adding a Bridge

To set up a bridge interface:

Go to Apps and the Containers screens to verify all apps and containers are stopped. If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM. Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Figure 2: Network Interfaces and Global Configuration Widgets
Click the more_vert icon for the interface, to open the Edit Interface screen. Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
Figure 3: Edit Interface for a Bridge
Click Add to open the Add Interface screen. Configure the interface:
Figure 4: Bridge Interface Settings
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.

Troubleshooting Network Changes

Ensure that there are no currently running applications.
Stop any running VMs.
(Optional) Go to Services. Click edit Configure to view the current configuration of sharing services, including SMB and NFS. Stop any services that have a bind IP address matching the bridge IP address. Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.

After adding the bridge and to assign the bridge to a VM or container, go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget. Click Add and select the new bridge interface from the dropdown list.

You can now access your TrueNAS storage from the container. You might have to set up shares or users with home directories to access certain files.

Assigning a Secondary NIC: Multiple Physical Interfaces

If you have more than one NIC on your system, you can assign container traffic to a secondary NIC. Configure the secondary interface as described in Managing Interfaces before attaching it to an instance.

If you are creating a new instance, use the Network settings to disable Use default network Settings and select the secondary NIC from Macvlan NICs.

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.
Figure 7: Add NIC

VM Access Examples

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.

Windows Example

Windows VMs can access TrueNAS storage using FTP and SMB.

The example below shows the Windows VM accessing an SMB share 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.

Additional Network Articles

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: Information on managing local user accounts in TrueNAS.

Managing Users: Provides instructions on adding and managing administrator and user accounts.
Users Screens: Provides information on the Users screens and settings in TrueNAS.

Using Administrator Logins: Explains role-based administrator logins and functions. Provides instructions on configuring SSH and working with the admin and root user passwords.

Groups: Information on managing local user groups in TrueNAS.

Managing Groups: Provides instructions on adding and managing groups.
Groups Screens: Provides information on the Groups screens and settings.

Privileges: Information on managing privileges in TrueNAS.

Managing Privileges: Provides instructions on adding and managing groups privileges.
Privileges Screens: Provides information on the Privileges screens and settings.

Directory Services: Tutorials to configure the various directory service credentials.

Configuring Active Directory: Provides instructions on configuring Active Directory (AD) in TrueNAS.
Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.
Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.
Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.
Kerberos Realms Screens: Provides information on the **Kerberos Realms** widget and configuration screen settings.
Kerberos Keytab Screens: Provides information on the **Kerberos Keytabs** screen and widget settings.
Directory Services Screens: Describes the screens and fields in the TrueNAS Directory Services section.

Backup Credentials: Backup credential tutorials to integrate TrueNAS with cloud storage providers through SSH connections and keypairs.

Adding Cloud Credentials: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.
Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.
Cloud Credentials Screens: Provides information on the Cloud Credentials screens and settings.
SSH Screens: Provides information on the SSH Connections and SSH Keypairs screens, widgets, and settings.
Backup Credentials Screens: Information on backup credential screens and settings to integrate TrueNAS with cloud storage providers by setting up SSH connections and keypairs.

Certificates: Information about adding and managing certificates, CSRs, CAs, and ACME DNS-Authenticators in TrueNAS.

Managing Certificates: Provides information on adding or managing certificates in TrueNAS.
Managing Certificate Signing Requests: Provides basic instructions on adding and managing certificate signing requests (CSRs) in TrueNAS.
Adding ACME DNS Authenticators: Provides basic instructions on adding and managing ACME DNS authenticators in TrueNAS.
Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.
Certificates Screens: Provides information on the Certificates screens and settings.
Certificate Signing Requests Screens: Provides information on the Certificates Signing Requests screens and settings.
ACME DNS-Authenticators Screens: Provides information on the ACME DNS-Authenticators widget and settings.

KMIP: Information on Key Management Interoperability Protocol (KMIP) configuration in TrueNAS Enterprise.

Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.
KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS Enterprise.

Users

Managing Users: Provides instructions on adding and managing administrator and user accounts.

Users Screens: Provides information on the Users screens and settings in TrueNAS.

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.

Creating an Administrator User Account

Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.

The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations. Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin). Configure appropriate administrative privileges for each admin account. Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user. If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete. See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s). Go to Credentials > Users, click on the user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.

Assigning Administrative Group Privileges

TrueNAS 24.04 or newer supports administrator privileges for role-based administrator accounts. Users can create new administrator accounts with limited privileges based on their needs. Predefined administrator roles are read-only, share admin, and the default full access administrator account. See Using Administrator Logins for more information.

Go to Credentials > Groups and select the row for primary group of the admin user to expand it. Click 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 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.

Creating User Accounts

User Access Levels

SMB Access is the default user access type assigned to user accounts that require access to SMB shares. It uses the user account credentials to access data shared with SMB.

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.
Setting up SSH Access
These options only show when you select the SSH Access option. Only Full Admin users who require SSH session access should be configured with this option.
Select the optional Allow SSH Login with Password if you want to allow this user to log in to an SSH session and not be prompted to enter a password. This is not recommended as it presents a security vulnerability!
Manually enter or copy/paste the public key in the Public SSH Key field to assign a public SSH key to the user for key-based authentication.
Do not enter the private key!
After adding authentication settings, complete the SSH access by setting up sudo commands in the next step.
Always keep a backup of an SSH public key if you are using one.
Enter additional details for the user. Setting options change based on the access option selected in Allow Access. If this is an SMB share user, leave the default SMB Access selected.
When Shell Access and SSH Access are assigned to the user, the Shell and Sudo Command settings show in the Additional Details section.
Figure 3: Additional Details Settings
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.
Figure 4: User Group Settings
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list. Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID. TrueNAS suggests a user ID starting at 3000, but you can change it if you wish. We recommend using an ID of 3000 or greater for non-built-in users.
(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty. This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory. If set to this path, TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Figure 5: User Home Directory Settings
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory. The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset. After clicking on a dataset, the Create Dataset option activates. Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist. pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure. This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did. This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign. For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task. See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished. Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password. To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Figure 6: Add User Sudo Command Options
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password. To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.

Disabling a Password

To disable a password, select the user, click Edit, and then select Disable Password. Note that Disable Password is not available when SMB Access is enabled. Setting Disable Password hides the Password widget, and TrueNAS removes any existing password from the account. TrueNAS restricts the account from password-based logins for services like SMB shares and SSH sessions.

To disable all password-based functionality for the account, select the Lock User option on the Access widget. This toggles to Unlock User when locked.

Adding Home Directories

You can add a home directory to a new or an existing user account. You can create a dataset to use for user home directories if one does not exist before you add or edit a user. You can also create one while adding or editing the user.

To add a home directory to an existing user, go to Credentials > Users, click on the user row, and then click Edit to open the Edit User screen. Scroll down to the Home Directory option, click in the field to show the settings.

Select Create Home Directory, then enter or browse to select the path to the dataset for home directories in Home Directory. For example, change /var/empty/ to the path to a new dataset.For example, /tank/homedirs.

Accept the default permissions or clear the checkmark to select the level of permissions you want to apply. We recommend leaving the default selections, Read/Write/Execute selected for the user home directory.

Click Save. TrueNAS creates a new home directory for the user.

Editing User Accounts

To edit an existing user account, go to Credentials > Users. Click anywhere on the user row, then click Edit to open the Edit User configuration screen. See Users Screen for details on all settings.

Setting Up and Using API Keys

To view API keys that are linked to different user accounts, go to the Settings icon on the top toolbar and select My API Keys.

You can also go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.

If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.

The Users API Keys screen shows a table of all API keys linked to user accounts on your TrueNAS.

You can edit or delete your API keys in the User API Keys screen. Click Edit to open the Edit API Key screen. Click Delete to delete an API key.

Adding an API Key

To add an API key for a user, select the user row on the Users table, and then click Add API Key to open the Add API Key screen. Enter a name for the key, select the user in the Username dropdown list field if not already populated with the correct username, and click Save.

To set the API key to expire, clear the checkmark in Non-expiring, then select the date using the calendar option in the field to set when this key expires.

After setting the date, click Save. The Access widget for this user shows the API Key icon and the View API Keys link.

Clearing Two-Factor Authentication for a User

Administrators can clear two-factor authentication (2FA) for a user from the Users screen. This is typically necessary when:

A user has lost access to their authenticator device (lost phone, broken device, etc.)
A user cannot generate valid 2FA codes due to device time synchronization issues
A user needs to switch to a different authenticator app or device
Troubleshooting 2FA-related login problems

Clearing 2FA should only be done when necessary, as it temporarily reduces account security. When Global 2FA is enabled, users are prompted to reconfigure 2FA on their next login.

To clear 2FA for a user:

Go to Credentials > Users.
Click on the user row to select the user whose 2FA needs to be cleared.
On the Access widget, click Clear Two-Factor Authentication.
Figure 8: Access Widget with Clear 2FA Button
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.
Figure 9: Clear Two-Factor Authentication Dialog
Click Clear to confirm, or Cancel to abort the operation.

After clearing, the user can log in without 2FA codes. If Global 2FA is enabled on the system, the user is prompted to set up 2FA again on their next login.

User Self-Clearing vs Admin Clearing

Users can also remove their own 2FA configuration using the Settings menu:

User self-clearing: The logged-in user accesses Settings > Two-Factor Authentication and clicks Unset 2FA Secret. This allows users to manage their own 2FA settings.
Admin clearing: Administrators use Credentials > Users > Access Widget > Clear Two-Factor Authentication to clear 2FA for another user. This is specifically for helping users who cannot access their accounts.

For more information on 2FA configuration and management, see Managing Global 2FA.

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.

User Search Options

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.

Users Screen Basic search — Figure 2: Users Screen Basic Search

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.

Users screen advanced search interface with filters — Figure 3: Users Screen Advanced Search Options

Switch to Basic option shows in the search field when in advanced search mode. Switch to Basic returns to the basic user table view.

User Table

The Users screen user table shows the Username, Full Name, Type, and pre-defined administrator role assigned to the user (Access) for each user. Username, Full Name, and Type sort the list in 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.
share	Indicates the user has WebShare access.
power	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.

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.

Figure 4: Users Screen Profile Widget

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.

User password widget showing password status — Figure 5: Users Screen Password Widget

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.

One-time password generation window — Figure 6: One Time Password Window

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.
share	Indicates the user has WebShare access.
power	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.

Figure 7: Clear Two-Factor Authentication Dialog

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.

Add or Edit User Screens

The Add User and Edit User configuration screens show the same setting options, but a few options are not editable. Built-in users (except the root user) do not show the home directory settings, but all new users created and the SMB share smbguest user do.

Username and Allow Access Settings

The Username and Allow Access settings specify the username and level of access (privileges granted) given to the user. Each access option changes the settings shown in other sections of the Add User and Edit User screens.

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: SMB Access - The default option is pre-selected. WebShare Access - Adds WebShare access for the user. TrueNAS Access - Shows the Select Role dropdown and the custom roles link that opens the TrueNAS documentation article on pre-defined administrator roles. Shell Access - Adds the Shell and Sudo Commands options to the Additional Details section. SSH Access - Deactivates the Shell Access option, but shows the Shell and Sudo Commands options found with Shell Access. Shows the Allow SSH Login with Password (not recommended) option, and the Public SSH Key field.
Select Role	Shows after selecting TrueNAS Access. Each role adds the appropriate group to the Groups option under Additional Details.

Authentication Settings

Authentication settings show after selecting Shell Access or SSH Access options under Allow Access. Password shows for all access options.

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!

Additional Details

The edit 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.
Email	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. Create Home Directory is preselected by default, and the Create Home Directory Under mount path and file browser fields show after clicking edit. 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. Default Permissions is preselected by default. It sets the home directory ACL permissions to 700 or owner - all, others-none. 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: Allowed Sudo Commands - Limits this user to the specific `sudo` commands entered in the field. Enter allowed commands as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands, and prompts the user for their account password. Allow all sudo commands - Grants the user permission to use all `sudo` commands, but prompts the user to enter their password. Allowed sudo commands with no password - Limits the `sudo` commands the user can enter without seeing a prompt to enter their password. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands. Exercise caution when allowing `sudo` commands without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks. Allow all sudo commands with no password - Gives this user administrator permissions and the ability to use all `sudo` commands without seeing a prompt to enter their password. This is not recommended!

Shell Options

You can set a specific shell for the user from the Shell dropdown list options.

Shell	Description
nologin	Use when creating a system account or creating a user account that can authenticate with shares, but cannot log in to the TrueNAS system using SSH. In rare cases, where a TrueNAS 13.0 user has `/etc/netcli` set as the user shell, and then after migrating to TrueNAS 24.04 or later, the user shell changes to `/user/sbin/nologin` as the default.
bash	Opens a Bourne Again shell for the GNU operating system.
rbash	Opens a Restricted bash shell.
dash	Opens a Debian Almquist shell.
sh	Opens a Bourne shell.
tmux	Opens a terminal multiplexer shell.
zsh	Opens a Z shell.
TrueNAS CLI	Opens Shell in the CLI. Eliminates the need to enter `cli` at the Shell system prompt to enter the TrueNAS CLI. Enter `ls` to see the list of namespaces.
TrueNAS Console	Opens Shell in the Console Setup menu. Eliminates the need to enter `menu`. This option provides the user access to the Linux and TrueNAS CLI shells.

Using Administrator Logins

Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.

The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations. Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin). Configure appropriate administrative privileges for each admin account. Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user. If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete. See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s). Go to Credentials > Users, click on the user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.

Administrator accounts have roles and privileges that are FIPS compliant and allow more control over access to TrueNAS functions.

TrueNAS has three predefined admin user account levels:

Full Admin - Assigned to the local administrator account created by the system when clean installing TrueNAS using an iso file. Also assigned when manually creating an admin user if logged in as the root user account after upgrading from a pre-22.12.3 release of TrueNAS or migrating from FreeBSD- to Linux-based TrueNAS releases.
Sharing Admin - Assigned to users responsible for only managing shares (SMB, NFS, iSCSI). This user can create shares and the datasets for shares, start/restart the share service, and modify the ACL for the share dataset.
Readonly Admin - Assigned to users that can monitor the system but not make changes to settings.

For more information on the different administrator scenarios users can encounter, read Logging In for the First Time.

Changing Administrator Account Passwords

Administrator passwords can be changed on the Edit User screen or, if currently logged in as that admin user, by clicking the Settings account_circle icon on the top toolbar and clicking Change Password.

Click on the Change Password dialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.

Click on the visibility_off icon to display entered passwords. To stop displaying the password, click on the visibility icon.

Configuring Administrative Privileges

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.

Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.

Click Save.

After creating a new group, click 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.

Allowing Sudo Commands

As a security hardening feature, administrator accounts in Linux-based TrueNAS releases (22.12.0 or newer) cannot execute certain root-level commands in a shell or SSH session by default. If a user attempts to execute one of these commands without root-level access, TrueNAS returns a command not found error.

Administrative users who need to execute root-level commands to complete a task should temporarily enable sudo permissions for that user by going to Credentials and editing the user or group to allow some or all sudo commands. For best security, enable only the required commands to perform the task and require password authentication, unless the task or app prevents it. Disable sudo permissions when the task completes and you no longer need them.

Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password, and Allow all sudo commands with no password, on the Add Group and Edit Group screens, grant limited root-like permissions using the sudo command. Use Allowed sudo commands or Allowed sudo commands with no password to list specific sudo commands to allow. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press Enter after each command.

To allow full access to sudo commands, select either Allow all sudo commands or Allow all sudo commands with no password. If you allow sudo commands with password protection, TrueNAS prompts you for a password the first time you enter a sudo command, but not again in the same session. Disable these settings after completing the task to return to a security-hardened system.

Do not allow sudo permissions for read-only administrators.

Disabling Root and Admin User Passwords

As a security measure, the root user is no longer the default account and TrueNAS disables the root password when you create the truenas_admin or admin user during installation.

Do not disable the default admin account, root, and any custom admin account passwords at the same time. If all root and administrator account passwords become disabled at the same time and the web interface session times out, a one-time sign-in screen allows access to the system.

Figure 4: Reset Root Password Sign-In Screen

Enter and confirm a password to gain access to the UI. After logging in, immediately go to Credentials > Users to enable the password for an administrator account before the session times out again. TrueNAS does not save the temporary password as a new password or enable the admin or root passwords. It only provides one-time access to the UI.

Disabling a password for UI login also disables it for SSH access.

Accessing the System Through an SSH Session

To enable SSH access to the system as an admin user (or root user), you must first configure the SSH service.

Go to System > Services, then click Edit for the SSH service.
Enter the groups (truenas_admin, root, etc.) you want to enable for password authentication in the Password Login Groups field.
Enable Allow Password Authentication.
Click Save and restart the SSH service.

Now you must verify the user configuration options to allow SSH access.

Using the Root User in SSH

If you want to SSH into the system as the root:

Go to Credentials > Users and click the root user, then click Edit.
Make sure Disable Password is disabled. If the root user has Disable Password enabled, you cannot use it to gain SSH access to the system.
Click Save.

Allowing an Admin User to Enter Commands in SSH

To allow an admin user to issue commands in an SSH session:

Go to Credentials > Users, click the admin user, then click Edit.
Select SSH Access.
Enable SSH password login enabled under Authentication.
Click Save.
Disable this after completing the SSH session to return to a security-hardened system.

SSH User Validation
Users must have a home directory and shell access to log in with SSH.

Two-Factor Authentication (2FA) and Administrator Account Log In

To use two-factor authentication with an administrator account, configure and enable SSH service to allow SSH access, then configure two-factor authentication. If you have the root user configured with a password and it is enabled, you can SSH into the system as the root user. Disable the root user password and only use a local administrator account for more security.

Administrator Logins and TrueCommand

Administrator logins work with TrueCommand, but you need to set up the TrueNAS connection using an API key.

Groups

Managing Groups: Provides instructions on adding and managing groups.

Groups Screens: Provides information on the Groups screens and settings.

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.

View Existing Groups

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.

Adding a New Group

To create a group, go to Credentials > Groups and click Add.

Enter a unique number for the group ID in GID. TrueNAS uses this to identify a Unix group. Enter a number above 3000 for a group with user accounts or enter the default port number as the GID for a system service.

Enter a name for the group. The group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?) greater or less than (<) (>), equal (=). The dollar sign ($) can be the last character in a group name.

Group names must also align with the Portable Filename Character Set defined by The Open Group.

To allow Samba permissions and authentication to use this group, select SMB Group.

Using the same group ID (GID) is not permitted as it can create confusion. The operating system treats it as the same group, even if a different name is assigned.

Select SMB Group to make this group available for permissions editors over SMB protocol, and add the share ACL editor. This is not used for SMB authentication or when determining the user session token or internal permissions checks.

Click Save.

Managing Groups

Click anywhere on a row to expand that group and show the group management buttons.

Use Members to manage membership and Edit or Delete to manage the group.

Update Members

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.

Edit Group

To edit an existing group, go to Credentials > Groups, expand the group entry, and click Edit to open the Edit Group configuration screen. See Groups Screens for details on all settings.

Groups Screens

Groups Screen

The Credentials > Groups screen displays a list of groups configured on the screen. By default, built-in groups are hidden until you make them visible.

When enabled, the Show Built-In Groups toggle turns blue and shows built-in groups. When disabled, the toggle turns grey and shows only non-built-in groups.

The Credentials > Groups screen displays the No groups screen if no groups other than built-in groups are configured on the system.

Add opens the Add Group configuration screen.

Privileges opens the Privileges screen

Clicking on the expand_more 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.

Add and Edit Group Screens

The Add Group and Edit Group screens show the same settings but the GID is not editable after saving changes on the Add Group screen. Add opens the Add Group configuration screen. The Edit icon opens the Edit Group screen.

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. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Using sudo prompts the user for their account password.
Allow all sudo commands	Enable to give group members permission to use all sudo commands. Using sudo prompts the user for their account password.
Allowed sudo commands with no password	Permits group memebers to enter the specific allowed sudo commands entered in this field without requiring the user to enter their password. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Exercise caution when allowing sudo commands without password prompts. Recommended to limit the privilege to trusted users and specific commands to minimize security risks.
Allow all sudo commands with no password	Not recommended. Enable to give group members the ability to enter all sudo commands without needing to enter a password. Does not require specifying allowed commands.
SMB Group	Select to make the group available for permissions editors over SMB protocol (and the share ACL editor). Not used for SMB authentication or determining the user session token or internal permissions checks.

Update Members Screen

The Update Members screen manages group permissions and access for large numbers of user accounts.

The right arrow adds a user account to the group after selecting the user. The left arrow removes the selected user account from the group. Hold Ctrl while clicking each entry to select multiple groups.

Privileges

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: Provides instructions on adding and managing groups privileges.

Privileges Screens: Provides information on the Privileges screens and settings.

Managing Privileges

Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges ares:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/execute permissions) to the user.

Active Directory can provision groups in TrueNAS or you can add new groups that you assign to users in AD. After adding a group, verify or edit the privilege(s) granted to the users in the group.

Adding a Privilege

To configure a new privilege, go to Credentials > Groups, click on Privileges to open the Privileges screen.

Click Add to define a new privilege. For example, if you want to create an group with the ability to only perform and manage backup, replication, or some other task. You can create a new privilege to customize the functional access you want to grant.

On the New Privilege screen:

Enter a name for the new privilege. Names can include the dash (-) or underscore (_) special characters, and upper and lowercase alphanumeric characters. Make the name descriptive of the privilege. For example, Replication Administrator, Backup Administrator, iSCSI Share Admin, etc. You can create a privilege that can only manage iSCSI shares or one that can manage applications based on the selections made in the Roles field.
Click in the Local Groups field to see a list of groups on the system. To add another group, click in the field to select another group. Click the x to the right of the group name to remove that group from the privilege.
Click the down arrow at the right of the Roles field to show the list of roles configured on the system. Select all roles to include. Use the scroll bar at the right of the field to see all options.
Select Web Shell Access to allow access to the shell screen in the TrueNAS UI.
Click Save to create the new privilege.

Users assigned to the group show on the Users screen with the new privilege granted to the user in the Roles column, and the new group shows on the Groups screen with privilege listed in the Roles column.

Privileges Screens

Privileges Screen

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.

Add and Edit Privilege Screens

The new and edit privilege screens show the same settings but not all settings are editable.

TrueNAS Enterprise
Enterprise-licensed systems can enable Active Directory to provision groups in TrueNAS. To make this possible, join Active Directory, then go to System > Advanced Settings > Access and enable the Allow Directory Service users to access WebUI option. After enabling this, the Edit Privilege screen lists AD groups on the Groups dropdown list. See Allowing Directory Service Users to Access the UI for more information.

Add opens the New Privilege screen. The Edit icon opens the Edit Privilege screen for the selected privilege.

Setting	Description
Name	Assigns the name entered to a new privilege. Names can include the dash (-) or underscore(_) special characters, and upper and lowercase alphanumeric characters. Enter a descriptive name for the privilege. Name shows on the Edit Privilege screen but is not editable.
Groups	Shows a list of groups configured on the system. Select a group from the dropdown list after clicking in the field. The privilege is applied to the selected group(s).
Roles	Select from a dropdown list of all available roles available to assign to the new privilege or change an existing privilege. Only the Readonly Admin, Sharing Admin, or Full Admin roles are supported in the web UI.
Web Shell Access	Select to grant the privilege access to the System > Shell screen. To open a shell for an app, container, or VM, the user also needs the write role for that resource type (`APPS_WRITE`, `CONTAINER_WRITE`, or `VM_WRITE`), which the Full Admin role includes.

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.

About Directory Services

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: Provides instructions on configuring Active Directory (AD) in TrueNAS.

Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.

Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.

Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.

Kerberos Realms Screens: Provides information on the **Kerberos Realms** widget and configuration screen settings.

Kerberos Keytab Screens: Provides information on the **Kerberos Keytabs** screen and widget settings.

Directory Services Screens: Describes the screens and fields in the TrueNAS Directory Services section.

Configuring Active Directory

The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.

You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.

Configuring TrueNAS Active Directory Access

The Active Directory (AD) service shares resources in a Windows network. AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.

When joined to an AD domain, you can use domain users and groups in local ACLs on files and directories. You can also set up shares to act as a file server.

Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.

Users can configure AD services on Windows or Unix-like operating systems using Samba version 4.

Preparing to Configure AD in TrueNAS

Before configuring Active Directory (AD) in TrueNAS:

You need to know the hostname assigned to the TrueNAS system. The default value is truenas.

The Domain Account Name default is Administrator, or enter a name for TrueNAS to generate as the computer account upon domain join. Enter the password for this account.

Verify name resolution. Go to Network > Global Network Settings to verify your TrueNAS network DNS name servers are configured with the target domain controller address that you plan to add on the Active Directory screen.
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.
Set time synchronization

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.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
Microsoft Reserved Words: ANONYMOUS, AUTHENTICATED USER, BATCH, BUILTIN, DIALUP, DOMAIN, ENTERPRISE, INTERACTIVE, INTERNET, LOCAL, NETWORK, NULL, PROXY, RESTRICTED, SELF, SERVER, USERS, WORLD
RFC 852 Reserved Words: GATEWAY, GW, TAC
If you encounter validation errors when joining Active Directory or configuring SMB services, verify that your NetBIOS Name, Workgroup, and Domain Name comply with these requirements.

Setting Time Synchronization

Active Directory relies on the time-sensitive Kerberos protocol. TrueNAS adds the AD domain controller with the PDC Emulator FSMO Role as the preferred NTP server during the domain join process. If your environment requires something different, go to System > Advanced Settings, click Add to open the NTP Servers screen, then add a new or edit a listed server.

Keep the local system time sync within five (5) minutes of the AD domain controller time in a default AD environment.

Use an external time source when configuring a virtualized domain controller. TrueNAS generates alerts if the system time gets out of sync with the AD domain controller time.

TrueNAS has a few options to ensure both systems are synchronized. Either:

Go to System > General Settings, click Settings in the Localization widget, and set Timezone to the value that matches the location of the AD domain controller.
Figure 1: Timezone Options

Set the system BIOS to either local time or universal time.

Connecting to the Active Directory Domain

Before you begin, modify the system DNS server settings. Take a screenshot of your current settings to refer to if you need to revert to pre-AD settings for any reason. Change the nameserver 1 setting to the IP address of the AD server and clear the other name server settings. Make sure the domain name is set to something other than the default value truenas.

To connect TrueNAS to Active Directory:

Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select Active Directory from the Configuration Type dropdown list.
Enter the Basic Configuration settings:
Figure 2: AD Basic Configuration
- 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:
Figure 3: Credential Configuration
- 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:
Figure 4: AD Configuration
- 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.

I don't see any AD information!

TrueNAS can take a few minutes to populate the Active Directory information after configuration. To check the AD join progress, open the Task Manager in the upper-right corner. TrueNAS displays any errors during the join process in the Task Manager.

When the import completes, AD users and groups become available while configuring basic dataset permissions or an ACL with TrueNAS cache enabled (enabled by default).

Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab. TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.

Understanding IDMAP Backends

When customizing IDMAP settings, you can select from several backend options. Each backend uses a different method to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs:

AD - Reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions.
AUTORID - Automatically allocates UID and GID ranges for each domain. Useful for environments with multiple trusted domains.
LDAP - Reads and writes UID / GID mapping tables from an external LDAP server.
NSS - Uses the Name Service Switch (NSS) to retrieve Unix user and group information from local or network sources.
RFC2307 - Reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only.
RID - Uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low.
TDB - Stores ID mappings in a local Trivial Database (TDB) file. Allocates new UIDs and GIDs as needed. Useful for standalone servers but not recommended for multi-server environments as mappings are not shared.

For most environments, the default RID backend provides consistent, reliable ID mapping without additional configuration.

Troubleshooting - Resyncing the Cache

If the cache becomes out of sync or fewer users than expected are available in the permissions editors, click Settings in the Active Directory widget, then click Rebuild Directory Service Cache to resync the cache.

The name in TrueNAS Hostname should match the name in Hostname on the Network > Global Configuration screen.

Disabling Active Directory

To disable your AD server connection without deleting your configuration or leaving the AD domain, click Settings in the Active Directory widget to open the Active Directory settings screen. Clear the Enable Service checkbox and click Save to disable the AD service.

This returns you to the main Directory Services screen.

Click Configure Directory Services to open the Directory Services Configuration form with your existing configuration settings. Select Enable Service again, and click Save to reactivate your connection to your AD server.

Leaving Active Directory

Users must cleanly leave an Active Directory for TrueNAS to delete the configuration. To cleanly leave AD, click Leave Domain on the Active Directory settings screen to remove the AD object. Remove the computer account and associated DNS records from the Active Directory.

If the AD server moves or shuts down without you using Leave Domain, TrueNAS does not remove the AD object, and you have to clean up the Active Directory.

Configuring LDAP

TrueNAS has an Open LDAP client for accessing the information on an LDAP server. An LDAP server provides directory services for finding network resources like users and their associated permissions.

You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.

Configuring LDAP

To configure TrueNAS to use an LDAP directory server:

Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select LDAP from the Configuration Type dropdown list.
Enter the Basic Configuration settings:
Figure 1: LDAP Basic Configuration
- 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:
Figure 2: LDAP Configuration
- Enter the LDAP server URLs in Server URLs. Required. Separate multiple entries by pressing Enter. If using a cloud service LDAP server, do not include the full URL.
- Enter the LDAP server base DN in Base DN. Required. This is the top level of the LDAP directory tree to use when searching for resources. For example, dc=example,dc=org.
- (Optional) Select the Start TLS checkbox if needed for your environment.
- (Optional) Select the Validate Certificates checkbox to verify certificate authenticity when connecting to the LDAP server.
- Select the LDAP NSS schema from the Schema dropdown list. Required. Options are RFC2307 or RFC2307BIS.
(Optional) Configure auxiliary parameters:
Select Use Standard Auxiliary Parameters to use default auxiliary parameters. Selected by default.
To customize auxiliary parameters, clear Use Standard Auxiliary Parameters to reveal the Auxiliary Parameters text field where you can enter custom options for nslcd.conf.
(Optional) Configure search bases:
Select Use Standard Search Bases to use default search bases. Selected by default.
To customize search bases, clear Use Standard Search Bases to reveal additional configuration options: User Base DN, Group Base DN, and Netgroup Base DN.
(Optional) Configure attribute maps:
Select Use Standard Attribute Maps to use default attribute mappings. Selected by default.
To customize attribute maps, clear Use Standard Attribute Maps to reveal four subsections for customization:
- LDAP Password Attributes - Enter custom password attribute mappings.
- LDAP Shadow Attributes - Enter custom shadow attribute mappings.
- LDAP Group Attributes - Enter custom group attribute mappings.
- LDAP Net Group Attributes - Enter custom net group attribute mappings.
Click Save.

Disabling LDAP

To disable LDAP but not remove the configuration, clear the Enable Service checkbox. The main Directory Services screen returns to the default view showing the option to configure directory services. To enable LDAP again, click Configure Directory Services to open the Directory Services Configuration form with your saved LDAP configuration. Select Enable Service again to reactivate your LDAP directory server configuration.

Removing LDAP from TrueNAS

To remove the LDAP configuration, click Settings on the LDAP widget to open the Directory Services Configuration screen. Click Clear Config to open the confirmation dialog.

Figure 3: Clear Directory Services Configuration 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.

Does IPA work with SMB?

IPA can work with SMB shares when properly configured. IPA includes integrated Samba support and can provide user and group information for SMB authentication. TrueNAS validates the full certificate chain when certificate validation is enabled. TrueNAS does not support non-CA certificates when certificate validation is required.

Configuring IPA

Configure TrueNAS to use an IPA directory server:

Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select IPA from the Configuration Type dropdown list.
Enter the Basic Configuration settings:
Figure 1: IPA Basic Options
- 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:
Figure 2: Credential Configuration
- 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:
Figure 3: IPA Configuration
- 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:
Figure 4: IPA SMB Configuration
Select Use Default SMB Domain Configuration to use default SMB domain settings. Selected by default.
To customize SMB domain settings, clear Use Default SMB Domain Configuration to reveal additional configuration options: Name, Domain Name, Range Low, Range High, and Domain SID.
Click Save.

Disabling IPA

Clear the Enable Service checkbox to disable the IPA directory server. This does not remove the configuration. The main Directory Services screen returns to the default view showing the option to configure directory services.

Click Configure Directory Services to open the Directory Services Configuration form with the saved IPA configuration to enable IPA again. Select Enable Service again to reactivate your IPA directory server configuration.

Removing IPA from TrueNAS

Click Settings to open the IPA screen to remove the IPA configuration. Clear all settings and click Save.

Configuring Kerberos

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).

If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD. You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.

After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help. For more information on Kerberos settings refer to the MIT Kerberos Documentation.

Kerberos uses realms and keytabs to authenticate clients and servers. A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client. By default, TrueNAS creates a Kerberos realm for the local system. A keytab (“key table”) is a file that stores encryption keys for authentication.

TrueNAS allows users to configure general Kerberos settings, as well as realms and keytabs.

Kerberos Realms

TrueNAS automatically generates a realm after you configure AD.

To configure Kerberos realms:

Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Realms widget to open the Add Kerberos Realm screen.
Enter the realm name in Realm. Required. Enter the name as a domain name, for example, example.com.
(Optional) Enter the Key Distribution Center name in KDC. The KDC acts as the third-party authentication service for Kerberos. If left blank, TrueNAS uses DNS discovery to locate the KDC. Separate multiple values by pressing Enter.
(Optional) Enter the primary KDC in Primary KDC. The Kerberos client uses this KDC when acquiring credentials if the current KDC fails with a bad password error. This is valuable for domains with hub-and-spoke topology.
(Optional) Enter the server that performs all database changes in Admin Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
(Optional) Enter the server that performs all password changes in Password Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
Click Save.

Kerberos Keytabs

TrueNAS automatically generates a keytab after you configure AD.

A Kerberos keytab is a file containing one or more Kerberos principals with their associated encryption keys. TrueNAS automatically generates a keytab during the Active Directory domain join process. The keytab principals are typically associated with the TrueNAS host computer account.

Keytabs allow authentication without requiring password storage. TrueNAS does not store the Active Directory or LDAP administrator account password in the system database after the keytab is created.

Adding a Keytab to TrueNAS

After generating the keytab:

Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Keytabs widget to open the Add Kerberos Keytab screen.
Enter a name for the keytab in Name. If configured, TrueNAS populates this field with what it detects in Active Directory.
Browse to the keytab file in Kerberos Keytab and upload it.
Click Save.

Using a Keytab with Active Directory or LDAP

To configure AD to use a keytab, go to the Directory Services screen, click Settings in the Active Directory widget, and select the keytab using the Kerberos Principal dropdown list.

The keytab must correspond to the computer account created during the domain join process.

To configure LDAP to use a keytab principal, click Settings in the LDAP widget and select the keytab using the Kerberos Principal dropdown list.

Synchronizing Keytabs with Active Directory

When TrueNAS is joined to Active Directory, you can synchronize Kerberos keytabs with Active Directory to ensure keytab data remains current.

To synchronize keytabs:

Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Sync in the Kerberos Keytabs widget header to open the synchronization confirmation dialog.
Figure 1: Sync Keytab Confirmation Dialog
Click Sync to synchronize the keytabs with Active Directory.

The Sync button only appears when the system is joined to Active Directory.

Kerberos Settings

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

The Kerberos Settings screen is available in Advanced Settings for configuring auxiliary parameters.

To access Kerberos Settings:

Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Settings in the Kerberos Settings widget to open the Kerberos Settings screen.
(Optional) Enter additional Kerberos application settings in Appdefaults Auxiliary Parameters. See the appdefaults section of krb.conf(5) for available settings and usage syntax.
(Optional) Enter additional Kerberos library settings in Libdefaults Auxiliary Parameters. See the libdefaults section of krb.conf(5) for available settings and usage syntax.
Click Save.

Kerberos Realms Screens

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).

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.

KerberosRealmsWidget

Add opens the Add Kerberos Realm configuration screen.

Click on any instance to open the Edit Kerberos Realm screen.

Click on the Kerberos Realms widget header to open the Kerberos Realms screen.

Kerberos Realms Screen

The Kerberos Settings configuration screen is available for advanced Kerberos configuration.

KerberosRealmsScreen

Actions includes the option to Add a new realm. Add opens the Add Kerberos Realm screen.

The button opens the Edit Kerberos Realm screen for the selected realm. The button opens a delete confirmation dialog for the Kerberos realm.

Add and Edit Kerberos Realm Screens

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

AddKerberosRealmScreen

Setting	Description
Realm	(Required) Enter the name of the realm as a domain name, For example, example.com. AD configured TrueNAS systems pre-populate this field with the required information.
KDC	Enter the name of the Key Distribution Center (KDC). The KDC acts as the third-party authentication service for Kerberos. If left blank, TrueNAS uses DNS discovery to locate the KDC. Separate multiple values by pressing `Enter`. For example, kdc1.example.com press `Enter` then kdc2.example.com.
Primary KDC	Specifies the primary Key Distribution Center (KDC) for the realm. The Kerberos client uses this KDC when acquiring credentials if the current KDC fails with a bad password error. This is valuable for domains with hub-and-spoke topology where password changes slowly propagate from the hub to the spoke.
Admin Server	Define the server that performs all database changes. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing `Enter`.
Password Server	Define the server that performs all password changes. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing `Enter`.

Kerberos Keytab Screens

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).

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.

KerberosKeytabWidget

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.

Figure 1: Sync Keytab Confirmation Dialog

Click on any keytab instance to open the Edit Kerberos Keytab screen.

The Kerberos Keytab widget header opens the Kerberos Keytabs screen.

Kerberos Keytab Screen

The Kerberos Keytabs screen displays a list view of keytabs configured on your TrueNAS system.

KerberosKeytabsScreen

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.
Figure 2: Sync Keytab Confirmation Dialog

The more_vert button opens the actions options for the selected keytab. Options are Edit which opens the Edit Kerberos Keytab screen for the selected keytab, and Delete that opens a delete confirmation dialog.

Add and Edit Kerberos Keytab Screens

The settings found on the Add Kerberos Keytab and Edit Kerberos Keytab screens are the same.

Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!

AddKerberosKeytabScreen

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

Directory Services Configuration Screen

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:

Basic Configuration
Credential Configuration

Directory Service-specific settings:

Active Directory Configuration
- AD Trusted Domain Configuration
- IDMAP Configuration
LDAP Configuration
IPA Configuration
- SMB Domain Configuration

Basic Configuration

The Basic Configuration settings show settings common to the three directory services available in TrueNAS: Active Directory, LDAP, and IPA (formerly FreeIPA).

Directory Services Configuration -Basic Settings — Figure 2: Directory Services Configuration - Basic Settings

Basic Configuration Settings

Setting	Description
Configuration Type	Sets the type of directory service. Options are: Active Directory, LDAP, and IPA. Each option shows the Credential Configuration settings and changes the setting options shown for each type of directory service.
Enable Service	Enables the directory service when selected. If TrueNAS has never joined the specified domain (IPA or Active Directory), enabling causes TrueNAS to attempt to join the domain. NOTE: The domain join process for Active Directory and IPA makes changes to the domain, such as creating a new computer account for the TrueNAS server and creating DNS records for TrueNAS. Enabled by default. Leave disabled to deactivate the configuration without deleting it and allow reenabling it later without reconfiguring it. The screen returns to the default settings and provides the option to configure AD, LDAP, or IPA.
Enable Account Cache	Enables backend caching for user and group lists. When enabled, directory services users and groups are presented as choices in the UI dropdowns and in API responses for user and group queries. Also controls whether users and groups appear in getent results. Disable to reduce load on the directory server when necessary. Enabled by default.
Enable DNS Updates	Allows TrueNAS to automatically register and update its DNS records on the DNS server for the domain when its IP address changes. Uses Kerberos authentication to verify TrueNAS has permission to update its own records. Enabled by default. Disable only if your DNS server does not support dynamic updates or if DNS is managed manually.
Timeout (seconds)	The number of seconds before the directory service connection times out. Valid range is 1-40 seconds. The timeout value for DNS queries that are performed as part of the join process and NETWORK_TIMEOUT for LDAP requests (5-60 seconds).
Kerberos Realm	Specifies the name of the Kerberos realm used for authentication to the directory service, for example, EXAMPLE.COM. When left empty, Kerberos is not used for binding to the directory service, but when joining an Active Directory or IPA domain for the first time, the realm is detected and configured automatically if not specified.

Credential Configuration

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.

Figure 3: Credential Configuration Kerberos User

Figure 4: Credential Configuration Kerberos Principal

Kerberos Credential Configuration Settings

Setting	Description
Credential Type	Sets the credential type for authentication. Options: Kerberos User or Kerberos Principal. Kerberos User shows the Username and Password settings. Kerberos Principal shows the Kerberos Principal dropdown list. Kerberos Principal, and Kerberos User.
Username	Username of the account to use to create a Kerberos ticket for authentication to directory services. This account must exist on the domain controller. A Kerberos ticket is a time-limited encrypted credential issued by the domain controller that allows TrueNAS to authenticate to domain services 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 issued by the domain controller that allows TrueNAS to authenticate to domain services without transmitting passwords over the network.
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.

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.

Figure 5: LDAP Plain Credential Configuration

Figure 6: LDAP MTLS 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.

Active Directory Configuration

The Active Directory Configuration section settings define the connection parameters and domain-specific options.

Active Directory Configuration Settings

Setting	Description
TrueNAS Hostname	The hostname for the TrueNAS system to register in Active Directory, for example, truenasnyc. This value must match the Hostname setting on the Network > Global Configuration screen and cannot exceed 15 characters. Cannot contain these special characters: \ / : * ? " < >
Domain Name	The full DNS domain name of the Active Directory domain name (for example, mydomain.internal) or child domain (for example, sales.example.com) if configuring access to a child domain. This must not be a domain controller!
Site Name	The Active Directory site where the TrueNAS server is located. TrueNAS detects this automatically during the domain join process.
Computer Account OU	The organizational unit (OU) where the TrueNAS computer object is created when joining the Active Directory domain for the first time. The OU string includes the distinguished name (DN) of the Computer Account OU. For example, OU=Computers,DC=example,DC=com. Use this setting to override the default organizational unit (OU) in which the TrueNAS computer account is created during the domain join. Use it to set a custom location for TrueNAS computer accounts.
Use Default Domain	Removes 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. Note that using this setting can cause collisions with local user account names. Controls if the system removes the domain prefix from Active Directory user and group names. If enabled, users appear as “administrator” instead of “EXAMPLE\administrator”. In most cases, disable this (default) to avoid name conflicts between Active Directory and local accounts.

Active Directory Trusted Domain Configuration

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

Figure 11: Trusted Domain AD IDMAP Backend Configuration

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

Figure 12: Trusted Domain LDAP IDMAP Backend Configuration

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

Trusted Domain RFC2307 IDMAP Backend Configuration — Figure 13: Trusted Domain RFC-2307 IDMAP Backend Configuration

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

Trusted Domain LDAP RID Backend Configuration — Figure 14: Trusted Domain RID IDMAP Backend Configuration

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.

IDMAP Configuration (AD)

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.

IDMAP Builtin 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 Configuration Builtin Settings

Setting	Description
Name	Short name for the joined 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.

IDMAP Domain Settings

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

Figure 16: IDMAP Domain AD Configuration

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

Figure 17: IDMAP Domain LDAP Configuration

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

IDMAP Domain RFC-2307 Configuration — Figure 18: IDMAP Domain RFC2307 Configuration

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

Figure 19: IDMAP Domain RID Configuration

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.

LDAP Configuration

The LDAP Configuration section settings define the connection parameters and validation options.

LDAP Configuration Settings

Setting	Description
Server URLs	Specifies the hostname or IP address of the LDAP server. Separate entries by pressing `Enter`. Multiple URLs create an LDAP failover priority list. If a host does not respond, TrueNAS tries the next host until it establishes a connection. If using a cloud service LDAP server, do not include the full URL.
Base DN	The top level of the LDAP directory tree to use when searching for resources. For example, dc=test,dc=org.
Start TLS	Encrypts the LDAP connection with STARTTLS on the default LDAP port 389. Options for encrypting the LDAP connection: OFF - Does not encrypt the LDAP connection. ON- Encrypts the LDAP connection with SSL on port 636. START_TLS- Encrypts the LDAP connection with STARTTLS on the default LDAP port 389 .
Validate Certificates	Verifies certificate authenticity when connecting to the LDAP server, when enabled.
Schema	Sets the LDAP NSS schema. Options are RFC2307 or RFC2307BIS. RFC2307 — Standard Unix attributes schema. Compatible with most LDAP servers, including OpenLDAP. RFC2307BIS — Extended schema that supports nested group membership. Use if your LDAP server is configured with RFC2307bis.

Auxiliary Parameters (LDAP)

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.

Search Bases

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.

Search Bases Settings

Setting	Description
User Base DN	Sets the base DN to use when searching for LDAP user accounts. Restricts user searches to a specific directory subtree. For example, ou=users,dc=example,dc=org.
Group Base DN	Sets the base DN to use when searching for LDAP group accounts. Restricts group searches to a specific directory subtree. For example, ou=groups,dc=example,dc=org.
Netgroup Base DN	Sets the base DN to use when searching for LDAP group accounts. Restricts netgroup searches to a specific directory subtree. For example, ou=netgroups,dc=example,dc=org.

Attribute Maps

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.

IPA Configuration

The IPA Configuration settings define the connection parameters and validation options.

IPA Configuration Settings

Setting	Description
Target Server	Specifies the name of the IPA server (hostname or IP address) that TrueNAS uses to build URLs when it joins or leaves the IPA domain. For example: ipa.example.internal.
TrueNAS Hostname	Specifies the hostname of the TrueNAS server to register in IPA during the join process. For example: truenasnyc.
Domain	Specifies the domain name of the IPA Server. For example: ipa.internal.
Base DN	Specifies the base distinguished name (base DN) to use when performing LDAP operations. For example: dc=example,dc=com.
Validate Certificates	Verifies certificate authenticity when connecting to the IPA server. When enabled, TrueNAS validates the full certificate chain. TrueNAS does not support non-CA certificates when certificate validation is required. When disabled, TrueNAS does not validate certificates from the remote LDAP server. It is better to use valid certificates or import them into the TrueNAS server trusted certificate store.

SMB Domain Configuration

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.

SMB Domain Configuration Settings

Setting	Description
Name	Short name for the IPA domain used for SMB access. Typically matches the IPA domain name.
Domain Name	Name of the SMB domain as defined in the IPA configuration for the IPA domain to which TrueNAS is joined.
Range Low	Specifies the lowest UID or GID that the IPA maps natively.
Range High	Specifies the highest UID or GID that IPA maps natively.
Domain SID	Specifies the domain SID for the IPA domain to which TrueNAS is joined.

Advanced 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.

Directory Services Advanced SettingsCards — Figure 30: Directory Services Advanced Settings Cards

Each Kerberos card shows the realms or keytabs configured in TrueNAS.

Add on the Kerberos cards opens configuration screens for each Kerberos function:

Add Kerberos Realm
Add Kerberos Keytab

Add Kerberos Realms

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.

Add Kerberos Keytabs

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: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.

Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.

Cloud Credentials Screens: Provides information on the Cloud Credentials screens and settings.

SSH Screens: Provides information on the SSH Connections and SSH Keypairs screens, widgets, and settings.

Backup Credentials Screens: Information on backup credential screens and settings to integrate TrueNAS with cloud storage providers by setting up SSH connections and keypairs.

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:

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.

Adding a Cloud Credential

We recommend you open another browser tab and log into the cloud storage provider account you intend to link with TrueNAS.

Some TrueNAS providers credentials require entering additional information generated while creating the provider account. For example, the Storj iX account produces an access and secret key that must be entered in the Cloud Credential screen to create the credential.

Have the authentication information required by your cloud storage provider on hand to make the process easier. Authentication information can include but is not limited to user credentials, access tokens, and access and security keys.

To add a cloud credential:

Select the cloud service from the Provider dropdown list. The provider required authentication option settings display.
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.

Adding Storj Cloud Credentials

Storj iX is the default cloud storage provider in TrueNAS.

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.

Creating the Storj iX Account

Setting Up S3 Access

After creating your Storj iX account, add S3 access credentials.

Click Access Keys to open the Access Keys dashboard, then click New Access Key.
Figure 3: Storj Access Keys Screen
The New Access window opens.
Enter the name you want to use for this credential. Select S3 Credentials for access type, then click Next.
Figure 4: Storj New Access Key Window
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.
Figure 5: Storj Access Permissions Window.
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.
Figure 6: Storj Access Select Permissions
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.
Figure 7: Storj Access Select Buckets.
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.
Figure 8: Storj Create Access Select Duration
d. Review access details and then click Create Access.
Figure 9: Storj Create Access Confirm Details
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.
Figure 10: Storj S3 Credentials Generated
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.
Figure 11: Verify Cloud Credentials
Click Save.

Creating a TrueNAS Storj Bucket

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.
Figure 12: TrueCloud Add New Bucket Settings
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.

Adding Amazon S3 Cloud Credentials

When adding an Amazon S3 cloud credential, you can either use the default authentication settings or advanced settings if you want to include endpoint settings.

To add a cloud credential for Amazon S3, select Amazon S3 in Provider, enter a name and then:

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

Adding Cloud Credentials that Authenticate with OAuth

Cloud storage providers using OAuth as an authentication method are Box, Dropbox, Google Drive, Google Photos, pCloud, and Yandex. Some providers like Google Drive and pCloud use additional settings to authenticate credentials.

Open the Cloud Credentials screen, select the name of the cloud storage provider on the Provider dropdown list, enter a name for the credential, and then:

Enter the provider account email in OAuth Client ID and the password for that user account in OAuth Client Secret.
Click Log In To Provider. The Authentication window opens. Click Proceed to open the OAuth credential account sign-in window.
Yandex displays a cookies message you must accept before you can enter credentials.
Enter the provider account user name and password to verify the credentials.
(Optional) Enter the value for any additional authentication method. For pCloud, enter the pCloud host name for the host you connect to in Hostname. For Google Drive when connecting to Team Drive, enter the Google Drive top-level folder ID.

Enter the access token from the provider if not populated by the provider after OAuth authentication. Obtaining the access token varies by provider.

Provider	Access Token
Box	For more information on the user access token for Box click here. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
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.

Adding BackBlaze B2 Cloud Credentials

BackBlaze B2 uses an application key and key ID to authenticate credentials.

Open the Cloud Credentials screen, select BackBlaze B2 in Provider, enter a name and then:

Log into the BackBlaze account, go to the App Keys page, and add a new application key. Copy and paste this into Key ID.
Generate a new application key on the BackBlaze B2 website. From the App Keys page, add a new application key. Copy the application Key string Application Key.
Click Verify Credentials.
Click Save.

Adding Google Cloud Storage Credentials

Google Cloud Storage uses a service account JSON file to authenticate credentials.

Open the Cloud Credentials screen, select Google Cloud Storage in Provider, enter a name and then:

Go to your Google Cloud Storage website to download this file to the TrueNAS server. The Google Cloud Platform Console creates the file.
Click Choose File to browse the server to locate the downloaded JSON file and upload it. The file populates Preview JSON Service Account Key For help uploading a Google Service Account credential file click here.
Click Verify Credentials.
Click Save.

Adding OpenStack Swift Cloud Credentials

OpenStack Swift authentication credentials change based on selections made in AuthVersion. All options use the user name, API key or password, and authentication URL, and can use the optional endpoint settings. For more information on OpenStack Swift settings, see rclone documentation.

Open the Cloud Credentials screen, select OpenStack Swift Cloud in Provider, enter a name for the credential and then:

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.
Set Auth(vx) to V1 or V2
If set to Auth(vX), V1 or V2:
a. (Required) Enter the OS_TENANT_NAME from an OpenStack credentials file in Tenant Name.
b. Enter the ID in Tenant ID. Required for v2.
c. (Optional) Enter the alternative authentication token in Auth Token.
d. Enter a region name in Region Name
e. (Optional) Enter the URL in Storage URL.
f. (Required) Select the service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended.
Set Auth(vx) to V3
If set to v3 the Advanced Options settings displayed change.
a. (Optional) Enter the user ID to log into OpenStack. Leave blank to log into most Swift systems.
b. (Optional) Enter the User Domain.
c. (Required) Enter the OS_TENANT_NAME from an OpenStack credentials file in Tenant Name.
d. Enter the ID in Tenant ID. Required for v2 and v3 and (optional) enter a Tenant Domain.
e. (Optional) Enter the alternative authentication token in Auth Token.
f. Enter a region name in Region Name
g. (Optional) Enter the URL in Storage URL.
h. (Required) Select the service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended.
Click Verify Credentials.
Click Save.

Adding Microsoft OneDrive Credentials

Microsoft OneDrive uses OAuth authentication to connect TrueNAS to your cloud account.

Open the Cloud Credentials screen, select Microsoft OneDrive in Provider, enter a name and then:

Click Log In To provider to open the Microsoft sign-in page in a new window. You can confirm the intended authorization in the new window.
Confirm the authorization to enter your Microsoft login information. After logging in to your account, Microsoft prompts you to give TrueNAS access to your Microsoft information.
Give TrueNAS access to your Microsoft account and close the pop-up window. Your Cloud Credentials wizard should now say Logged In To Provider and have populated OAuth Client ID, OAuth Client Secret, Access Token, and Drive Account Type fields.
(Optional) Select an entry from the Drives List drop-down menu. This will also populate the Drive ID field.
Choose a drive from your OneDrive account and enter the ID in this field. If you selected an entry for Drives List, this field should already be populated with a valid ID.
Click Save.

Using Automatic Authentication

Some providers can automatically populate the required authentication strings by logging in to the account.

To automatically configure the credential, click Login to Provider and enter your account user name and password.

AutomaticAuthenticationSCALE

We recommend verifying the credential before saving it.

Adding SSH Credentials

The SSH Connections and SSH Keypairs widgets on the Backup Credentials screen display a list of SSH connections and key pairs configured on the system. Using these widgets, users can establish Secure Socket Shell (SSH) connections.

You must also configure and activate the SSH Service to allow SSH access.

These SSH credentials are used to manage SSH connections specifically for automated tasks such as replication, backups, cloud sync, or other system-to-system operations. You can generate, store, and manage SSH key pairs and define SSH connections that TrueNAS uses for these automated processes. The key pairs managed here are not tied to individual user but are instead used by the system for secure communication with other systems or services.

For individual user SSH access, configure SSH keys in the user account settings under Credentials > Users.

Creating an SSH Connection

To begin setting up an SSH connection, go to Credentials > Backup Credentials.

Click Add on the SSH Connections widget to open the configuration screen:

Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
Figure 1: Name and Method Settings
Enter the authentication settings.
Figure 2: 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.
Figure 3: More Options Settings
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.

Configuring a Semi-Automatic SSH Connection

The procedure in this section covers the semi-automatic setup method for creating an SSH connection with another TrueNAS system.

Semi-automatic simplifies setting up an SSH connection with another TrueNAS system without logging in to that system to transfer SSH keys. This requires an SSH key pair on the local system and administrator account credentials for the remote TrueNAS. You must configure the remote system to allow root access with SSH. You can generate the key pair as part of the semiautomatic configuration or a manually created one using SSH Keypairs.

Click Add on the SSH Connections widget to open the configuration screen:

Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
Figure 4: Name and Method Settings
Enter the authentication settings.
Figure 5: 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.
Figure 6: More Options Settings
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.

Configuring a Manual SSH Connection

The instructions in this section cover how to set up an SSH connection to a non-TrueNAS system. To manually set up an SSH connection, you must copy a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.

Click Add on the SSH Connections widget to open the configuration screen:

Enter a name for the connection, then select Manual from the Setup Method dropdown list.
Figure 7: Manual Name and Method
Enter the authentication settings.
Figure 8: Manual 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.
Figure 9: Manual More Options
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.

Adding a Public SSH Key to an Admin User Account

This procedure covers adding a public SSH key to the admin account on the TrueNAS system and generating a new SSH Keypair to add to the remote system (TrueNAS or other).

Copy the SSH public key text or download it to a text file:
Log in to the TrueNAS system that generated the SSH key pair and go to Credentials > Backup Credentials.
Click on the name of the key pair on the SSH Keypairs widget to open the key pair for the SSH connection.
Copy the text of the public SSH key or download the public key as a text file.
Add the public key to the admin account on the system where you want to register the public key.
Log in to the TrueNAS system where you want to register the public key and go to Credentials > Users.
Edit the admin account. Select the user, and click Edit to open the Edit User screen.
Figure 10: Adding SSH Settings
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.

Generating SSH Keypairs

TrueNAS generates and stores RSA-encrypted SSH public and private key pairs on the SSH Keypairs widget found on the Credentials > Backup Credentials screen. Key pairs are generally used when configuring SSH Connections or SFTP Cloud Credentials. TrueNAS does not support encrypted key pairs or key pairs with passphrases.

TrueNAS automatically generates key pairs as needed when creating new SSH Connections or Replication tasks.

To manually create a new key pair:

Click Add on the SSH Keypairs widget.
Click Generate New on the SSH Keypairs screen.
Give the new key pair a unique name and click Save. The key pair displays on the SSH Keypairs widget.

Click the vertical ellipsis more_vert at the bottom of the SSH Keypairs configuration screen to download these strings as text files for later use.

Cloud Credentials Screens

These providers are supported for Cloud Sync tasks in TrueNAS:

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.

Figure 2: Cloud Credentials Widget No Credentials

Add opens the Cloud Credentials configuration screen.

Cloud Credentials 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.

Name and Provider Settings

The selection in Provider changes the Authentication settings.

Setting	Description
Provider	(Required) Default is set to Storj. Select the cloud storage provider from the options on the dropdown list.
Name	Enter a name for this cloud credential. For example, cloud1 or amazon1.

Storj iX Credential

Storj authentication includes going to the Storj iX sign-in screen to either create a new Storj iX account or log into an existing Storj iX account. After configuring the Storj account in the Storj-iX portal, return to TrueNAS to enter the S3 credentials provided by Storj.

Storj iX Authentication Settings

Setting	Description
Signup for account	Link to the Storj iX account sign-up page where you either create a new account or sign in to your Storj iX account.
Access Key ID	Enter the alphanumeric key provided by Storj when you create the S3 account access associated with the storage buckets added in Storj.
Secret Access Key	Enter the alphanumeric key provided by Storj when you create the S3 account access associated with the storage buckets added in Storj.
Endpoint	(Optional) Enter a custom Storj S3-compatible endpoint to use a specific tier, such as Global or Select. Automatically set to the default.

Amazon S3 Credential

Amazon S3 has basic authentication and advanced authentication settings. This section provides information on the basic authentication settings.

Amazon S3 Authentication Settings

Setting	Description
Access Key ID	Enter the alphanumeric key that is between 5 and 20 characters for the Amazon Web Services Key ID. Find this on Amazon AWS by going through My account > Security Credentials > Access Keys (Access Key ID and Secret Access Key).
Secret Access Key	Enter the alphanumeric key that is between 8 and 40 characters for the Amazon Web Services password. If you cannot find the Secret Access Key, go to My Account > Security Credentials > Access Keys and create a new key pair.

Amazon S3 Advanced Authentication Options

This section provides information on Amazon S3 advanced authentication settings for endpoints. The basic authentication settings are required when using the advanced settings.

Amazon S3 Advanced Authentication Settings

Setting	Description
Maximum Upload Ports	Enter a value to define the maximum number of chunks for a multipart upload. Setting a maximum is necessary if a service does not support the 10,000 chunk AWS S3 specification.
Endpoint URL	(Optional) When using AWS, you can leave the endpoint field empty to use the default endpoint for the region and automatically fetch available buckets, or enter an S3 API endpoint URL. Refer to the AWS Documentation for a list of Simple Storage Service Website Endpoints.
Region	(Optional) Enter an AWS resources in a geographic area. Leave empty to detect the correct public region for the bucket. Entering a private region name allows interacting with Amazon buckets created in that region. For example, enter us-gov-east-1 to discover buckets created in the eastern AWS GovCloud region.
Disable Endpoint Region	Select to prevent automatic detection of the bucket region. Select only if your AWS provider does not support regions.
Use Signature Version 2	Select to force using Signature Version 2 to sign API requests. Select only if your AWS provider does not support default version 4 signatures.

BackBlaze B2 Credential

This section provides information on the BackBlaze B2 authentication settings.

Backblaze B2 Authentication Settings

Setting	Description
Key ID	Enter or copy and paste the alphanumeric Backblaze B2 Application Key ID string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.
Application Key	Enter or copy and paste the alphanumeric Backblaze B2 Application Key string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.

OAuth and Access Token Authentication Credentials

Several cloud storage providers use OAuth authentication and a required access token to authenticate the cloud storage account. Providers using these methods are Box, Dropbox, Google Photos, pCloud, and Yandex.

OAuth and Access Token Authentication Settings

Use Login to Provider to enter the account username and password.

Setting	Description
OAuth Client ID	Enter the public identifier for the cloud application.
OAuth Client Secret	Enter the secret phrase known only to the cloud application and the authorization server.
Token	Enter a User Access Token for Box. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
Hostname	(Optional) pCloud only. Enter the host name to connect to.

FTP and SFTP Credentials

FTP and SFTP cloud storage providers use host name, port, and user credentials to authenticate accounts. SMTP uses SSH hosts, port, and user credentials and also uses a private key.

Figure 9: Host, Port User Credentials Authentication

FTP and SFTP Authentication Settings

Setting	Description
Host	Enter the FTP host name, or for SFTP, the SSH host name to connect. For example, ftp.example.com.
Port	Enter the FTP or for SFTPP, the SSH port number. Leave blank to use the default port 21 for FTP or 22 for SFTP.
Username	Enter a username on the FTP or for the SFTP host system, the SSJ user name. This user must already exist on the host.
Password	Enter the password for the user account.
Private Key ID	(SFTP only) Import the private key from an existing SSH keypair or, if no keypairs exist on the system, select Add on the SSH Keypairs widget to open the SSH Keypairs screen. Enter a name, and then click Generate New to create a new SSH key for this credential.

Google Cloud Storage Credential

Google Cloud Storage authentication uses a Google service account JSON key credential file to authenticate the account.

Google Cloud Storage Authentication Settings

Setting	Description
Service Account Key	Use Choose File to browse to the file location on the server. Opens a file browser to select the Google service account key credential file generated by the Google Cloud Platform Console to authenticate the account.
Preview JSON Service Account Key	Shows the JSON file downloaded to the system server from Google Cloud Storage and uploaded with Choose File.

Google Drive Credential

Google Drive also uses OAuth authentication, a required access token, and a team drive ID to authenticate accounts. Google Drive adds one additional authentication setting to the general OAuth settings.

Google Drive Authentication Settings

Use Login to Provider to enter the account username and password.

Setting	Description
OAuth Client ID	Enter the public identifier for the cloud application.
OAuth Client Secret	Enter the secret phrase known only to the cloud application and the authorization server.
Access Token	(Required) Token created with Google Drive. Access Tokens expire periodically, so you must refresh them.
Team Drive ID	(Optional) Google Drive only when connecting to a team drive, and is the top-level folder ID for the team drive.

HTTP Credential

HTTP uses an HTTP host URL to authenticate account credentials. It is a read-only client that supports directory listings from popular web servers like Apache and Nginx.

Hubic Credential

Hubic uses an access token to authenticate the account. Enter the token generated by a Hubic account into the Access Token field.

Microsoft Azure Blob Storage Credential

Microsoft Azure Blob Storage uses the Microsoft Azure account name and account key to authenticate the account credentials.

CloudCredentialsMSAzureBlogStorageAuth

Microsoft Azure Blob Storage Authentication Settings

Setting	Description
Account Name	Enter the Microsoft Azure account name.
Account Key	Enter the base64 encoded key for Azure account.
Endpoint	Enter an endpoint. For example, blob.core.usgovcloudapi.net.

OpenStack Swift Credential

OpenStack Swift uses several required settings to authenticate credential accounts. The AuthVersion setting selection changes setting options displayed in Advanced Options.

OpenStack Swift Authentication Settings

Setting	Description
User Name	(Required) Enter the OpenStack user name (OS_USERNAME) from an OpenStack credentials file.
API Key or Password	(Required) Enter the Openstack API key or password. This is the OS_PASSWORD from an OpenStack credentials file.
Authentication URL	(Required) Enter the authentication URL for the server. This is the OS_AUTH_URL from an OpenStack credentials file.
AuthVersion	Authentication version set to default. Click on field to specify different authentication version (rclone documentation).

OpenStack Authentication Advanced Options

The Authentication Advanced Options screen shows different options based on the AuthVersion setting. Auto(vX), v1, and v2 use the same advanced authentication settings.

Figure 14: OpenStack Swift Authentication Advanced

Auto(vx), V1 and V2 Authentication Settings

Setting	Description
Tenant Name	Enter the OS_TENANT_NAME from an OpenStack credentials file.
Tenant ID	(Optional for v1 auth) Enter the tenant ID Enter the tenant ID. For more information, see rclone documentation.
Auth Token	(Optional) Enter the auth token from alternate authentication. For more information, see rclone documentation.
Region Name	(Optional) Enter the region name. For more information, see rclone documentation.
Storage URL	(Optional) Enter the storage URL. For more information, see rclone documentation.
Endpoint Type	Select service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended. For more information, see rclone documentation.

V3 Authentication Settings

Setting AuthVersion to v3 shows additional authentication settings.

Figure 15: OpenStack Swift Authentication Advanced V3

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 Credential

WebDAV uses a URL, service type, and user credentials to authenticate the cloud account credentials.

WebDAV Authentication Settings

Setting	Description
URL	(Required) Enter the URL of the HTTP host to connect to.
WebDAV Service	(Required) Select the name of the WebDAV site, service, or software used from the dropdown list. Options are NEXTCLOUD, OWNCLOUD, SHAREPOINT, or OTHER.
Username	(Required) Enter the WebDAV account user name.
Password	(Required) Enter the WebDAV account password.

Microsoft OneDrive Credential

Microsoft OneDrive uses several required settings to authenticate credential accounts.

Figure 17: Microsoft OneDrive Cloud Credentials

Microsoft OneDrive Authentication Settings

Setting	Description
Access Token	(Required) Enter the OneDrive access token found in your Microsoft account.
Drives List	Enter the drives and IDs registered to your Microsoft account. Entering a value in this field also fills out the Drive ID field.
Drive Account Type	(Required) Select the type of OneDrive account you are authorizing. This is automatically selected when you log in to your Microsoft account.
Drive ID	Enter a unique drive identifier or keep the auto-filled entry that appeared when you filled out the Drives List field above.

SSH Screens

The Backup Credentials screen displays the SSH Connections and SSH Keypairs widgets.

These widgets are used to manage SSH credentials specifically for automated tasks such as replication, backups, cloud sync, or other system-to-system operations. You can generate, store, and manage SSH key pairs and define SSH connections that TrueNAS uses for these automated processes. The key pairs managed here are not tied to individual user logins, but are instead used by the system for secure communication with other systems or services.

For individual user SSH access, configure SSH keys in the user account settings under Credentials > Users.

You must also configure and activate the SSH Service to allow SSH access.

SSH Connection and Keypairs Widgets

The SSH Connections and SSH Keypairs widgets display a list of SSH connections and key pairs configured on the system.

The SSH Connections widget allows users to establish Secure Socket Shell (SSH) connections. The SSH Keypairs widget allows users to generate SSH key pairs required to authenticate the identity of a user or process that wants to access the system using SSH protocol.

Add in the SSH Connections widget opens the SSH Connections configuration window. The connection name on the widget is a link that opens the SSH Connections configuration screen already populated with the saved settings for the selected connection. The more_vert icon shows options to Edit or Delete the connection. Delete opens a dialog with an option to delete the associated SSH Keypair.

SSH Connections Screens

The settings on the SSH Connections configuration screens are the same whether you add a new connection or edit an existing connection.

Name and Method Settings

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:

Semi-automatic (TrueNAS only) - Select to simplify setting up an SSH connection with another TrueNAS or FreeNAS system without logging into that system to transfer SSH keys. The default is set to Semi-automatic (TrueNAS only).

Manual - Select to enter all settings when setting up an SSH connection with a non-TrueNAS server. Displays other setting options required to manually configure an SSH connection. Requires copying a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.

Authentication - Semi-Automatic Method Settings

These authentication settings show when Setup Method is Semi-automatic (TrueNAS only).

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.

Authentication - Manual Method Settings

These authentication settings show when Setup Method is Manual. You must copy a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.

Figure 4: Manual Authentication Settings

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.

More Options Settings

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 more_vert icon shows a dropdown list of options: Download, Edit, and Delete. Download saves the public and private key strings as text files for later use. Edit opens the SSH keypair configuration screen. Delete opens the delete dialog. If the keypair is used by SSH Connections, deleting it also deletes those connections. Click Confirm and then Delete to remove the stored key pairs from the system.

SSH Keypairs Screen

The SSH Keypairs configuration screen displays the same settings for both add and edit options. Click Add to open a new configuration form, or click on an existing key pair to open the configuration screen populated with the settings for the selected key pair.

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 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: Provides information on adding or managing certificates in TrueNAS.

Managing Certificate Signing Requests: Provides basic instructions on adding and managing certificate signing requests (CSRs) in TrueNAS.

Adding ACME DNS Authenticators: Provides basic instructions on adding and managing ACME DNS authenticators in TrueNAS.

Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.

Certificates Screens: Provides information on the Certificates screens and settings.

Certificate Signing Requests Screens: Provides information on the Certificates Signing Requests screens and settings.

ACME DNS-Authenticators Screens: Provides information on the ACME DNS-Authenticators widget and settings.

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.

TrueNAS Connect Certificate

The TrueNAS Connect service automatically creates a default truenas_connect_ certificate after registering your TrueNAS system in the TrueNAS Connect service. The certificate shows in the Certificates widget on the Credentials > Certificates screen.

This certificate provides secure SSL access between the TrueNAS server and the TrueNAS Connect service. If not listed on the Certificates screen, choose the truenas_default certificate. For apps where certificates are used, you should see and be able to select the TNC certificate and get a full secure connection for the apps.

Adding Certificates

By default, TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import and edit existing certificates.

To add a certificate to TrueNAS, click Import on the Certificates widget to open the Import Certificates screen.

First, enter a name as a certificate identifier. A name can include the dash (-) or underscore (_) special characters.

Select Add To Trusted Store if you want to add the imported certificate to the trusted store in TrueNAS.

Copy/paste the certificate into the Certificate field, and the private key part of the certificate into the Private Key field.

Enter or copy/paste the password associated with the private key into the Password and Confirm Password fields.

Click Import to add the certificate to TrueNAS.

Editing a Certificate

TrueNAS allows you to rename a certificate or to add it to the TrueNAS trusted store.

Click on the more_vert icon, then select Edit on the dropdown list. The Edit Certificate screen for that certificate opens.

Enter a new name for the certificate.

Select Add To Trusted Store to add the certificate to the TrueNAS trusted store.

Click Save.

Downloading the Certificate or Public Key

Click on the more_vert icon, then select Edit or Download on the dropdown list. On the Edit Certificate screen for the selected certificate, click View/Download Certificate to open a window with the certificate string. Click View/Download Key to open a window with the certificate private key.

To copy the certificate or private key to the clipboard, click on the assignment clipboard icon. Click Download to put a copy of the certificate or private key on your server.

Keep the certificates and private keys in a secure area where you can back them up.

Managing Certificate Signing Requests

The Certificate Signing Requests widget allows users to configure a message that the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.

Adding a CSR

If you plan to create an ACME certificate, before adding a CSR, make sure the certificate authority provider account (i.e., Cloudflare, DigitalOcean, etc.) is correctly configured with all domains entered in this CSR.
When adding an ACME certificate for a CSR, it is created based on the settings in the selected CSR.
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.
Figure 1: Add CSR Certificate Options RSA Type
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.
Figure 2: Add CSR Certificate Subject Screen
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.

Importing a CSR

When importing a certificate into TrueNAS for the CSR, enter a name, and then select Import Certificate Signing Request in Type. Click Next.

Enter or copy/paste the certificate string into Signing Request, then enter or copy/paste the private key into Private Key. Enter the password for the private key in Password and Confirm Password. Click Next, review the information, and then click Save.

Creating an ACME Certificate

TrueNAS provides a way to add a certificate for an ACNE DNS authenticator added to the system. After adding the DNS authenticator, create a CSR for it. Click on the more_vert for the CSR on the Certificate Signing Requests widget, then click on Create ACME Certificate to open the Create ACME Certificate screen.

You must configure a DNS authenticator to create an ACME certificate! The ACME certificate is created based on the settings in the selected CSR.
You must have the domains added to the account providing the DNS authenticator. For example, if using Cloudflare to create the DNS authenticator, the Cloudflare account must have the domain(s) entered in the Subject Alternative Name field in the Add CSR wizard on the Certificate Subject screen. If not properly configured, a dialog with an error indicating the configuration problem opens.

Figure 4: Create ACME Certificate Screen

Enter a name in Identifier. The underscore (_) and dash (-) are allowed characters in the name.

Select Terms of Service.

Enter a number that specifies the time (in days) before the certificate expires in Renew Certificate Days.

Select the URI of the ACME server directory from the ACME Server Directory URI dropdown list.

The Domains area shows domains for each entry made in the Subject Alternative Name field on the Certificate Subject screen of the Add CSR wizard. Select the option from the dropdown list for each domain shown. This sets the authenticator to validate the domain.

Click Save. The new ACME certificate shows on the Certificates and the Certificate Signing Requests widgets.

Adding ACME DNS Authenticators

Automatic Certificate Management Environment (ACME) DNS authenticators allow users to automate certificate issuing and renewal. The user must verify ownership of the domain before TrueNAS allows certificate automation.

ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.

The system requires an ACME DNS Authenticator and CSR to configure ACME certificate automation to proceed.

Adding a DNS Authenticator

Before you begin this procedure, log in to your DNS authenticator provider service to obtain an API global key or an API token, whichever your service provider requires. When configuring an ACME DNS authenticator in TrueNAS using Cloudflare as the provider, you need the global API key but not the API token.

This procedure uses Cloudflare as the example. To add an authenticator:

Click Add on the ACME DNS-Authenticator widget to open the Add DNS Authenticator screen.

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 more_vert for the authenticator, and then on Edit.

After adding the authenticator, you can configure a certificate signing request (CSR) for this authentictor and create an ACME certificate. For more information, see Managing Certificate Signing Requests.

Adding an Authenticator with a Shell Script

The shell authenticator option is intended for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.

If you select shell as the authenticator, you must enter the path to an authenticator script, the running user, a certificate timeout, and a domain propagation delay.

Advanced users can select this option to 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.

Requirements

An email address for your TrueNAS admin user.
A custom domain that uses Cloudflare, DigitalOcean, Amazon Route 53, or OVHcloud.
A DNS server that does not cache for your TrueNAS system.

Create an ACME DNS-Authenticator

Go to Credentials > Certificates and click ADD in the ACME DNS-Authenticators widget.

LetsEncryptAcmeDNSAuthenticator

Enter the required fields depending on your provider, then click Save.

For Cloudflare, enter either your Cloudflare Email and API Key, or enter an API Token. If you create an API Token, make sure to give the token the permission Zone.DNS:Edit, as it’s required by certbot.

For DigitalOcean, enter your Digitalocean Token.

For Route53, enter your Access Key ID and Secret Access Key. The associated IAM user must have permission to perform the Route53 actions ListHostedZones, ChangeResourceRecordSets, and GetChange.

For OVH, enter your OVH Application Key, OVH Application Secret, OVH Consumer Key, and OVH Endpoint.

Create a Certificate Signing Request (CSR)

Next, click ADD in the Certificate Signing Requests widget.

You can use default settings except for the Common Name and Subject Alternate Names fields.

LetsEncryptCSR

Enter your primary domain name in the Common Name field, then enter additional domains you wish to secure in the Subject Alternate Names field.

For example, if your primary domain is domain1.com, entering www.domain1.com secures both addresses.

Create ACME Certificate

Click the icon next to the new CSR.

LetsEncryptACMECertificate

Fill out the ACME Certificate form. Under Domains, select the ACME DNS Authenticator you created for both domains, then click Save.

You can create testing and staging certificates for your domain.

Set the GUI SSL Certificate

Go to System > General Settings and click Settings in the GUI widget.

Select the new ACME certificate you created from the GUI SSL Certificate dropdown, then click Save.

Select the Confirm checkbox, then press Continue to restart TrueNAS and apply the changes.

Certificates Screens

The Certificates widget on the Credentials > Certificates screen shows certificates added to TrueNAS.

Import opens the Import Certificate screen.

The more_vert 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 Download downloads the certificate to the system. In Windows, this is the Downloads folder.

edit Edit opens the Edit Certificate screen.

delete Delete opens the Delete dialog.

Import Certificate

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.

Edit Certificate Screen

The Edit Certificate screen shows the current certificate identifier (name), subject information for the certificate, the view/download certificate and key options, and allows you to add the certificate to the TrueNAS trusted store.

The Subject area of the Edit Certificate screen shows information about the certificate.

Setting	Description
Common	Shows the common name for the certificate. A name can include the underscore (_) or dash (-) special characters. The default value for the truenas_default certificate is localhost.
SAN	Shows the subject alternative name (SAN) name for the certificate. The default value for the truenas_default certificate is DNS:localhost.
Distinguished Name	Shows the full directory service distinguished name for the certificate. This includes the country, organization, common name, email address, state, locality, and SAN properties.
Country	Shows the country where the certificate is issued. The default value for the truenas_default certificate is US.
State	Shows the organization for the certificate. The default value for the truenas_default certificate is iXsystems.
City	Shows the city where the certificate organization is located. The default value for the truenas_default certificate is Maryville
Organization	Shows the country where the certificate is issued. The default value for the truenas_default certificate is US
Organizational Unit	Shows the department in the organization for the certificate. No default value for the truenas_default certificate is specified.
Email	Shows the email address associated with the certificate. The default value for the truenas_default certificate is info@ixsystems.com.
Type	Shows the type of certificate. The default value for the truenas_default certificate is Certificate.
Path	Shows the path to where the certificate is stored. The default value for the truenas_default certificate is `/etc/certificates`.
Digest Algorithm	Shows the authentication protocol for the certificates. The default value for the truenas_default certificate is SHA256S.
Key Length	Shows the number of characters in the key for the certificate. The default value for the truenas_default certificate is 2048.
Key Type	Shows the certificate key type. The default value for the truenas_default certificate is RSA.
Until	Shows the expiration date for the certificate.
Lifetime	Shows the number of days the certificate remains valid. The default value for the truenas_default certificate is 397 days.

View/Download Certificate opens a window with the certificate string.

View/Download Key opens a window with the certificate private key.

The assignment clipboard icon copies the certificate or public key to the clipboard.

Download downloads a copy of the certificate to your server. Keep the certificate in a secure area where you can back it up and save it.

Delete Certificate Dialog

The Delete Certificate dialog removes the certificate from the TrueNAS system.

Force deletes the certificate if it is in use by a feature or function in the UI. For example, an application uses it for authentication.

Delete removes the certificate.

Certificate Signing Requests Screens

The Certificate Signing Requests widget, on the Certificates screen, shows a list of certificate signing requests (CSRs) configured on the system. CSR.

Figure 1: Certificate Signing Request Widget No CSRs

Figure 2: Certificate Signing Request Widget with CSR

The more_vert 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 Delete opens the Delete Certificate dialog.

Add opens the Add CSR wizard.

Create ACME Certificate Screen

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. Lets Encrypt Staging Directory Let’s Encrypt Production Directory
DNS:UnitedStates	Sets the authenticator to validate the domain. Shows a dropdown list of previously configured ACME DNS authenticators.

Edit CSR Screen

The Edit CSR screen shows the current CSR settings. It allows changing the CSR name (identifier), downloading or viewing the CSR, and provides access to the Create ACME Certificate screen.

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.
Email	Shows the email address associated with the certificate. The default value for the truenas_default certificate is info@ixsystems.com.
Type	Shows the type of certificate. The default value for the truenas_default certificate is Certificate.
Path	Shows the path to where the certificate is stored. The default value for the truenas_default certificate is `/etc/certificates`.
Digest Algorithm	Shows the authentication protocol for the certificates. The default value for the truenas_default certificate is SHA256S.
Key Length	Shows the number of characters in the key for the certificate. The default value for the truenas_default certificate is 2048.

View/Download Certificate opens a window with the certificate string.

View/Download Key opens a window with the certificate private key.

The assignment clipboard icon copies the certificate or public key to the clipboard.

Delete Certificate Dialog

The Delete Certificate dialog removes the certificate from the TrueNAS system.

Force deletes the certificate if it is in use by a feature or function in the UI. For example, an application uses it for authentication.

Delete removes the certificate.

Add CSR Wizard Screens

Certificate signing requests (CSR) allow configuring a message the TrueNAS system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.

The Add CSR wizard has five screens to configure a new certificate signing request (CSR) on TrueNAS. The wizard screens are:

1 Identifier and Type

2 Certificate Options

3 Certificate Subject

4 Extra Constraints

5 Confirm Options

Identifier and Type Options

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.

Figure 7: Identifier and Type Import CSR

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: Certificate Signing Request - Controls when an external CA issues (signs) the certificate. Typically used with ACME or other CAs that most popular browsers trust by default. Import Certificate Signing Request - Imports an existing CSR onto the system. Typically used with ACME CAs. Selecting Import Certificate Signing Request removes the Profile field, and the Certificate Subject and Extra Constraints wizard screens.
Profile	Sets the predefined certificate extention to either HTTPS RSA Certificate or HTTPS ECC Certificate.

Certificate Options Screen

Certificate Options show when Type is set to Certificate Signing Request on the Identifier and Type wizard screen. The settings specify the private key type, number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.

When Type is set to Import Certificate Signing Request, the settings shown add the signing request and private key of the imported certificate and the authentication credentials for the private key.

Figure 8: Add CSR Certificate Options RSA Type

Figure 9: Add CSR Certificate Options EC Type

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.

Import Certificate Screen

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.

Certificate Subject Settings

The Certificate Subject settings define the geographical location, name, and email for the organization using the certificate. Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.

Figure 11: Add CSR Certificate Subject Screen

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.
Email	Text entry field that accepts manual or copy/paste entry of the email address of the person responsible for the certificate.
Common Name	Text entry field that accepts manual or copy/paste entry of the fully qualified host name (FQHN) of the system. This name must be unique within a certificate chain.
Subject Alternate Names	Sets multi-domain support of additional domains to secure. Text entry field that accepts manual or copy/paste entry of additional domains to secure for multi-domain support. Separate each domain by pressing `Enter`. For example, if the primary domain is example.com, entering www.example.com secures both addresses.

Extra Constraints Settings

The Extra Constraints screen shows when adding a CSR. Settings on this screen are optional.

The Extra Constraints settings contain certificate extension options:

Basic Constraints limits the path length for a certificate chain.
Authority Key Identifier identifies the public key corresponding to the private key used to sign a certificate.
Key Usage defines the purpose of the public key contained in a certificate.
Extended Key Usage further refines key usage extensions.

The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.

After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, more settings show for that option.

Figure 12: Add CSR Extra Constraints Screen

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: CA - Select when the certificate is a certificate authority (CA) Critical Extension - Select when the certificate is a critical extension. Clients must recognize critical extensions to prevent rejection. Web certificates typically require you to disable CA and enable Critical Extension.
Extended Key Usage	Activates this certificate extension, and shows the Usages setting. The extended key usage extension identifies and limits valid uses for this certificate, such as client or server authentication. See RFC 3280, section 4.2.1.13 for more details.
Usages	Shows after selecting Extended Key Usage, and sets the options to identify the purpose of this public key. Typically used for the end entity certificates. You can select multiple usages. These show in the field separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CERTIFICATE_TRANSPARENCY, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_IKE, KERBEROS_PKINIT_KDC, OCSP_SIGNING, SERVER_AUTH, SMARTCARD_LOGON, or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. Using the Extended Key Usage and Key Usage extensions requires the purpose of the certificate to be consistent with both extensions. See RFC 3280, section 4.2.13 for more details.
Critical Extension	Shows after selecting Extended Key Usage. Sets the extension to critical or non-critical for the certificate. Critical extensions must be recognized by the system using the certificate, or this certificate is rejected. Extensions identified as non-critical can be ignored by the system using the certificate, and the certificate is still approved.
Key Usage	Activate this certificate extension, and shows the Key Usage Config field. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that can be used for a few operations should be restricted. For example, when an RSA key should only be used to verify signatures on objects other than public key certificates and CRLs, and the digital signature bits are asserted. Likewise, when an RSA key should only be used for key management, the key encipherment bit should be asserted. See RFC 3280, section 4.2.1.3 for more information.
Key Usage Config	Shows after selecting Extended Key Usage or Key Usage. Sets the key usage extension to valid option(s) on the dropdown list. Options are: Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. Web certificates typically need at least a digital signature and possibly key ecncipherment or key agreement, while other applications might need other usages.

Confirm Options

The Confirm Options screen shows a summary of settings for the CSR when adding a new certificate. It shows the Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and Basic Constraints Config setting values. When importing a certificate, the screen shows the Type, Signing Request, and Private Key setting values.

Save adds the certificate to TrueNAS. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.

ACME DNS-Authenticators Screens

The ACME DNS-Authenticators widget, on the Certificates screen, shows configured authenticators. Automatic Certificate Management Environment (ACME) DNS-Authenticators allow users to automate certificate issuing and renewal. The user must verify ownership of the domain before TrueNAS allows certificate automation.

ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.

The system requires an ACME DNS authenticator and CSR to configure ACME certificate automation.

Figure 1: ACME DNS-Authenticators Widget

Add opens the Add DNS-Authenticator screen.

The more_vert icon for a listed certificate shows a dropdown list of options.

Edit opens the Edit DNS Authenticator screen.

delete deletes opens a Delete DNS Authenticator dialog.

Add or Edit DNS Authenticator

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.

Delete DNS Authenticator Dialog

The Delete DNS Authenticator dialog shows a Confirm option that, when selected, activates the Delete button. TrueNAS asks you to confirm before you can delete the authenticator.

KMIP

Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.

KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS Enterprise.

Configuring KMIP

TrueNAS Enterprise
KMIP is only available for TrueNAS Enterprise licensed systems. Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.

The Key Management Interoperability Protocol (KMIP) is an extensible client/server communication protocol for storing and maintaining keys, certificates, and secret objects. KMIP on TrueNAS Enterprise integrates the system within an existing centralized key management infrastructure and uses a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.

With KMIP, keys created on a single server are then retrieved by TrueNAS. KMIP supports keys wrapped within keys, symmetric, and asymmetric keys. KMIP enables clients to ask a server to encrypt or decrypt data without the client ever having direct access to a key. You can also use KMIP to sign certificates.

Requirements

To simplify the TrueNAS connection process:

Have a KMIP server available with certificate authorities and certificates you can import into TrueNAS.
Have the KMIP server configuration open in a separate browser tab or copy the KMIP server certificate string and private key string to later paste into the TrueNAS web interface.

Connecting TrueNAS to a KMIP Server

To connect TrueNAS to a KMIP server, import a Certificate from the KMIP server, then configure the KMIP options.

How do I import these?

Log into the TrueNAS web interface and go to Credentials > Certificate. Click Import on the Certificate widget. Enter a memorable name for the certificate, then paste the KMIP server certificate and private key strings into the related TrueNAS fields. Leave Passphrase empty. Click Save.

For security reasons, we strongly recommend protecting the certificate values.

Configuring KMIP in TrueNAS

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

TrueNAS Enterprise
KMIP on TrueNAS Enterprise is used to integrate the system within an existing centralized key management infrastructure and use a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.

The KMIP screen has two areas, KMIP Key Status that displays keys synced between a KMIP server and TrueNAS database and KMIP Server with the KMIP configuration settings.

KMIP Key Status

The KMIP Key Status area of the KMIP screen lists ZFS/SED keys synced between a KMIP server and the TrueNAS database.

Sync Keys synchronizes keys issued by the KMIP server with the TrueNAS database. This button activates when a KMIP key sync is pending.

Clear Sync Keys cancels a pending synchronization. This button is active when a KMIP key sync is pending or in progress but not completed.

KMIP Server Settings

Setting	Description
Server	Text entry field that accepts manual or copy/paste entry of the host name or IP address of the central key server.
Port	Text entry field that accepts manual or copy/paste entry of a connection port number on the central key server. Default value 5696 is the kmip.truenas.com port number.
Certificate	Sets an existing certificate to one selected on the dropdown list, or enter a new one to use for key server authentication. Requires a valid certificate to verify the key server connection. Warning: for security reasons, protect the certificate used for key server authentication.
Manage SED Passwords	Manages the global self-encrypting drive (SED) password with KMIP when enabled. This option allows the key server to manage creating or updating the global SED password, and retrieving SED passwords when SEDs are unlocked. Disabling this option leaves SED password management with the local system.
Manage ZFS Keys	Uses the KMIP server to manage ZFS encrypted dataset keys when enabled. The key server stores, applies, and destroys encryption keys whenever an encrypted dataset is created, when an existing key is modified, an encrypted dataset is unlocked, or an encrypted dataset is removed. When not enabled, this option leaves all encryption key management with the local system.
Enabled	Activates KMIP configuration and begins syncing keys with the KMIP server when enabled.
Change Server	Moves existing keys from the current key server to a new key server when enabled. When switching to a different key server, enable key synchronization, then select this setting, update the key server connection configuration, and click Save.
Validate Connection	Tests the server connection and verify the chosen certificate chain when enabled. To test, configure the Server and Port settings, select a certificate, then select this setting, and click Save.
Force Clear	Cancels any pending key synchronization when selected.

Containers

TrueNAS supports Linux containers (LXC) for lightweight, isolated application environments that share the host system kernel.

Creating and Managing Containers: Tutorials for configuring the TrueNAS Containers feature, creating, and managing containers.

Containers Screens: Provides information on the Containers screens and settings to add containers or virtual machines (VMs) to your TrueNAS system.

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.

What system resources do containers require?

Containers are lightweight and share the host kernel, requiring fewer resources than virtual machines. However, proper resource allocation ensures optimal performance and system stability.

You can leave CPU and memory settings blank to allow containers access to all available host resources, or configure specific limits based on your needs. Key considerations for container deployment:

Storage Pool: Containers require a storage pool for volume creation and image storage. SSD drives provide optimal performance.
CPU: No virtualization extensions required. Multiple containers run efficiently on fewer resources than equivalent VMs.
Memory: More efficient than VMs with no guest OS overhead. Memory allocated to containers reduces available memory for TrueNAS ZFS caching.

Setting Up the Containers Service

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.

Configuring Settings

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.

Setting a Preferred Pool

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.

Configuring the Default Network

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 Enterprise
Custom bridge selection is not available on High Availability systems. HA deployments always use Automatic to prevent issues that could interfere with controller failover.
(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.

Configuring Containers in High Availability Environments

TrueNAS Enterprise
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.

Understanding Network Configuration Best Practices for HA

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.

Understanding Container Failover Behavior

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

Managing Container Permissions

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.

Understanding Default Mapping

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.

Granting Root Access to Host Paths

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.

Determining When to Use Custom Mappings

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.

Configuring Mappings

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 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.

Creating Containers

Click Create New Container to open the Add Container configuration wizard.

Creating a Container

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.
Name Requirements
A container name must meet these criteria:
- It must be between 1 and 63 characters long.
- It can only include letters, numbers, and dashes from the ASCII character set.
- It cannot begin with a number or a dash.
- It cannot end with a dash.
(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.
Figure 5: 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

Running Nested Containers

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.

Managing Containers

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 to restart or to stop a running container. Choosing to stop a container shows a choice to stop immediately or after a small delay.

Click 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.

Using Bulk Actions

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.

Editing Containers

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.

Deleting Containers

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.

Managing USB Devices

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.

Managing GPU Devices

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.

Configuring Filesystem Devices

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.
Figure 15: Add Filesystem Device
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 more_vert 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:

Managing NICs

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.
Figure 17: Add NIC Device
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 to stop the container.
Click the more_vert 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.

Accessing Containers

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

Containers Screen

The Containers screen allows users to add, edit, or manage Linux containers.

The Containers screen displays No Containers before you create the first container.

Figure 1: Containers Screen No Containers

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.

Settings Screen

The Settings screen displays global options that apply to all containers, including an optional preferred storage pool and default network settings.

Preferred Pool

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

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.

Map User and Group IDs Screen

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 on a row removes that mapping.

Add New Mapping Settings

Setting	Description
User/Group	Specifies the user or group account name. Supports local users and groups only; Active Directory and other directory service accounts are not supported.
Map to the same UID/GID in the container	(Default) Maps the host user or group ID to the same ID inside containers.
Container UID/GID	(Displays when Map to the same UID/GID in the container is not selected) Enter the ID number (e.g., 1000) to map the host user or group ID to inside containers.

Set creates the mapping. Changes apply immediately, though restarting the container might be required for them to take effect.

Add Container Screen

The Add Container screen displays basic configuration fields and an Advanced Options button for additional settings.

Basic 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.

Name Requirements

A container name must meet these criteria:

It must be between 1 and 63 characters long.
It can only include letters, numbers, and dashes from the ASCII character set.
It cannot begin with a number or a dash.
It cannot end with a dash.

Advanced Options

Advanced Options shows additional configuration settings.

Storage

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.

CPU Configuration

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.

Time Configuration

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.

Init Process

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.

Figure 6: Add Container Advanced Options - Part 2

Environment Variables

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.

ID Mapping

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:

Default (Recommended): Maps the container root (UID 0) to the unprivileged host user truenas_container_unpriv_root (UID 2147000001). All other container UIDs are offset by the same amount (e.g., container UID 1000 becomes host UID 2147001001). Provides security isolation while allowing normal container operations.

Isolated: Uses the same offset as default but shifts the base further by a per-container slice value, ensuring no two containers share host UID ranges. Use when multiple containers access the same host datasets and non-overlapping UID ranges are required. TrueNAS automatically assigns a unique slice if none is specified.

Privileged: Applies no UID/GID mapping — container UIDs map directly to the same UIDs on the host. Container root (UID 0) becomes host root. Use only when an application explicitly requires direct UID mapping.

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

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: DEFAULT (Recommended): Keeps most capabilities but drops dangerous ones (sys_module, sys_time, mknod, audit_control, mac_admin). Provides security while allowing normal container operations. ALLOW: Grants all capabilities. Use when containers need broad system access, but reduces security isolation.

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.

Containers Table

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 button restarts or the 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 button starts a stopped container.

Search above the Containers table allows entering the name of a container to locate a configured container.

The checkbox on each container row shows the Bulk Actions dropdown.

Bulk Actions

The Bulk Actions dropdown list allows you to apply actions to one or more containers on your system. Options are Start All Selected, Stop All Selected, and Restart All Selected.

Containers Cards

The Details for Container cards display information and configuration options for the selected container.

General Info Card

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.

Delete Containers

The Delete dialog asks for confirmation to delete the selected container.

Confirm activates the Continue button. Continue starts the delete operation.

USB Devices Card

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.

GPU Devices Card

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

Filesystem Devices Card

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 more_vert actions menu includes options to Edit or Delete the filesystem device.

See Configuring Filesystem Devices in the Containers tutorial for configuration procedures.

NIC Devices Card

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.

Add/Edit NIC Device Dialog

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 more_vert actions menu provides options to Edit or Delete the NIC.

NICs can only be modified when the container is stopped.

Tools Card

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.

Accessing a web shell requires the Web Shell Access privilege. Shells for apps, containers, and VMs also require the write role for that resource type. The Full Admin role includes all these write roles.

Shell	Required Privilege and Role
System > Shell (host system)	Web Shell Access privilege only
VM Serial Shell	Web Shell Access privilege plus the VM write role (`VM_WRITE`)
Container Shell	Web Shell Access privilege plus the container write role (`CONTAINER_WRITE`)
Container Shell (Apps)	Web Shell Access privilege plus the apps write role (`APPS_WRITE`)

When authorized, shell commands run as the root user.

Edit Container Screen

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).

TrueNAS Enterprise
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: Tutorials for configuring TrueNAS SCALE virtualization features and creating virtual machines.

Adding and Managing VM Devices: Provides instructions on adding or managing devices used by VMs.

Virtual Machines Screens: Provides information on the screens and settings to add virtual machines (VMs) and devices to your TrueNAS SCALE system.

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.

What system resources do VMs require?

TrueNAS assigns a portion of system RAM and a new zvol to each VM. While a VM is running, these resources are not available to the host computer or other VMs.

Virtualization requires:

x86 machine running a recent Linux kernel
Intel processor with VT (Virtualization Technology) extensions, OR
AMD processor with SVM extensions (AMD-V)

Users cannot create VMs unless the host system supports these features.

Users with multiple GPUs who wish to pass a GPU to a VM must first isolate a GPU for VM use. One GPU is always required by TrueNAS.

Creating a Virtual Machine

Before creating a VM:

Obtain an installer .iso or image file for the OS you intend to install
Create a zvol on a storage pool that is available for both the virtual disk and the OS install file.

If the VM needs to access local NAS storage, you must create a network bridge to allow communication. See Accessing TrueNAS Storage from a VM below for more information.

Using the Create Virtual Machine Wizard

To create a new VM, go to Virtual Machines and click Add to open the Create Virtual Machine wizard. If you have not yet added a virtual machine to your system, clicking Add Virtual Machines opens the same wizard.

Configure the Operating System settings.
a. Select the operating system for the VM from the Guest Operating System dropdown list.
Figure 1: Operating System Settings
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.
Figure 2: CPU and Memory Settings
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.
Figure 3: 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.
Figure 4: Import Image Options
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.
Figure 5: 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.
Figure 6: Installation Media Settings
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.
Figure 7: Upload Installation Media
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.
Figure 8: GPU Settings
TrueNAS does not have a list of approved GPUs at this time, but TrueNAS does support various NVIDIA, Intel, and AMD GPUs.
Confirm your VM settings, then click Save.

Adding and Removing Devices

Using the Create Virtual Machine wizard configures at least one disk and NIC, and optionally a CD-ROM and display as part of the process, but you can add more devices to suit your use case. Go to Virtual Machines, then click anywhere on a VM entry to expand it and show the options for the VM.

The VM options change when the VM is running.

Click Devices to open the Devices screen for that VM. Click the more_vert 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.

Managing a Virtual Machine

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 Display and 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 to follow a standard procedure to do a clean shutdown of the running VM. Click 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 button might not function as expected. The Running toggle and 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.

Deleting a Virtual Machine

To delete a VM, first stop it if it is running, then click 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.

Installing an OS

After configuring the VM in TrueNAS and an OS .iso file is attached, start the VM and begin installing the operating system.

Some operating systems can require specific settings to function properly in a virtual machine. For example, plain Debian can require advanced partitioning when installing the OS. Refer to the documentation for your chosen operating system for tips and configuration instructions.

Installing Debian OS Example

Upload the Debian .iso to the TrueNAS system and attach it to the VM as a CD-ROM device. This example uses Debian 12 and basic configuration recommendations. Modify settings as needed to suit your use case.

Click Virtual Machines, then ADD to use the VM wizard. Configure settings as needed.
Figure 13: Add Debian VM

Settings used in this example

Operating System

Setting	Description
Guest Operating System	Linux
Name	debianVM
Description	Debian VM

CPU and Memory

Setting	Description
Memory Size	1024 MiB

Disks

Setting	Description
Create new disk image	Selected
Zvol Location	Select pool.
Size	30 GiB

Network Interface

Setting	Description
Attach NIC	Select the physical interface to associate with the VM.

Installation Media

The installation ISO is uploaded to local storage. If the ISO is not uploaded, select Upload an installer image file. Select a dataset to store the ISO, click Choose file, then click Upload. Wait for the upload to complete.

GPU

Leave the default values.

Confirm Options

Verify the information is correct and then click Save.

After creating the VM, start it. 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.
- If the network configuration fails, click Continue and do not configure the network yet.
c. Enter a name in Hostname.
d. Enter a Domain name.
e. Enter the root password and re-enter the root password.
f. Enter a name in New User.
g. Select the username for your account or accept the generated name.
h. Enter and re-enter the password for the user account.
j. Choose the time zone, Eastern in this case.
Detect and partition disks.
a. Select Guided - use entire disk to partition.
b. Select the available disk.
c. Select All files in one partition (recommended for new users).
d. Select Finish partitioning and write changes to disk.
e. Select Yes to Write the changes to disks?.
Install the base system:
a. Select No to the question Scan extra installation media.
b. Select Yes when asked Continue without a network mirror.
Install software packages:
a. Select No when asked Participate in the package usage survey.
b. Select Standard system utilities.
c. Click Continue when the installation finishes.
After the Debian installation finishes, close the display window.
Remove the device or edit the device order. In the expanded section for the VM, click Power Off to stop the new VM.
a. Click Devices.
b. Remove the CD-ROM device containing the install media or edit the device order to boot from the Disk device.
- To remove the CD-ROM from the devices, click the and select Delete. Click Delete Device.
- To edit the device boot order, click the and select Edit. Change the CD-ROM Device Order to a value greater than that of the existing Disk device, such as 1005. Click Save.
Return to the Virtual Machines screen and expand the new VM again.
Click Start, then click Display.

What if GRUB does not start automatically?

If GRUB does not run when you start the VM, enter the following commands after each start. At the shell prompt:

Enter FS0: and press Enter.
Enter cd EFI and press Enter.
Enter cd Debian and press Enter.
Enter grubx64.efi and press Enter.

To ensure it starts automatically, create the startup.nsh file at the root directory on the VM. To create the file:
Go to the Shell.
At the shell prompt, enter edit startup.nsh.
In the editor, enter:
a. Enter FS0: and press Enter.
b. Enter cd EFI and press Enter.
c. Enter cd Debian and press Enter.
d. Enter grubx64.efi and press Enter.
Use the Control+s keys (Command+s for Mac OS) then press Enter.
Use the Control+q keys to quit.
Close the display window
To test if it boots up on startup:
a. Power off the VM.
b. Click Start.
c. Click Display.
d. Log into your Debian VM.

Configuring Virtual Machine Network Access

Configure VM network settings during or after installation of the guest OS. To communicate with a VM from other parts of your local network, use the IP address configured or assigned by DHCP within the VM.

To confirm network connectivity, send a ping to and from the VM and other nodes on your local network.

Debian OS Example

Open a terminal in the Debian VM.

Enter ip addr and record the address.

Enter ping followed by the known IP or hostname of another client on the network, that is not your TrueNAS host. Confirm the ping is successful. To confirm internet access, you can ping a known web server, such as ping google.com.

Accessing TrueNAS Storage From a VM

By default, VMs are unable to communicate directly with the host NAS. If you want to access your TrueNAS SCALE directories from a VM, for example, to connect to a TrueNAS data share, you have multiple options.

If your system has more than one physical interface, you can assign your VMs to a NIC other than the primary one your TrueNAS server uses. This method makes communication more flexible but does not offer the potential speed of a bridge.

If your system has only one physical interface, create a bridge interface for the VM to use. Stop all existing apps, VMs, and services using the current interface, edit the interface and VMs, create the bridge, and add the bridge to the VM device. See Accessing NAS from VM for more information.

Virtual Machines Contents

Adding and Managing VM Devices

Managing Devices

The VM options change when the VM is running.

Click Devices to open the Devices screen for that VM. Click the more_vert 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 You Begin

Before adding, editing, or deleting a VM device, stop the VM if it is running. Click the Running toggle to stop a VM, or click on the VM row and use the Stop button. Clicking the Running toggle for a stopped VM restarts it, or you can click on the VM row to expand it, and then click on the Restart button.

To access the devices for a VM, click on the VM row on the Virtual Machines screen to expand the VM, then click on Devices to open the Devices screen showing the devices for the selected VM.

Click Add to create a new device> To edit an existing device, click on the more_vert at the right of each device row, click Edit to open the Edit Device screen. Click Delete to open a delete confirmation dialog. t

Editing a Device

After selecting the VM row on the Virtual Machines list and clicking on Devices to open the Devices screen, the devices configured for that selected VM show. Devices added when you create the VM show by default. You can add additional or edit existing devices.

Click on the more_vert at the right of the device row. Options for each device show. A disk device shows four options: Edit, Delete, Details, and Export to Image. Other device types do not include the export option.

Click Edit* to open the Edit Device screen. The screen settings change based on the device type selected. For example, when editing a disk (example provided below), you can change the type of virtual hard disk, the storage volume to use, or change the boot order for the device.

Stop the VM on the Virtual Machines screen, click on Devices to open the Devices screen for that VM, and then click Edit. The procedure below describes editing a disk device. Steps below are optional. Change them based on your use case.

(Optional) Select the zvol created when setting up the VM on the Zvol dropdown list. The field populates with the path to the selected zvol.
(Optional) Select the type of hard disk emulation from the Mode dropdown list. The options are AHCI and VirtIO. Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM has support for VirtIO disk devices.
(Optional) Specify the disk sector size in bytes in Disk Sector Size. Leave set to Default if you want to leave the sector size unset and use the ZFS volume value. Select either 512 or 4096 byte values from the dropdown list to specify a logical and physical sector size.
(Optional) Enter a number that reflects the boot order or priority level in Device Order. Setting this value to 1000 puts the disk device in the boot order first position. When first installing or changing an OS added to the CD-ROM device, the CD-ROM is assigned 1000 to boot up from and install an OS. After installing the OS, change the boot order for the CD-ROM to a lower boot order so you 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.

To edit display type or bind address after creating a VM

Go to Virtual Machines, locate the VM you want to modify, and click on it to expand it. Click Devices to open the Devices screen associated with the VM. Click the more_vert icon at the right of the display device and click on Edit to open the Edit Device screen for that display device. Select the IP address or other option on the Bind dropdown.

You can assign a port number to your display device or use the default port number associated with the device.

You can add a second display device to have a VNC and SPICE display associated with the VM, but only one display device can be active at one time. Adding a second display device assigns a different default port number to the second display device.

Deleting a Device

Deleting a device removes it from the list of available devices for the selected VM.

To delete a device:

Stop the VM if it is running, then click Devices to open the Devices screen showing the devices for the selected VM.
Click on the more_vert icon to the right of the device and then Delete to open the delete confirmation dialog for that display device. The dialog shows the name or identifier for the selected device. The example below shows undefined 8 as the name.
Figure 4: Delete Virtual Machine Device
Select Force Delete to force the system to delete the device (for example, device is a CD-ROM). When deleting a disk, it forces the system to delete the zvol even if other devices or services are using it or are affiliated with the zvol device.
Click Delete Device.

Changing the Device Order

Changing the device order moves the device up or down in the boot order when the VM or system is restarted. A VM attempts to boot from devices according to the Device Order, starting with 1000, then ascending.

After stopping the VM and clicking Devices to open the Devices screen:

Click on the more_vert at the right of the device row, then click on Edit to open the Edit Device screen.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order. The lower the number, the higher the device is in the boot sequence. 1000 is the first position in the boot order.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Adding a CD-ROM Device

After stopping the VM and clicking Devices to open the Devices screen:

Click Add and select CD-ROM on the Device Type dropdown list.
Figure 5: Devices Add CD-ROM Type
Enter or browse to select the mount path to the CD-ROM device. Click on the to the left of /mnt to expand or collapse the directory tree.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order. The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Adding a NIC Device Type

After stopping the VM and clicking Devices to open the Devices screen:

Click Add to open the Add Device screen.
Select NIC on the Device Type dropdown list to show the network interface card settings.
Figure 6: Devices Add NIC
Select the adapter type from the Adapter Type dropdown list. Choose Intel e82585 (e1000) for maximum compatibility with most operating systems. If the guest OS supports VirtIO paravirtualized network drivers, choose VirtIO for better performance.
Click Generate to have TrueNAS populate MAC Address with a new random MAC address to replace the default random address, or enter your own custom address.
Select a physical interface on your TrueNAS system from the NIC To Attach dropdown list.
(Optional) Select Trust Guest Filters to allow the virtual server to change its MAC address and join multicast groups. This is required for the IPv6 Neighbor Discovery Protocol (NDP).
Setting this attribute has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address. Determine your network setup needs before setting this attribute.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Add a Disk Device

After stopping the VM and clicking Devices to open the Devices screen:

Click Add and select Disk from the Device Type dropdown list.
Figure 7: Devices Add Disk
Select the path to the zvol created when setting up the VM on the Zvol dropdown list.
Select the hard disk emulation type from the Mode dropdown list. Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM supports VirtIO disk devices.
Select the sector size in bytes in Disk Sector Size. Leave set to Default or select either 512 or 4096 from the dropdown list. Default uses the ZFS volume values.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order. The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Exporting a Disk to an Image

Use this function to convert a VM disk (zvol) to a portable disk image file. Exported images can be imported into other VMs, transferred to different systems, or used as backups.

After stopping the VM and clicking Devices to open the Devices screen:

Click on the more_vert icon to the right of the disk device and then click Export to Image to open the Export Disk to Image window.
Figure 8: Export Disk to Image
Browse to select the dataset/directory using the file browser. Click on the dataset/directory to select it and populate the mount path field.
Select the image format from the Image Format dropdown list. Available formats include QCOW2 (QEMU Copy On Write), QED (QEMU Enhanced Disk), RAW (Raw Disk Image), VDI (VirtualBox Disk Image), VHDX (Hyper-V Virtual Hard Disk), and VMDK (VMware Virtual Machine Disk). The system automatically adds the appropriate file extension to the name in Image Name.
Click Export. The system saves the disk as an image in the location you specified in Destination Directory.

Adding a PCI Passthrough Device

Depending upon the type of device installed in your system, you might see a warning: PCI device does not have a reset mechanism defined. You may experience inconsistent or degraded behavior when starting or stopping the VM. Determine if you want to proceed with this action in such an instance.

After stopping the VM and clicking Devices to open the Devices screen:

Click Add and select PCI Passthrough Device from the Device Type dropdown list.
Enter a value in PCI Passthrough Device using the format of bus#/slot#/fcn#.
Figure 9: Devices Add PCI Passthrough
Enter a new number that represents where in the boot sequence you want to place this device in Device Order. The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Adding a USB Passthrough Device

After stopping the VM and clicking Devices to open the Devices screen:

Click Add and select USB Passthrough Device from the Device Type dropdown list to configure the USB passthrough device.
Figure 10: Devices Add USB Passthrough
Select the Controller Type from the dropdown list.
Select the hub controller type from the Device dropdown list. If the type is not listed, select Specify custom, then enter the Vendor ID and Product ID.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order. The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.

Adding a Display Device

Display devices have a 60-second inactivity timeout. If the VM display session appears unresponsive, try refreshing the browser tab.

After stopping the VM and clicking Devices to open the Devices screen:

Click Add and select Display from the Device Type dropdown list to configure a new display device.
Figure 11: Devices Add Display
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

Virtual Machines Screen

The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) or VM devices in TrueNAS. The No Virtual Machines screen shows when there are no VMs configured in or deleted from TrueNAS.

Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.

Each virtual machine listed includes the Running and Start on Boot toggles. Running shows the current state of the VM. Start on Boot automatically starts the VM after a system reboot.

Expanding a VM shows the details screen details on and options for that VM.

Virtual Machine Details Screen

The expanded Virtual Machines screen shows the details and options for a VM. Details include the basic information on the number of virtual CPUs, cores, threads, the amount of memory, the boot loader, and system clock types. Additional details include the display port number and the shutdown timeout in seconds.

Options shown change after starting a virtual machine. When a VM is placed in a suspended state, the options shown on the VM details screen change to show only the Power Off and Resume options.

VM Options

Operation	Icon	Description
Start		Starts a VM. The toggle turns blue when the VM switches to running. The Start button toggles to Stop. While running, the screen shows the Restart,Power Off, Display, and Serial Shell buttons.
Restart	replay	Stops then starts the VM. Shows for a running VM.
Power Off	power_settings_new	Shows after starting a VM. Powers off and halts the VM, similar to turning off a computer power switch. Shows only when the VM is running.
Resume	Shows when a VM is placed in a suspended state. The VM resumes operation and returns to the normal Running state.
Stop		Shows after starting a VM. Stops a running VM. Virtual machines do not always respond to STOP or the command might time out if the VM does not have an OS. Use Power Off instead. Stop toggles to Start after the VM stops.
Edit	mode_edit	Opens the Edit Virtual Machine with editable VM settings. You cannot edit a VM while it is running. Stop the VM to edit the properties and settings.
Delete		Deletes a VM and removes it from the system. Opens a delete dialog. You cannot delete a virtual machine that is running. Stop the VM to delete it.
Devices		Shows after starting a VM. Opens the Virtual Machine Devices screen for the selected VM.
Clone		Shows after starting the VM. Makes an exact clone copy of the VM. Opens the Clone dialog.
Display		Shows after starting the VM. Opens the SPICE login screen in a new browser window and allows you to connect to the remote desktop after entering the password to access that remote desktop.
Serial Shell		Shows after starting the VM. Opens the TrueNAS VM Serial Shell screen.
Download Logs	content_paste	Places a copy of the .log file on the system.

Delete Virtual Machine Dialog

The Delete Virtual Machine dialog shows options when deleting the VM and removing the VM configuration from your system.

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.

Clone Virtual Machine Dialog

The Clone dialog settings create an exact duplicate (clone) of the VM. The blank field allows manual entry of a name for the clone of the selected VM. Naming the clone VM is optional.

A cloned VM shows on the Virtual Machines list with the extension _clone0. Cloning the same VM again changes the extension for the second clone to clone1.

VM Serial Shell Screen

The Serial Shell button opens the VM Serial Shell screen, where you can enter commands for the selected virtual machine.

Shell	Required Privilege and Role
System > Shell (host system)	Web Shell Access privilege only
VM Serial Shell	Web Shell Access privilege plus the VM write role (`VM_WRITE`)
Container Shell	Web Shell Access privilege plus the container write role (`CONTAINER_WRITE`)
Container Shell (Apps)	Web Shell Access privilege plus the apps write role (`APPS_WRITE`)

When authorized, shell commands run as the root user.

The Virtual Machines breadcrumb in the header to returns to the Virtual Machine screen.

Edit Virtual Machine Screen

The Edit VM screen shows a subset of settings in the Create Virtual Machine screens. It includes the general settings also on the wizard Operating System screen, CPU and Memory, and GPUs screen settings. To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.

General Settings

The Edit screen General Settings specifies the basic settings for a VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.

General Settings

Setting	Description
Name	Required. Enter an alphanumeric name for the virtual machine.
Description	Enter a description (optional).
System Clock	Select the VM system time from the dropdown list. Options are Local or UTC. The default is Local.
Boot Method	Select the boot method option from the dropdown list. Select UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout	Enter the time, in seconds, the system waits for the VM to cleanly shut down. During the shutdown, the system powers off the VM after the shutdown timeout entered expires.
Start on Boot	Select to start this VM when the system boots.
Enable Hyper-V Enlightenments	Shows for VMs set for Windows OS. KVM implements Hyper-V Enlightenments for Windows guests. These features make Windows think they are running on a Hyper-V-compatible hypervisor and use Hyper-V-specific features. In some cases, enabling these enlightenments might improve the usability and performance for the guest.
Enable Secure Boot	Turns on the secure boot function in TrueNAS. Only available when using the wizard to create a new VM; it is not available on the edit screen. Some operating systems, like Windows 11, might not require secure boot.
Enable Trusted Platform Module (TPM)	Turns on the Trusted Platform Module (TPM) for enhanced security features in TrueNAS. TPM provides hardware-based cryptographic security functions. Some operating systems, like Windows 11, might require enabling this option.

Edit CPU and Memory Settings

The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.

CPU and Memory Settings

Setting	Description
Virtual CPUs	Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores	Text entry field to manually enter the number of cores per virtual CPU socket.
Threads	Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)	Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus	Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode	Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model	Sets the CPU model to the option selected on the dropdown list.
Memory Size	Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size	Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)	Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).

Edit GPU Settings

The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.

GPU Settings

Setting	Description
Hide from MSR	Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device	Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs	Sets the GPU to the option selected on the dropdown list.

Devices Screens

The Devices screen shows a table listing of VM devices configured on your system. By default, the screen shows three devices: Disks, NIC, and Display.

Add opens the Add Device screen. Settings change based on the various device types.

The more_vert at the right of each device row shows options for that device:

Edit - Opens the Edit type Device screen where type is the device type selected. Settings vary based on the type of device selected in Device Type. See Add Device screen. Device Type only displays on the Add Device screens.
Delete - Opens the Delete Device dialog.
Details - Opens an information dialog showing the port, type, bind IP, and other details about the device.
Export to Image - Shows only for disk devices. Opens the Export Disk to Image window to convert the disk (zvol) to a portable disk image file in QCOW2, QED, RAW, VDI, VHDX, or VMDK format.

Create Virtual Machine Wizard Screens

The Create Virtual Machine wizard includes all settings to set up a new virtual machine in TrueNAS.

Next and Back advance to the next screen or return to the previous screen without saving or losing setting choices. Save saves all settings, closes the wizard, and adds the new VM to the Virtual Machines screen.

Operating System Settings

The Operating System settings specify the VM operating system type, the time setting the VM system clock uses, the boot method, and the display type.

Operating System Settings

Setting	Description
Guest Operating System	(Required) Sets the operating system for the VM operating system to the option selected on the dropdown list. Options are Windows, which adds the Enable Hyper-V Enlightenments option. Linux, and FreeBSD.
Enable Hyper-V Enlightenments	Only shows when Guest Operating System is set to Windows. When enabled, the VM emulates a Hyper-V-compatible hypervisor for the Windows guest operating system and makes some Hyper-V-specific features available.
Name	(Required) Text entry field that accepts manual or copy/paste entry of a name for the VM that consists of alphanumeric characters.
Description	(Optional) Text entry field that accepts manual or copy/paste entry of a brief description about the VM. For example, the type of OS for the VM or the purpose of the VM.
System Clock	(Required) Sets the VM system clock to the option selected on the dropdown list. Options are: Local, which uses the TrueNAS SCALE system clock setting, or UTC, which uses the Coordinated Universal Time clock. The default is Local.
Boot Method	(Required) Sets the boot method to the option selected on the dropdown list. Options are: UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Enable Secure Boot	Sets the VM to verify boot components using digital signatures. This prevents unauthorized code from running during startup and is required for Windows 11 and some Linux distributions.
Enable Trusted Platform Module (TPM)	Sets TrueNAS to provide a virtual TPM 2.0 device for the VM. This enables hardware-based security functions, including secure key storage and cryptographic operations. Required for Windows 11.
Shutdown Timeout	Text entry field that accepts manual entry of a time in seconds that the system waits for the VM to cleanly shut down. During system shutdown, the system powers off after the shutdown timeout for the VM expires.
Start on Boot	Sets the VM to automatically start after restarting the system or when it is rebooted. Selected by default.
Enable Display (VNC)	Enables a VNC display (Virtual Network Computing) remote connection. VNC is the default display type when adding a VM. Requires UEFI booting. Selected by default.
Bind	Shows when Enable Display is selected. Sets an IP address to use for remote VNC sessions. Note that this setting only applies when using a VNC client other than the TrueNAS WebUI.
Password	(Required) Displays when Enable Display is selected.Enter a password to secure access to the VM. Enter this when logging into the VNC display.

CPU and Memory Settings

The CPU and Memory settings specify the CPU mode, model, and memory size. They allow specifying the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.

CPU and Memory Settings

Setting	Description
Virtual CPUs	Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores	Text entry field to manually enter the number of cores per virtual CPU socket.
Threads	Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)	Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus	Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode	Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model	Sets the CPU model to the option selected on the dropdown list.
Memory Size	Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size	Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)	Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).

Disks Settings

The Disks settings specify how virtual disks are added. Options are creating a new zvol on an existing dataset for a disk image, using an existing zvol for the VM, or importing an existing disk image file (QCOW2, QED, RAW, VDI, VHDX, VMDK) and converting it to a zvol.

Disks Settings

Setting	Description
Create new disk image	Shows settings to create a new zvol on an existing dataset to use as a virtual hard drive for the VM. Displays the Select Disk Type, Zvol Location, and Size fields.
Use existing disk image	Shows settings to select an existing zvol for the VM. Displays the Select Disk Type and Select Existing Zvol fields.
Import Image	Checkbox option to import an existing disk image file and convert it to a zvol for VM use. When you select this option, the Image Source field displays. Supports QCOW2, QED, RAW, VDI, VHDX, and VMDK formats with automatic format detection.
Image Source	(Required) Displays when you select Import Image. Browse to and select the source disk image file to import. The system automatically detects the image format from the file.
Select Disk Type	Sets the disk type to the option selected on the dropdown list. Options are AHCI or VirtIO. Select AHCI for Windows VMs. VirtIO requires a guest OS that supports VirtIO paravirtualized network drivers.
Select Existing Zvol	(Required) Shows after selecting Use existing disk image. Sets the disk to the existing zvol selected from the dropdown list.
Zvol Location	(Required) Shows a dropdown list of datasets to select as the location where the system creates a new zvol. When you select Import Image, this specifies the destination dataset for the converted zvol. When you select Create new disk image, this specifies where the system creates the new zvol.
Size	(Required) Shows when Create new disk image is selected. Allocates space for the new zvol. (Examples: 500 KiB, 500M, 2 TB). Units smaller than MiB are not allowed.

Network Interface Settings

The Network Interface settings specify the network adapter type, MAC address, and physical network interface card associated with the VM.

Network Interface Settings

Setting	Description
Adapter Type	Sets the adapter type to the option selected on the dropdown list. Options are: Intel e82545 (e1000) - Emulates the same Intel Ethernet card and provides compatibility with most operating systems. VirtIO - Provides better performance when the operating system installed in the VM supports VirtIO para-virtualized network drivers.
Mac Address	Shows the MAC address automatically entered by TrueNAS. Enter the desired address into the field to override the randomized MAC address.
Attach NIC	Sets the physical interface to associate with the VM selected on the dropdown list.
Trust Guest Filters	Enables and allows the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Enabling Trust Guest Filters has security risks because it allows the virtual server to change its MAC address and so receive all frames delivered to this address. Disabled by default.

Installation Media Screen

The Installation Media settings specify the location of the operating system installation media image in a TrueNAS dataset, or you can upload a copy from the local machine.

Installation Media Settings

Setting	Description
Choose Installation Media Image	Shows two fields, the mount path field and a file browser field directly below it. Sets the mount path to what is selected in the file browser field. To collapse the file branch, click on the to the left of /mnt.
Upload New Image File	Opens the Upload Image File dialog, where you browse to, and select the image file location on the local system or a network location available to your TrueNAS system. Choose File sets the file location and activates UpLoad.

Upload Installation Media Dialog

Upload Installation Media Settings

Setting	Description
ISO save location	Enter the path or browse to the location where you want to install the image file.
Choose File	Click to save the path populated in the ISO save location field.
Upload	Click to upload the file selected in the ISO save location field.

GPU Screen

The GPU settings specify the graphics processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.

GPU Settings

Setting	Description
Hide from MSR	Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device	Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs	Sets the GPU to the option selected on the dropdown list.

Confirm Options Screen

The Confirm Options screen shows a summary of settings for the VM, including the number of CPUs, cores, threads, memory, name of the VM, and the disk size.

Save adds the VM to the Virtual Machines screen.

Add Device Screen

The Add Device screen shows different settings based on the option selected in Device Type. Settings change based on the type, except the Type and Device Order settings, which are common to all device types.

Type sets the device type to the option selected on the dropdown list. The default selection is CD-ROM.

Device Order sets the position of the device in the boot order used when the system boots up or restarts. Accepts a number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.

CD-ROM Settings

CD-ROM settings show when Device Type is set to CD-ROM.

CD-ROM Path shows two fields: the /mnt path field that populates with what is selected with the file browser field directly below it. The to the left of /mnt expands or collapses the directory branch while you browse to the location of the CD-ROM file on the system. |

NIC Settings

VM network interface card settings show when Device Type is set to NIC.

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 to the left of /mnt to expand or collapse the directory branches as you browse to and select the location of the file on the system.
Disk sector size	Sets the disk sector size to the option selected on the dropdown list. Options are Default, which uses the ZFS volume values, 512, or 4096. Setting a sector size changes both the logical and physical sector size.
Mode	Sets the drive type to the option selected on the dropdown list. Options are: AHCI - Emulates an AHCI hard disk for better software compatibility. VirtIO - Uses paravirtualized drivers and can provide better performance, but the operating system installed in the VM must support VirtIO disk devices. .
Raw filesize	Text field that accepts manual entry of a number for the size of the file in GiB.

PCI Passthrough Settings

Shows PCI passthrough device settings when Device Type is set to PCI Passthrough Device.

Depending upon the type of device installed in your system, you might see a PCI device does not have a reset mechanism defined warning. You might experience inconsistent or degraded behavior when starting or stopping the VM. If this occurs, determine if you want to proceed with this action.

PCI Passthrough Device sets the PCI device to what is manually entered or select on the dropdown list of options. Enter a device as bus#/slot#/fcn#, for example 0000:00:04.3 ‘System peripheral’: Sky Lake-E CBDMA Registers by ‘Intel Corporation’.

USB Passthrough Settings

Shows the USB passthrough device setting when Device Type is set to USB Passthrough Device.

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.

Export Disk to Image Window

The Export Disk to Image window shows a file browser and other settings to convert a VM disk (zvol) to a portable disk image file. You access it from a disk device on the Devices screen.

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: QCOW2 - QEMU Copy On Write QED - QEMU Enhanced Disk RAW - Raw Disk Image VDI - VirtualBox Disk Image VHDX - Hyper-V Virtual Hard Disk VMDK - VMware Virtual Machine Disk

Apps

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: Articles describing the TrueNAS Apps screens and fields.

Custom App Screens: Provides information on the Install Custom App screen and configuration 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.

Installed Screen

The first time you go to Apps, the Installed applications screen header shows an Apps Service Not Configured status and dialog opens prompting you to choose the pool for apps to use. You must choose the pool apps use before you can install applications. See Choose A Pool for Apps for more information.

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.

Figure 2: Installed Applications Screen No Apps

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.

Figure 3: Installed Applications Screen Settings

Choose a Pool for Apps

Choose Pool opens the Choose a pool for apps dialog. The Pool dropdown list shows a list of available pools on the system. Choose sets the selected pool for use by applications.

The first time you open the Installed applications screen a dialog prompts you to choose the pool for apps to use for storage. Select the pool from the dropdown list, then click Save. This starts the applications service. If you exit out of this dialog, to set the pool, click Settings > Choose Pool to select a storage pool for apps.

If a pool is not selected and you attempt to install an application, a dialog window prompts you to select a pool before the installation wizard shows.

Migrate Existing Applications

If you select a new pool in the Pool dropdown after previously configuring the apps service, the dialog displays the Migrate existing applications option.

Migrate existing applications migrates all installed applications to the new applications pool.

Migrate existing applications only affects data saved in the apps dataset, such as the installed app location and iXvolume storage. Data in mounted host paths is not migrated.

Unset Pool

Unset Pool on the Settings menu opens the Unset Pool dialog.

Unset removes the pool configuration and turns off the application service. When complete, a Success dialog displays.

Manage Container Images

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

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 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.

Docker Registries

The Docker Registries screen lists signed-in Docker registry records.

Create Docker Registry

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

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).

Applications Table

The Applications table on the Installed screen populates a row for each installed app that shows the current state, and the option to stop the app. Stopped apps show the option to start the app.

After installing an application, the Installed screen populates the Applications table. When returning to the Installed screen, the first application on the list is selected by default. Each application row shows the name, status, and update information for the application.

Figure 13: Installed Applications Status

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.

Bulk Actions

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.

Application Widgets

Installed applications have a set of widgets on the Installed screen. Select an application row to view the information widgets for that application. Information in the widgets changes based on the app row selected in the Applications table.

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 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.

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.

Delete Apps

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 Apps

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

Convert to custom app on the 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 Apps

Roll Back on the 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.

Figure 21: Installed Apps Containers Widget

The Shell Shell button opens the Container Shell screen.

Shell	Required Privilege and Role
System > Shell (host system)	Web Shell Access privilege only
VM Serial Shell	Web Shell Access privilege plus the VM write role (`VM_WRITE`)
Container Shell	Web Shell Access privilege plus the container write role (`CONTAINER_WRITE`)
Container Shell (Apps)	Web Shell Access privilege plus the apps write role (`APPS_WRITE`)

When authorized, shell commands run as the root user.

The Volume Mounts folder_open button opens the Volume Mounts dialog.

The View Logs Logs button also opens the Pod Logs screen for the app.

Volume Mounts

Volume Mounts opens a dialog showing information on the app volume mounts for current and exited volume mounts for the application container. The app has Volume Mount options to open windows for both the running mount point and permissions - exited mount point.

Pod Log

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.

Discover Apps Screen

The Discover screen displays application widgets for the official TrueNAS stable train by default. Users can add the community and enterprise, or test train applications on the Settings screen.

Discover Screen Header

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. > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.

The Discover screen includes a search field, links to other application management screens, and filters to sort the application widgets displayed. Show All shows all application widgets in the trains added to the Stable catalog. The links are:

Refresh Charts that executes a job to refresh the catalog applications.
Manage Installed Apps that opens Installed applications screen.

Filters shows a list of sort categories that alter which application widgets show. Click on a category to select and filter app widgets. Filter information includes the Category, App Name, and Updated Date.

Category sorts the app widgets by category or functional area. For example, Media, Monitoring, Networking, Productivity. etc.
App Name sorts app widgets alphabetically (A to Z).
Updated Date sorts the app widgets by date of update.

Install Custom App Screens

TrueNAS 24.10 or later provides two options for installing a third-party application not included in the official catalogs using a Docker image. Custom App opens the Install iX App guided installation wizard. > 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.

Application Information Screens

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.

Figure 29: Application Information Screen Example

The application information screen shows two widgets:

Available Resources that show CPU and memory usage the app requires, the app pool, and available space in gigabits.
Application Info that includes the application version number, link to GitHub repository for the image, and date the image was last updated.

Some applications might also include the Run-As Content and Capabilities widgets.

The screen includes small screenshots of the application website that, when clicked, opens larger versions of the image.

Install opens the installation wizard for the application.

The bottom of the screen includes app widgets for similar applications found in the catalog.

Application Install or Edit App Wizards

The application Install Application wizard and Edit Application screens show the same settings, but un-editable settings are either not shown or are inactive to prevent edit attempts. The Edit Application screen opens populated with the current settings for the application.

The install and edit wizard screens include a navigation panel on the right of the screen that lists and links to the setting sections. A red triangle with an exclamation point marks the sections with the required settings. An asterisk marks the required fields in a section. You can enter a new setting in fields that include a preprogrammed default.

Custom App Screens

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. > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.

Install Custom App Screen

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.

Install Custom App Toc — Figure 2: Install Custom App ToC

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 Settings

Application Name has two required settings, Application Name and version. After completing the installation these settings are not editable.

Settings Information

Setting	Description
Application Name	Enter a name for the application. The name must have lowercase alphanumeric characters, begin with an alphabet character, and can end with an alphanumeric character. The name can contain a hyphen (-) but not as the first or last character in the name. For example, use chia-1 but not -chia1 or 1chia- as a valid name.
Version	Displays the current version of iX-App. Accept the default number.

Image Configuration Settings

Image Configuration settings specify the container image details. They define the image, tag, and when TrueNAS pulls the image from the remote repository.

Settings Information

Setting	Description
Repository	(Required) Enter the Docker image repository name. For example, plexinc/pms-docker for Plex.
Tag	Enter the tag to use for the specified image. For example, public for Plex. Or accept the default latest.
Pull Policy	Select the Docker image pull policy from the dropdown list. Options are Only pull image if not present on host (default option), Always pull image even if present on host, and Never pull image even if it’s not present on host.

Container Configuration Settings

Container Configuration settings specify the entrypoint, commands, timezone, environment variables, and restart policy to use for the image. These can override any existing variables stored in the image. Check the documentation for the application you want to install for required entrypoints, commands, or variables.

Settings Information

Setting	Description
Entrypoint	Click Add to display a new field. Each field is an item in the ENTRYPOINT list in exec format. For example, to enter `ENTRYPOINT ["top", "-b"]`, enter `top` in the first Entrypoint field. Click Add again. Enter `-b` in the second field.
Command	Click Add to display a new field. Each field is an item in the CMD list in exec format. For example, to enter `CMD ["echo", "hello world"]`, enter `echo` in the first Command field. Click Add again. Enter `hello world` in the second field.
Timezone	Use the dropdown to select a timezone setting for the container or begin typing the timezone to see a narrowed list of options to select from.
Environment Variables	Click Add to display a block of environment variables. Click Add again to enter another set of environment variables.
Name	Enter the environment variable name or key. For example, enter `MY_NAME`.
Value	Enter the value for the variable specified in Environment Variable Name. For example, enter `John Doe`, `John\ Doe`, or `John`.
Restart Policy	Use the dropdown to select a restart policy to use for the container. Options are No - Does not restart the container under any circumstances., Unless Stopped - Restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed., On Failure - Restarts the container if the exit code indicates an error., and Always - Restarts the container until its removal..
Disable Builtin Healthcheck	Select to disable the built-in `HEALTHCHECK` defined in the image, for example to address performance or compatibility requirements.
TTY	Select to enable a pseudo-TTY (or pseudo-terminal) for the container.
Stdin	Select to keep the standard input (stdin) stream for the container open, for example for an interactive application that needs to remain ready to accept input.

Security Context Configuration Settings

Security Context Configuration settings allow you to run the container in privileged mode, grant the container Linux kernel capabilities, or define a user to run the container.

Settings Information

Setting	Description
Privileged	Select to run the container in privileged mode. Note that privileged mode grants the container nearly unrestricted access to the host system, providing full administrative access to the entire TrueNAS server. This includes access to privileged credentials, encryption keys, and all data. By default, containers cannot access host devices. With Privileged enabled, the container gains access to all host devices and system capabilities. Only enable privileged mode when absolutely necessary and when you fully trust the container source. A more secure solution is to use Capabilities below to grant specific, limited permissions as needed.
Capabilities	Click Add to display a container capability field. Enter a Linux capability to enable, for example, enter `CHOWN`. Click Add again to enter another capability.
Custom User	Select to display the User ID and Group ID fields.
User ID	Displays when Custom User is selected. Enter the numeric UID of the user that runs the container. Defaults to 568 (apps).
Group ID	Displays when Custom User is selected. Enter the numeric GID of the group that runs the container. Defaults to 568 (apps).

Network Configuration Settings

Network Configuration settings specify network, ports, and DNS servers if the container needs a custom networking configuration.

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.

Figure 7: Network Configuration Settings

Settings Information

Setting	Description
Host Network	Select to bind the container to the TrueNAS host network. When bound to the host network, the container does not have a unique IP-address, so port-mapping is disabled.
Ports	Click Add to display a block of port configuration fields to specify the port values and transfer protocol. Click again to add additional port mappings.
Container Port	Enter a port number in the container. Refer to the application documentation for default port values.
Host Port	Enter an open port number on the TrueNAS host.
Protocol	Select the protocol from the dropdown list. Options are TCP or UDP.
Nameservers	Use to add one or more IP addresses to use as DNS servers for the container. Click Add to the right of Nameservers to display a Nameserver entry field. Click again to add another name server.
Nameserver	Enter the IP address of the name server.
Search Domains	Use to add one or more DNS domains to search non-fully qualified host names. Click Add to display a Search Domain field to enter the domain you want to configure. Click again to add another search domain. See the Linux search documentation for more information.
Search Domain	Enter the search domain you want to configure. For example, mydomain.com.
DNS Options	Use to add one or more key-value pairs to control various aspects of query behavior and DNS resolution. Click Add to display an Option field. Click again to add another option. See the Linux options documentation for more information.
Option	Enter a key-value pair representing a DNS option and its value. For example, ndots:2.

Portal Configuration Settings

The Portal Configuration settings configure the web UI portal for the container.

Click Add to display the web portal configuration settings.

Settings Information

Setting	Description
Name	Enter a UI portal name to use and display in the UI. For example, MyAppPortal.
Protocol	Select the web protocol to use for the portal from the dropdown list. Options are HTTP or HTTPS.
Use Node IP	Select to use the TrueNAS node, or host, IP address to access the portal. Selected by default.
Host	Displays when Use Node IP is not selected. Enter a host name or an internal IP within your local network, for example my-app-service.local or an internal IP address.
Port	Enter the port number to use for portal access. The port number the app uses should be in the documentation provided by the application provider/developer. Check the port number against the list of Default Ports to make sure TrueNAS is not using it for some other purpose.
Path	Enter the path for portal access, for example /admin. Defaults to /. The path is appended to the host IP and port, as in truenas.local:15000/admin.

Storage Configuration Settings

The Storage Configuration settings specify persistent storage paths and share data claims separate from the lifecycle of the container. For more details, see the Docker storage documentation.

You can mount TrueNAS storage locations inside the container with host path volumes. Create the storage volumes in TrueNAS and set the host path volume to a dataset and directory path. Define the path to the system storage and the container internal path for the system storage location to appear. Alternatively, select ixVolume to allow TrueNAS to create a dataset on the apps storage pool. Both Host Path and ixVolume attach container storage as a bind mount. See Docker Bind Mount documentation for more information.

Users can create additional SMB share volume claims within the container to access an SMB share. Share volumes consume space from the pool chosen for application management.

Finally, Tmpfs allows the container to utilize a temporary directory on the RAM. See the Docker tmpfs documentation for more information.

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 path/to/directory where the host path mounts inside the container.
Enable ACL	Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Host Path	(Required) Enter a path or click arrow_right to the left of /mnt to browse to the location of the dataset to populate the Host Path. Click on the dataset to select and display it in the Host Path field.
ACL Entries	Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type	Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID	Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access	Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.
Force Flag	Displays when Enable ACL is selected. Select to apply the configured ACL settings to a directory containing existing data.

ixVolume (Dataset created automatically by the system)

Use to configure a storage mount for a system created dataset on the applications pool.

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 path/to/directory where the ixVolume mounts inside the container.
Enable ACL	Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Dataset Name	Enter a name for the dataset that is created and used for storage.
ACL Entries	Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type	Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID	Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access	Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.

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 path/to/directory where the share volume mounts inside the container.
Server	(Required) Enter the IP address for the SMB server, for example 192.168.1.100. This can be the TrueNAS host.
Path	(Required) Enter the name of the SMB share, for example my-share.
Username	(Required) Enter the username of an account with permission to access the SMB share.
Password	(Required) Enter the password for the account in Username.
Domain	Enter the directory services domain. Only required if the domain is something other than the TrueNAS default `WORKGROUP`, for example on systems with Active Directory configured.

Tmpfs (Temporary directory created on the RAM)

Use to configure a memory-backed temporary directory. See the Docker tmpfs documentation for more information.

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

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.

Figure 14: Resources Configuration Settings

Settings Information

Setting	Description
Enable Resource Limits	Select to enable resource limits and display the CPUs and Memory (in MB) settings.
CPUs	Enter the maximum number of CPU cores the container can access. For example, 2.
Memory (in MB)	Enter the number of megabytes you want to limit memory to. For example, 4096.
Passthrough available (non-NVIDIA) GPUs	Select to allow the passthrough of non-NVIDIA GPU devices to the container.
Select NVIDIA GPU(s)	Displays if compatible NVIDIA GPU device(s) are installed and detected.
Use this GPU	Select to allow passthrough of the specified NVIDIA device to the container.

Add Custom App Screen

The Add Custom App screen allows you to configure third-party applications using Docker Compose YAML syntax. Use the YAML editor to configure applications not included in the official catalog. See the Docker Compose overview from Docker for more information.

Installing custom applications via YAML requires advanced knowledge of Docker Compose and YAML Syntax. Users should be prepared to troubleshoot and debug their own installations. The TrueNAS forums are available for community support.

TrueNAS applies basic YAML syntax validation to custom applications, but does not apply additional validation of configuration parameters before executing the file as written.

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: Provides information on changing settings that control how TrueNAS displays report graphs, how to interact with graphs, and configuring reporting exporters.

Reporting Screens: Provides information on TrueNAS reporting graph screens and settings.

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.

Interacting with Graphs

Click on and drag a certain range of the graph to expand the information displayed in that selected area in the Graph. Click on the icon to zoom in on the graph. Click on the icon to zoom out on the graph. Click the to move the graph forward. Click the to move the graph backward.

Configuring Reporting Exporters

You can configure TrueNAS to export Netdata information to any time-series database, reporting cloud service or application installed on a server. For example, Graphite, Grafana, etc., installed on a server or use their cloud service.

Creating reporting exporters enables TrueNAS to send Netdata data reporting metrics, formatted as a JSON object, to another reporting entity.

For more information on exporting Netdata records to other servers or services, refer to the Netdata exporting reference guide.

Graphite is a monitoring tool available as an application you can deploy on a server or use their cloud service. It stores and renders time-series data based on a plaintext database. Netdata exports data reporting metrics to Graphite in the format prefix.hostname.chart.dimension. For additional information, see the Netdata Graphite exporting guide.

Adding a Reporting Exporter

To configure a reporting exporter in TrueNAS, you need the:

IP address of the reporting service or server. If using another TrueNAS system with a data reporting application, this is the IP address of the TrueNAS running the application.
Port number the reporting service listens on. If using another TrueNAS system with a reporting application, this is the port number the TrueNAS system listens on (port:80)

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.

To configure a third-party reporting integration, such as Graphite, click Exporters to open the Reporting Exporters screen.

Report Graphs

The following sections provide examples of each report graph. There are a few controls to change the default graph view:

The Auto Refresh toggle updates the graphs with the latest reporting data every few seconds. When active, the graph resets to the chosen Reset Zoom view every time the reporting data updates. Disable Auto Refresh before manually zooming in on any section of the graph.
Step Back () moves the graph backward in time by whatever time increment is currently active in Reset Zoom.
Step Forward () moves the graph forward in time by whatever time increment is currently active in Reset Zoom. The default graph view is to show the latest data, which disables this button.
Zoom Out () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views.
The Reset Zoom indicator shows which time value is active for the graph. The default 1 Hour is the default (and minimum) time period that can be active. When Zoom Out is active, click Reset Zoom to reset the graph view to 1 Hour.
Zoom In () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views. This is active when the graph changes from the default 1 Hour view.

To manually adjust the vertical or horizontal precision of the graph, disable Auto Refresh, then click and drag within the graph view. A left-to-right (or vice-versa) motion increases the horizontal view precision, while an up-to-down (or vice-versa) motion increases the vertical precision.

CPU Graphs

Shows the CPU temperature, CPU usage, and system load graphs. CPU graphs show the amount of time the CPU spends in various states such as executing user code, executing system code, and idle time. Graphs show short-, mid-, and long-term loads, along with CPU temperature graphs.

Figure 1: CPU Reporting Usage and Temperature

Disk 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.

Disk Report Setting Options

Setting	Description
Select All	Displays all available graphs for any or all disks selected on the Disks dropdown list.
Disk Temperature	Displays the minimum, maximum, and mean temperature readings for the disk selected.
Disk I/O	Displays the disk read and write I/O stats in bytes/s.

Temperature monitoring for the disk is disabled if HDD Standby is enabled. Check the Storage > Disks Edit Disk* configuration form for any or all disks in the system if you do not see the temperature monitoring graph.

Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.

Memory Graphs

Shows the Physical memory available graph with the amount of free memory available based on current memory usage.

Network Graphs

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.

System Graphs

Shows the System Uptime graph.

UPS Graphs

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.

ZFS Graphs

Shows the ZFS ARC size graph with compressed physical ARC size.

Reporting Exporters Screen

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.

Add Reporting Exporter

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.

Graphite Settings

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 Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration. Enterprise-licensed HA systems have access to the failover settings located on this screen.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
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: Information on updating TrueNAS, including standard and Enterprise HA update procedures.

Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.
Updating TrueNAS Enterprise HA: Provides instructions on how to update TrueNAS releases on Enterprise (HA) systems.
Update Screens: Provides information on functions and fields on the TrueNAS Update screens.

General Settings: Tutorials and UI reference for TrueNAS General Settings including support, email, localization, and GUI configuration.

Configuring General Settings: Tutorials for configuring many general TrueNAS settings.
Adding a License and Proactive Support: Provides instructions for TrueNAS Enterprise users to add their system license and set up proactive support.
Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.
General Settings Screen: Provides information on the General Settings screen, cards, and configuration settings for getting support, changing console or the GUI, localization and keyboard setups, and system email.

Advanced Settings: Tutorials and UI reference for TrueNAS Advanced System Settings including console, cron jobs, GPU, 2FA, init/shutdown scripts, and system logging.

Configuring Advanced Settings: Tutorials for configuring advanced system settings in TrueNAS.
Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.
Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.
Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.
Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.
Managing Init/Shutdown Scripts: Provides information on adding or modifying init/shutdown scripts in TrueNAS.
Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.
Isolating GPU for VMs: Provides information on isolating Graphics Processing Units (GPU) installed in your system.
Managing Global 2FA (Two-Factor Authentication): Provides information on setting up and managing global two-factor authentication, and logging in with it enabled.
Developer Mode (Unsupported): Provides information on the unsupported TrueNAS developer mode and how to enable it.
Advanced Settings Screen: Provides information on the System Settings > Advanced screen, cards, and configuration screen settings.

Boot: Information on managing TrueNAS boot environments.

Boot Pool Management: Provides instructions on managing the boot pool and boot environments in TrueNAS.
Boot Screens: Provides reference descriptions of the boot environment screens and settings.

Services: Tutorials for TrueNAS services.

Configuring FTP Service: Provides instructions on configuring the FTP service including storage, user, and access permissions.
Configuring NFS Service: Provides information on configuring NFS service in TrueNAS.
Configuring SMB Service: Provides instructions on configuring the SMB service in TrueNAS.
Configuring SNMP Service: Provides information on configuring SNMP service in TrueNAS.
Configuring SSH Service: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.
Configuring UPS Service: Provides information on configuring UPS service in TrueNAS.
Services Screens: Information on the Services screen and individual service articles in the Services area.
FTP Service Screen: Provides information on the FTP services screens and settings.
iSCSI Services Screen: Provides information on iSCSI service screen and settings.
NFS Services Screen: Provides information on NFS service screen and settings.
SMB Service Screen: Provides information in the SMB service screen and settings.
SNMP Service Screen: Provides information on SNMP service screen settings.
SSH Service Screen: Provides information on the SSH service screens and settings.
UPS Services Screen: Provides information on the UPS service screen settings.
WebShare Service Screen: Provides information on the WebShare service screen and settings.

Shell: Information on using the TrueNAS Shell for command-line access directly in the web UI.

Using Shell: Provides information on using the TrueNAS shell.
Shell Screen: Provides information on the TrueNAS Shell screen, buttons, and slider.

Alert Settings Screen: Provides information on Alert Settings service screen settings.

Audit: Information on reviewing and managing TrueNAS audit logs.

Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.
Audit Screen: Provides information on the TrueNAS Audit screens and settings.

View Enclosure Screen (TrueNAS Systems Only): Provides information on the TrueNAS View Enclosure screen available only on compatible TrueNAS hardware systems.

Update

Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.

Updating TrueNAS Enterprise HA: Provides instructions on how to update TrueNAS releases on Enterprise (HA) systems.

Update Screens: Provides information on functions and fields on the TrueNAS Update screens.

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.

Software Update Paths

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.

Selecting an Update Profile

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.

Figure 2: Update Profile

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.

Installing an Update

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.

Why should I save the secret seed?

Note, the secret seed does not store local users passwords in any form, only a hash of the password sufficient for authentication. Hashed passwords are not encrypted.

It is a best practice to always save the secret seed with the system configuration file after making system configuration changes to have a current backup copy to use should the need arise.

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.

Installing a Manual Update File

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.

Update Progress

When a system update starts, appears in the toolbar at the top of the UI. Click the icon to see the current status of the update and which TrueNAS administrative account initiated the update.

Updating TrueNAS Enterprise HA

TrueNAS Enterprise
This procedure only applies to TrueNAS Enterprise (HA) systems. If attempting to migrate from FreeBSD- to Linux-based TrueNAS versions, see TrueNAS Migrations.
Installing, upgrading, or making some changes to TrueNAS on High Availability (HA) systems is complicated and should be guided by Enterprise-level support. Contact TrueNAS Enterprise Support for assistance whenever attempting to install or make some changes to TrueNAS on Enterprise HA hardware.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Updating Enterprise (HA) Systems

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 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.

Why should I save the secret seed?

Note, the secret seed does not store local users passwords in any form, only a hash of the password sufficient for authentication. Hashed passwords are not encrypted.

It is a best practice to always save the secret seed with the system configuration file after making system configuration changes to have a current backup copy to use should the need arise.

Click Install to begin the installation, click Cancel to return to the Update screen.

If manually updating your system:

click Install to the right of Manual Update.
Save the secret seed, and configuration file to a secure location, and click Save Configuration to show the Manual Install screen.
Click Choose File and use the file browser to select the update file downloaded to your system. Click Apply Update to start the update process. After the system finishes updating it restarts.

After the system sign-in screen shows:

Sign in to the TrueNAS UI. If using root to sign in, create the admin account (see step 3). If using admin, continue to the next step.
Verify the system license after the update. Go to System > General Settings. Verify the license information in the screenshot of the Support widget you took before the update matches the information on the Support widget after updating the system.
Verify the admin user settings, or if not created, create the admin user account now.
Before adding a new admin user, create a dataset for home directories if you do not have one already set up.
If editing an existing admin user, select the user on the Credentials > Users screen and click Edit.
If you want the admin account to have the ability to execute sudo commands in an SSH session, set Allow Access to both TrueNAS Access and SSH Access, assign the new admin user the Full Admin role. Add the SSH pubic key, enter and confirm the password, then go to Sudo Commands to set the option for sudo access you want to allow.
Verify Shell is set to bash if you want to give the admin user the ability to execute commands in Shell.
To set a location where the admin user can save or browse files, and then select the dataset path in Home Directory. If set to the default /nonexistent files are not saved for this user.
Click Save to create the user or save changes to the existing user.
Verify the admin user can log in to the UI.
a. Log out of the UI.
b. Enter the admin user credentials in the sign-in splash screen.
After validating access to the TrueNAS UI using the admin credentials, disable the root user password. Go to Credentials > User, select the root user, then click Edit. Select 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.

Update Screen

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.

Installed Version

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.

Other Options

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.

Update Profiles

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.

Figure 4: Update Profile

Apply changes the profile to the selected option.

Available Profiles

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.

Save Configuration Settings Window

The Save configuration settings from this machine before updating? window opens after clicking Install to the right of Manual Install.

Export Password Secret Seed 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.

Manual Update Screen

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: Tutorials for configuring many general TrueNAS settings.

Adding a License and Proactive Support: Provides instructions for TrueNAS Enterprise users to add their system license and set up proactive support.

Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.

General Settings Screen: Provides information on the General Settings screen, cards, and configuration settings for getting support, changing console or the GUI, localization and keyboard setups, and system email.

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.

Configuring Support

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.

Sending Feedback

TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.

Rating a UI Screen

Reporting an Issue

Issue Reporting Example

Bug reports are created in the publicly visible TrueNAS Jira project.

TrueNAS can show a list of existing Jira tickets with similar summaries.

Click Login To Jira To Submit to finish and submit the report.

Reporting an Issue - Enterprise Licensed Systems

TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Figure 5: TrueNAS Enterprise Bug Report Form
Filling out the entire form with precise details and accurate contact information ensures a prompt response from the TrueNAS Customer Support team.

Configuring GUI Options

The GUI card allows users to configure the TrueNAS web interface address. Click Settings on the widget to open the GUI Settings configuration screen.

Changing the GUI SSL Certificate

The system uses a self-signed certificate to enable encrypted web interface connections. To change the default certificate, create or import a certificate as described in Managing Certificates to add it to the dropdown list of certificates available on the system. Select the certificate from the GUI SSL Certificate dropdown list.

Setting the Web Interface IP Address

To set the WebUI IP address, when using IPv4 addresses, select a recent IP address on the Web Interface IPv4 Address dropdown list. This limits the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable. When using an IPv6 address, select a recent IP address from the Web Interface IPv6 Address dropdown list.

Configuring HTTPS Options

To allow configuring a non-standard port to access the GUI over HTTPS, enter a port number in the Web Interface HTTPS Port field.

Select the cryptographic protocols for securing client/server connections from the HTTPS Protocols dropdown list. Select the Transport Layer Security (TLS) versions TrueNAS can use for connection security.

To redirect HTTP connections to HTTPS, select Web Interface HTTP -> HTTPS Redirect. A GUI SSL Certificate is required for HTTPS. Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year. A warning displays when setting this function.

Select Crash Reporting to send failed HTTP request data, which might include client and server IP addresses, tracebacks for failed method calls, and middleware log file contents to TrueNAS.

Sending Usage Statistics and UI Error Reports

To send anonymous usage statistics and WebUI errors to TrueNAS, select the Usage Collection & UI Error Reporting option. When enabled, anonymous usage statistics and WebUI errors are reported to the TrueNAS engineering team. No personally identifiable information is collected.

When disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g., TrueNAS 24.04.0, 55 TB) are collected.

For more information about what usage data is collected, see the TrueNAS Data Collection Statement.

Showing Console Messages

To show real-time console messages at the bottom of the browser window, select Show Console Messages.

Localizing the TrueNAS System

Localizing the TrueNAS system consists of changing the UI language and the keyboard layout to support the selected language 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.

Setting Up System Email

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

Adding a TrueNAS Enterprise License

For users with a valid TrueNAS license, click Add License. Copy your license into the box and click Save.

GeneralSettingsSCALESupportLicenseEntry

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.

GeneralSettingsSCALESupportLicenseComplete

Silver and Gold level Support customers can also enable Proactive Support on their hardware to automatically notify iXsystems if an issue occurs. To find more details about the different Warranty and Service Level Agreement (SLA) options available, see TrueNAS Enterprise Support.

When the system is ready to be in production, update the status by selecting This is a production system and then click the Proceed button. This sends an email to iXsystems declaring that the system is in production.

While not required for declaring the system is in production, TrueNAS has the option to include an initial debug with the email that can assist support in the future.

Setting Up Proactive Support

Silver/Gold Coverage Customers can enable iXsystems Proactive Support. This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.

To configure proactive support, click Get Support on the Support widget located on the System > General Settings screen. Select Proactive Support from the dropdown list.

GeneralSettingsSCALEProactiveSupport

Complete all available fields and select Enable iXsystems Proactive Support, then click Save.

GeneralSettingsSCALEProactiveSupportForm

Setting Up System Email

An automatic script sends a nightly email containing important information such as disk health to configured recipients. For fast awareness and resolution of critical issues, configure TrueNAS system email with the recipient addresses that should receive these notifications.

TrueNAS mails Scrub Task issues separately to the address configured in those services.

Configuring Email Recipients

Starting with TrueNAS 25.10, system emails are sent to a configurable list of recipients rather than automatically using local administrator email addresses. Configure the recipient list in the system email settings to specify who receives system notifications.

Setting Up System Email

Configure the send method and recipients for the email service.

Go to System > General Settings and locate the Email widget to view the current configuration, or click the Alerts icon at the top right of the UI screen, then click the gear settings icon, and select Email to open the General Settings screen.

Click Settings on the Email Widget to open the Email Options screen.

Select one of the three Send Mail Method options:

SMTP
GMail OAuth
Outlook OAuth

The configuration options change based on the selected method.

After configuring the send method, click Send Test Mail to verify you can send email. If the email test fails, verify the recipient addresses are correctly configured in the Email Recipients field.

Save stores the email configuration and closes the Email Options screen.

Configuring Email Using SMTP

To set up SMTP service as the system email send method, you need the outgoing mail server and port number for the email address.

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.

Configuring Email Using GMail OAuth

To set up the system email using Gmail OAuth, use the TrueNAS web UI to log in to your Gmail account.

Select 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.

Configuring Email Using Outlook OAuth

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.

Setting Up the Email Alert Service

After configuring the system email send method, configured recipients receive a system health email every night/morning.

To add or configure the Email Alert Service to send timely warnings when a system alert hits the warning level specified in Alert Settings:

Go to System > Alert Settings or from any screen, click on the Alerts notifications icon at the top right of the screen to open the Alerts panel. Click on the settings settings icon and then on Alert Settings.

Locate Email under Alert Services, select the more_vert icon, and then click Edit to open the Edit Alert Service screen.

Add the alert recipient email address in the Email Address field.

Use the Level dropdown to adjust the email warning threshold or accept the default Warning setting.

Click Send Test Alert to generate a test alert and confirm the email address and alert services work.

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:

Support
GUI
Localization
Email

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.

Support Card

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.

Community Edition Support Card

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.

TrueNAS Enterprise
Enterprise Support Card
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.
Support Banners
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.

Update Production Status Dialog

The Update Production Status dialog can set a TrueNAS Enterprise system to production status and can send an initial system debug to TrueNAS.

Send initial debug starts the debug download and file transfer to TrueNAS.

Proceed starts the process and sets the system to a production system.

Send Feedback Window

The Send Feedback window shows two options: Rate this page and Report a Bug, which is the default selection after clicking File Ticket. The Rate this page is the default selection after clicking the option to rate a new screen shown in early release with new functional screens or redesigned screens.

Report a Bug

Subject is a text entry field for a brief description of an issue experienced. For example, Traceback received when pressing Save.

Message is a text entry field for a longer description of what steps were taken and the result. The field provides examples of what to enter. This content populates the Jira ticket description field after clicking Login To Jira To Submit.

Attach debug, which is selected by default, downloads and attaches a system debug to the Private Attachment Area TrueNAS provides to secure user confidential data that is part of the debug file.

Take screenshot of the current page, selected by default, takes a screenshot of the current screen.

Attach additional images opens a file browser where you can locate and attach saved logs, screenshots, or video files that help explain the issue reported in the ticket.

Login To Jira To Submit opens a Jira login screen where you enter your Jira credentials so TrueNAS can create the ticket for you using your credentials.

Rate this page

Select the Rate this page to show options to submit review feedback on a UI screen.

Stars set a rating using one (lowest) to five (best) stars.

Message is a text entry field for comments about the screen you are rating. Include what you like, don’t like, works well, or does not work well, and your 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.

License Screen

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.

Proactive Support Screen

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.

GUI Settings Screen

The GUI Settings screen shows configuration settings for the TrueNAS web interface.

GUI Settings

Setting	Description
GUI SSL Certificate	Sets the selected certificate as the SSH certificate. truenas_default is the default certificate. The system uses a self-signed certificate to enable encrypted web interface connections. Manage Certificates opens the Certificates screen. Certificates added or imported into TrueNAS show on this list.
Web Interface IPv4 Address	Sets an IP address to limit the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface IPv6 Address	Sets an IPv6 address from the dropdown list to limit usage when accessing the administrative GUI. The default is ::. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface HTTP Port	Sets a non-standard port to access the GUI over HTTP. The default is 80. Changing this setting might require changing a Firefox configuration setting.
Web Interface HTTPS Port	Sets a non-standard port to access the GUI over HTTPS. The default is 443.
HTTPS Protocols	Sets a cryptographic protocol(s) for securing client/server connections. Select the Transport Layer Security (TLS) versions TrueNAS can use for connection security from the dropdown list of options: TLSv1 TLSv1.1 TLSV1.2 selected by default TLSv1.3 (selected by default)
Web Interface HTTP -> HTTPS Redirect	Redirects HTTP connections to HTTPS. A GUI SSL certificate is required for HTTPS. Activating this sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year. After adding a new certificate, select it or use the default TrueNAS certificate in GUI SSL Certificate.
Usage Collection & UI Error Reporting	When enabled, anonymous usage statistics and WebUI errors are reported to the TrueNAS engineering team. No personally identifiable information is collected. When disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g. TrueNAS 24.04.0, 55 TB) are still collected. Information about system configuration and usage is not collected. For more information about what usage data is collected, see the TrueNAS Data Collection Statement.
Show Console Messages	Shows console messages in real-time at the bottom of the browser screen.

Localization Settings Screen

The Localization 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.

Localization Settings

Setting	Description
Console Keyboard Map	Sets a language for the keyboard layout, for example, English (US) for American English. Select an option on the dropdown list, or type in the field to filter the list to show matching languages.
Timezone	Set the geographical time zone for the system. Allows filtering the list by typing in the field after clearing the default value. Or scroll down to locate and select a timezone from the dropdown list.

Email Options 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.

SMTP Email 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.

SMTP Settings

Setting	Description
From Email	Sets the user account email address used for the envelope From email address, the address sending emails.
From Name	Sets the name shown in front of the sending email address, for example, truenas system 1 in truenas system 1@example.com.
Outgoing Mail Server	Sets the host name or IP address of the SMTP server used to send emails.
Mail Server Port	Sets the SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).
Security	Sets the security option to what is selected on the dropdown list. Options are: Plain (No Encryption) SSL (Implicit TLS) TLS (STARTTLS) For more information on types, see email encryption.
SMTP Authentication	Select to enable SMTP AUTH using plain Simple Authentication and Security Layer (SASL) for authentication and data security. Applies and requires a valid simple username and password authentication method.
Username	Shows after selecting SMTP Authentication. Sets the username of the sending email account, which is typically the full email address. Enter the username if the SMTP server requires authentication.
Password	Shows after selecting SMTP Authentication. Sets the password for the sending email account for the SMTP server. Only plain ASCII characters are accepted.

OAuth Email Options

Gmail OAuth and Outlook OAuth options show the From Email and From Name fields and a log-in-to button for the email method selected. GMail OAuth shows Log In To Gmail and Outlook OAuth shows Log In To Outlook. These login methods step through a sequence of login screens for the selected method. For more information, see Setting Up System Email

Advanced Settings

TrueNAS Advanced Settings provide configuration options for console, scheduled tasks, hardware resources, security, and system logging.

Configuring Advanced Settings: Tutorials for configuring advanced system settings in TrueNAS.

Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.

Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.

Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.

Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.

Managing Init/Shutdown Scripts: Provides information on adding or modifying init/shutdown scripts in TrueNAS.

Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.

Isolating GPU for VMs: Provides information on isolating Graphics Processing Units (GPU) installed in your system.

Managing Global 2FA (Two-Factor Authentication): Provides information on setting up and managing global two-factor authentication, and logging in with it enabled.

Developer Mode (Unsupported): Provides information on the unsupported TrueNAS developer mode and how to enable it.

Advanced Settings Screen: Provides information on the System Settings > Advanced screen, cards, and configuration screen settings.

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).

TrueNAS Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration.

Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.

Figure 2: Advanced Settings Screen (cont.'d)

TrueNAS Enterprise
Enterprise-licensed systems include configuration options for STIG and FIPS security, and failover when the system is a High Availability system.
Figure 4: Advanced Settings Screen for HA

Configuring System Auditing

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.

Figure 5: Advanced System Setting Audit Card

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.

Audit Settings

Settings	Description
Retention (in days)	Enter the number of days to retain local audit messages.
Reservation (in GiB)	Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)	Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)	Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range: 5 - 80.
Quota Fill Critical (in %)	Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range: 50 - 95.

Click Configure to open the Audit configuration screen and to manage storage and retention policies for audit logs.

Managing Tunable Variables

Use Add on the Tunable card to add a tunable that configures a kernel module parameter at runtime.

AdvancedSettingsTunableCard

The Add Tunable screen shows the settings.

AddTunableScreen

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 1024³)
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.

Adding NTP Servers

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.

Managing the System Dataset

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.

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.

Figure 8: System Dataset Pool Config Screen

Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward. If the encrypted pool already has a passphrase set, you cannot move the system dataset to that pool.

Changing Resilvering Priority

To set a different resiliver priority, select Run Resilvering At Higher Priority At Certain Times. Two additional setting options show that allow you to configure the day and time range for resilvering to run.

To return to the default resilver priority, clear the checkbox and click Save.

Setting the Number of Replication Tasks

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.

SystemAdvancedSettingsReplicationWidget

Click Configure to open the Replication configuration screen.

AdvancedSettingsReplicationConfigScreen

Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.

Managing Allowed IP Addresses

Use the System > Advanced Settings screen Allowed IP Addresses configuration screen to restrict access to the TrueNAS web UI and API.

Entering an IP address limits access to the system to only the address(es) entered here. To allow unrestricted access to all IP addresses, leave this list empty.

Managing Access (WebSocket Sessions)

The Access widget shows a list of all active sessions, including the current logged-in user 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.

Changing the Session Timeout

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.

Allowing Directory Service Users to Access the UI

TrueNAS Enterprise
Only Enterprise-licensed systems allow TrueNAS web UI access for Directory Service accounts

TrueNAS allows Enterprise users to show the UI to users in an Active Directory group. To configure this access, first, add the selected AD users to a group that is granted a TrueNAS privilege that permits it, and enable the Allow Directory Service users to access WebUI option on the Access Settings screen. This option only shows on Enterprise-licensed systems.

Access Settings Screen Enterprise Systems — Figure 12: Access Settings Screen Enterprise Systens

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.

Installing NVIDIA Drivers

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.

Security Settings

TrueNAS Enterprise
Only Enterprise-licensed systems show the Security card and have access to the STIG and FIPS settings.
Administrators considering enabling STIG and FIPS security settings should contact TrueNAS Support before making any changes.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

STIG and FIPS Considerations

Review these topics and contact TrueNAS Support before enabling STIG and FIPS security settings.

When STIG (and FIPS) are enabled:

TrueNAS cannot issue API keys, and existing API keys cannot be used for authentication. Only the user credential with a two-factor authentication method is accepted.
SSH log-ins require a cryptographic algorithm.
SMB authentication for local TrueNAS accounts is disabled.
NTLM authentication passthrough to a domain controller is disabled.
Usage stats are not reported, and the Usage Collection option is disabled.
One-time passwords (OTP) configured for administrative users have a single use and expire after 24 hours. After logging in with the OTP, the system prompts the user to immediately change the password and set up two-factor authentication.
TrueNAS is limited to a maximum of 10 concurrent sessions. Accounts lock for 15 minutes after three consecutive failed login attempts.
Password aging rules are applied to the SMB protocol. After a failed login attempt, users with expired passwords receive a password-expired message.
TrueNAS prompts users to change their passwords when logging in, and the system flags the account as requiring this change. Users cannot reuse a password if it is marked as used within the last five passwords in the history file. Passwords must be 15 characters in length.
TrueNAS updates can only use a signed update file provided by the TrueNAS team.

What features are not available?

When enabled, STIG disables these features:

Virtualization
Apps
TrueCommand connectivity

What events are included in auditing?

When STIG (and FIPS) are enabled, auditing includes these events:

Account creation events
Privilege commands (with full text of the commands run)
Privilege changes
Log-ins and other system access events. Account log-ins are tracked from two distinct sources (UI and SSH)
Kernel module load/unload
Audit log modifications and attempts to modify audit logs
Security object modifications and attempts to modify security objects

Configuring STIG and FIPS

To set up FIPS or STIG compliance on a TrueNAS server, you must first configure two-factor authentication for an admin user with full permissions.

After configuring two-factor authentication, go to System > Advanced Settings and locate the Security card.

Click Settings to open the System Security configuration screen.

SystemSecurityScreen

Select the toggle to enable FIPS and STIG, then click Save. You must enable FIPS with STIG! The system prompts you to restart.

SecurityFIPSSTIGRestartDialog

The system restart takes several minutes to complete before showing the login screen. Highly Available (HA) systems must restart each storage controller before STIG mode is fully enabled.

TrueNAS Administrator Password Rules

The remaining options are for setting TrueNAS administrator password rules. Options include defining a password lifetime, types of characters that must be present in the password, how many characters must be present in a valid password, and how many previously used passwords to remember for an account and prevent reuse in a new password.

Adjust these as needed for your security requirements. Enabling STIG compatibility mode requires specific minimum values for these settings.

Note that TrueNAS begins warning all local account types (administrator, full admin, read-only, and sharing-only) seven days before password expiration. After expiration, the account locks and requires administrative action to unlock.

Additional Content

Managing the System Configuration

TrueNAS allows users to manage the system configuration by uploading or downloading configurations or by resetting the system to the default configuration.

System Configuration Options

The Manage Configuration option on the System > Advanced Settings screen provides three options:

Download File that downloads your system configuration settings to a file on your system.
Upload File that allows you to upload a replacement configuration file.
Reset to Defaults resets system configuration settings back to factory settings.

Downloading the File

The Download File option downloads your TrueNAS current configuration to the local machine.

A system config file is a database file containing your settings, including accounts, directory services, networking, services, shares, storage configuration, system settings, data protection tasks, and more.

In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file. Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations. See Using Administrator Logins for more information on admin account types.

Why should I save the secret seed?

Note, the secret seed does not store local users passwords in any form, only a hash of the password sufficient for authentication. Hashed passwords are not encrypted.

It is a best practice to always save the secret seed with the system configuration file after making system configuration changes to have a current backup copy to use should the need arise.

Physically secure the config file with the secret seed, and any encryption key files to decrypt encrypted datasets or pools.

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.

Uploading the File

The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS configuration file.

Do I need to upload a config file?

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.

Resetting to Defaults

TrueNAS Enterprise
Enterprise High Availability (HA) systems should never reset their system configuration to defaults. Contact TrueNAS Enterprise Support if you need to reset the system configuration.
TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

Save the current system configuration with the Download File option before resetting the configuration to default settings! If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.

The Reset to Defaults option resets the system configuration to factory settings. After the configuration resets, the system restarts, and users must set a new login password.

Remote Backups of the Config File

TrueCommand provides an easy solution for users who want to schedule an automatic remote backup of the system configuration file:

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.

AdvancedSystemSettingsConsoleWidget

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.

ConsoleConfigScreen

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.

AdvancedSettingsCronJobWidget

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.

AddCronJobsScreen

Enter a description for the cron job.

Next, enter the full path to the command or script to run in Command. For example, for a command string to create a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt.

Select a user account to run the command from the Run As User dropdown list. The user must have permissions allowing them to run the command or script.

Select a schedule preset or choose Custom to open the advanced scheduler. An in-progress cron task postpones any later scheduled instances of the task until the one already running completes.

Cron Job Schedule Format

Cron job schedules use six asterisks that represent minutes, hours, days of the month, days of the week, and months in that order.

For example, a schedule of 1 1 1 * sat,sun would run at 01:01 AM, on day 1 of the month, and only on Saturday and Sunday.

Separate multiple values for a segment with commas, not spaces.

If you want to hide standard output (stdout) from the command, select Hide Standard Output. If left cleared, TrueNAS emails any standard output to the user account cron that ran the command.

To hide error output (stderr) from the command, select Hide Standard Error. If left cleared, TrueNAS emails any error output to the user account cron that ran the command.

Select Enabled to enable this cron job. Leave this checkbox cleared to disable the cron job without deleting it.

Click Save.

The TrueNAS UI has several fields that allow users to write custom scripts. When a user writes a password into a custom script, the password is provided in cleartext form within system debug files, creating a serious security concern.
We do not recommend using custom scripting on TrueNAS, as it is a highly advanced feature for expert storage administrators and can lead to security breaches.

Managing 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.

Adding an Init/Shutdown Script

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 must have the execute bit set. By default scripts run using dash(1), but you can run a script under a different interpreter by including a shebang line (for example, #!/bin/bash) as the first line of the script.

Select the option from the When dropdown list for the time this command or script runs.

Enter the number of seconds after the script runs that the command should stop in Timeout.

Select Enable to enable the script. Leave clear to disable but not delete the script.

Click Save.

Script Execution

Scripts run at different points in the system lifecycle based on the option you select in the When dropdown:

Pre Init: Select to run a script early in the boot process, after filesystems and networking are available.
Post Init: Select to run a script later in the boot process, just before TrueNAS services start.
Shutdown: Select to run a script during system shutdown, after services begin stopping.

Scripts in the same category (for example, multiple Post Init scripts) run sequentially in the order in which the user added them.

Use the Timeout setting to limit how long each script runs. A script that hangs or takes too long delays the next script in that category.

Shutdown scripts run while the system powers down, so not all services or resources remain available.

Editing an Init/Shutdown Script

Click a script listed on the Init/Shutdown Scripts widget to open the Edit Init/Shutdown Script configuration screen populated with the settings for that script.

You can change from a command to a script, and modify the script or command as needed.

To disable but not delete the command or script, clear the Enabled checkbox.

Click Save.

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.

TrueNAS Enterprise
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.

Configuring Global SED Settings

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!

Configuring Individual SED Passwords

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).

Isolating 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.

About TrueNAS 2FA

To use 2FA, you need a mobile device (or desktop application) with the correct time and date, and a TOTP-compatible authenticator app installed.

TrueNAS uses the TOTP (Time-based One-Time Password) standard (RFC 6238), which is compatible with most authenticator apps. Popular options include:

Microsoft Authenticator (iOS, Android)
Google Authenticator (iOS, Android)
Authy (iOS, Android, desktop)
Bitwarden (cross-platform, open source)
1Password (cross-platform)

Choose an authenticator app based on your platform and preferences. All TOTP-compatible apps work with TrueNAS.

Two-factor authentication is time-based and requires a correct system time setting. We strongly recommend ensuring Network Time Protocol (NTP) is functional before enabling two-factor authentication!

What is 2FA and why should I enable it?

2FA adds an extra layer of security to your system to prevent someone from logging in, even if they have your password. 2FA requires you to verify your identity using a randomized six-digit code that regenerates every 30 seconds (unless modified) to use when you log in.

Enabling global 2FA prompts users to set up their individual 2FA secrets but does not require it unless the system is in STIG compatibility mode.

Benefits of 2FA

Unauthorized users cannot log in since they do not have the randomized six-digit code.

Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.

Internet access on the TrueNAS system is not required to use 2FA.

Drawbacks of 2FA

2FA requires an app to generate the 2FA code.

If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled). You can bypass or unlock 2FA using the CLI.

Enabling Global 2FA

Set up a second 2FA device as a backup before proceeding.

Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.

Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure.
Figure 1: Global Two Factor Authentication Settings Widget
Select Enable Two Factor Authentication Globally, then click Save.
Figure 2: Check Enable Two Factor Authentication Globally
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.

Disabling Global 2FA

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.

Reactivating Global 2FA

If you want to enable 2FA again, go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click 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.

Setting Up Individual 2FA

When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. Users can also set up 2FA at any time by 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.
Figure 3: 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.
Figure 4: Set Up Two-Factor Authentication Screen
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.

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.

Removing Individual 2FA Configuration

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

Administrator Clearing User 2FA

Administrators can clear 2FA for any user without needing to log in as that user. This is useful when:

A user has lost access to their authenticator device
A user is locked out due to 2FA issues
Troubleshooting login problems for users

To clear 2FA for another user:

Go to Credentials > Users
Select the user whose 2FA needs to be cleared
Click Clear Two-Factor Authentication on the Access widget
Confirm the action in the dialog

After clearing, the user can log in without 2FA. If Global 2FA is still enabled, they are prompted to reconfigure 2FA on their next login.

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.

Using 2FA to Log in to TrueNAS

Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.

Logging In Using the Web Interface

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.

2FA Signin Splash Screen — Figure 5: 2FA Splash Screen

TOTP codes regenerate every 30 seconds (by default). If a code expires while you are entering it, wait for your authenticator app to display a new code and retry.

Logging In Using SSH

Confirm that you set Enable Two Factor 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.

Figure 3: Example - TrueNAS Appliance Warning

However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.

Do not make system changes using the TrueNAS UI web shell. Using package management tools in the web shell can result in middleware changes that render the system inaccessible.
Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.

To enable developer mode, log into the system as the root account and access the Linux shell. Run the install-dev-tools command.

Running install-dev-tools removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS. These changes do not persist across updates and install-dev-tools must be re-run after every system update.

Troubleshooting

install-dev-tools is a developer-focused option that might not work in scenarios beyond those intended by TrueNAS developers, such as modified installations or deployments that use non-default settings.

Users with NVIDIA GPU drivers installed cannot enable developer mode while the NVIDIA kernel module is mounted. Running install-dev-tools in this state results in the following error:

/usr is currently provided by a readonly systemd system extension.
This may occur if nvidia module support is enabled. System extensions
must be disabled prior to disabling rootfs protection.

This happens because the NVIDIA drivers are overlaid onto /usr via systemd-sysext, making it read-only by design. To resolve the issue, unmerge systemd-sysext, run install-dev-tools, then merge system extensions again.

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.

TrueNAS Enterprise
Enterprise-licensed systems include configuration options for STIG and FIPS security, and failover when the system is a High Availability system.
Figure 4: Advanced Settings Screen for HA

Manage Configuration

The Manage Configuration dropdown shows two options: one to download the system config file and the other to upload a system config file. The option to reset system settings to the default configuration shows after uploading a configuration file.

Download File

Download File opens the Save Configuration dialog, where users can download the current system configuration to their local machine.

The Export Password Secret Seed option is selected by default. It stores hashes of the passwords sufficient for authentication in the system, but does not store user passwords. The secret seed is used to decrypt encrypted fields in the TrueNAS configuration database. Various fields are encrypted because they might contain sensitive information such as cryptographic certificates, passwords (not user login passwords), or weak hashing algorithms (for example, NT hashes of SMB users). When a config file is restored without the secret seed, encrypted fields are set to empty values. This means various services can be broken due to the missing information. Examples are SMB via local accounts and apps.

Upload File

The Upload File option opens the Upload Config dialog, which allows users to choose a previously saved TrueNAS configuration to replace the current system configuration. This is useful when restoring system configuration settings after a clean install of a TrueNAS release.

Choose File opens a file browser window to locate the downloaded and saved configuration file. After selecting the file, the Upload Config window opens. Upload starts the upload of the selected configuration file.

All passwords are reset if the uploaded configuration file was saved without Export Password Secret Seed enabled.

Reset to Defaults

The Reset to Defaults option opens the Reset Configuration dialog. Using Resetting to Defaults returns the system configuration to factory settings and restarts the system. Users must set a new login password.

Save the current system configuration with the Download File option before resetting the configuration to default settings.
Not saving the system configuration before resetting it can result in losing data that is not backed up and losing the ability to revert to the previous configuration.

Console Card

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 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.

Console Settings

Settings	Description
Show Text Console without Password Prompt	Select to display the console without being prompted to enter a password. Leave cleared to add a login prompt to the system before showing the console menu. Selected by default.
Enable Serial Console	Select to enable the serial console. Selected by default. Clear this if the serial port is disabled.
Serial Port	Shows the default serial port. If using a port other than the default, enter the serial console port address.
Serial Speed	Shows the default serial port speed. If not using the default speed, select the speed (in bits per second) the serial port uses from the dropdown list. Options are 9600, 19200, 38400, 57600, or 115200.
MOTD Banner	Enter the message you want to display when a user logs in with SSH. The default banner message is Welcome to TrueNAS.

Syslog Card

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.

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.

Syslog Settings

Settings	Description
Use FQDN for Logging	Select to include the fully qualified domain name (FQDN) in logs to identify systems with similar host names.
Syslog Level	Select the minimum log priority level to send to the remote syslog server. The system only sends logs at or above this level.
Syslog Server	Enter the remote syslog server DNS hostname or IP address. Add a colon and the port number to the hostname to use non-standard port numbers, like mysyslogserver:1928. Log entries are written to local logs and sent to the remote syslog server. Add Syslog Server shows a block of settings to configure a syslog server. Allows adding two servers.
Host	Syslog Server setting. Sets the remote syslog server DNS host name or IP address. Allows using non-standard port numbers by adding a colon and the port number to the host name, like mysyslogserver:1928. Log entries are written to local logs and sent to the remote syslog server.
Transport	Syslog Server setting. Sets the transport protocol for the remote system log server connection. Selecting Transport Layer Security (TLS) shows the TLS Certificate field. This setting requires pre-configuring the server system certificate if not using the Truenas_default certificate.
TLS Certificate	Syslog Server setting that shows after selecting TLS in Transport. Select the transport protocol for the remote system log server TLS certificate from the dropdown list. Select the default or import a certificate using the Credentials > Certificates screen, Certificates card.
Include Audit Logs	Select to enable audit logging.

Audit Card

Configure Auditing

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.

Audit Settings

Settings	Description
Retention (in days)	Enter the number of days to retain local audit messages.
Reservation (in GiB)	Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)	Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)	Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range: 5 - 80.
Quota Fill Critical (in %)	Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range: 50 - 95.

Click Configure to open the Audit configuration screen and manage storage and retention policies

Kernel Card

The Kernel card shows options for configuring the Linux kernel installed with TrueNAS.

Kernel Settings

Settings	Description
Enable Debug Kernel	Set to boot a debug kernel after the next system restart. This is intended for troubleshooting scenarios only and should typically remain disabled. Enabling this option disables any Nvidia drivers present on the system.

Cron Jobs Card

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.

Add or Edit Cron Job Configuration Screen

The Add Cron Job and Edit Cron Job configuration screens display the same settings.

Cron Jobs lets users configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.

Cron Job Settings

Settings	Description
Description	Enter a description for the cron job.
Command	Enter the full path to the command or script to run. For example, to create a command string that generates a list of users on the system and writes that list to a file, enter `cat /etc/passwd > users_$(date +%F).txt`
Run As User	Select a user account to run the command. The user must have permissions allowing them to run the command or script.
Schedule	Select a schedule preset or choose Custom to open the advanced scheduler. Note that an in-progress cron task postpones any later scheduled instance of the same task until the running task is complete.
Hide Standard Output	Select to hide standard output (stdout) from the command. If left cleared, TrueNAS mails any standard output to the user account cron that ran the command.
Hide Standard Error	Select to hide error output (stderr) from the command. If left cleared, TrueNAS mails any error output to the user account cron that ran the command.
Enabled	Select to enable this cron job. Leave cleared to disable the cron job without deleting it.

Init/Shutdown Scripts Card

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.

Add or Edit Init/Shutdown Script Configuration Screens

Init/Shutdown Scripts lets users schedule commands or scripts to run at system startup or shutdown.

Init/Shutdown Script Settings

Settings	Description
Description	Comments about this script.
Type	Select Command for an executable or Script for an executable script.
Command	Enter the command with any options.
Script	Select the script. Scripts run using dash(1) by default, or under the interpreter named in the shebang line of the script (for example, `#!/bin/bash`).
When	Select when the command or script runs from the dropdown list. Options are Pre Init for early in the boot process, after mounting file systems and starting networking. Post Init runs at the end of the boot process before Linux services start. Shutdown runs during the system power-off process. Scripts in the same category (for example, multiple Post Init scripts) run sequentially in the order in which the user added them.
Enabled	Select to enable this script. When left cleared, it disables the script without deleting it.
Timeout	Automatically stop the script or command after the specified number of seconds.

Tunable Card

The Tunable card shows the existing sysctl settings on the system.

Add to add a tunable that configures a kernel module parameter at runtime.

Add Tunable Screen

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.

Tunable Settings

Settings	Description
Type	Sets the type of tunable to configure. Shows 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. Best used for general system performance, network stack, memory pressure, security hardening (e.g., against SYN floods: `net.ipv4.tcp_syncookies=1`). They are written to /proc/sys/ at runtime via `sysctl -w` and are made persistent via files in /etc/sysctl.d/ or /etc/sysctl.confM/file>. Variables persist across system reboots if set in config files. 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 applied when the rules files ending in `.rules` in /etc/udev/rules.d. The udev daemon (udevd) parses them on device events. 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 (ARC/L2ARC), compression, dedup, scrub/resilver behavior, and I/O patterns. They only apply to ZFS filesystem/modules, and are applied when written to /sys/module/zfs/parameters/ at runtime (after module load). Runtime changes are lost on reboot or module reloads. Use modprobe config for boot-time persistence.
Variable	Enter the name of the variable to configure. Tunables configure system parameters while the system is running, and they generally take effect immediately.
Value	Enter a value for the tunable. For a SYSCTL tunable, enter a sysctl value to use for the loader, sysctl variable.
Description	Enter a description for the tunable.
Enabled	Select to enable this tunable. Leave clear to disable this tunable without deleting it.

Adding NTP Servers

Add NTP Server Screen

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.

Add NTP Servers Screen — Figure 22: Add NTP Server Screen

Add NTP Server Settings

Setting	Description
Address	Sets the host name or IP address of the NTP server.
Burst	Enables using a non-public NTP server. Recommended when Max Poll is greater than 10. Only use on personal NTP servers or those under direct control. Do not enable it when using public NTP servers.
IBurst	Enables and speeds up the initial synchronization (seconds instead of minutes).
Prefer	Enable when using highly accurate NTP servers such as those with time monitoring hardware. Only use these highly accurate NTP servers.
Min Poll	Sets the minimum polling interval. Enter a numeric value in seconds, as a power of 2. For example, 6 means 2^6, or 64 seconds. The default is 6, and the minimum value is 4.
Max Poll	Sets the maximum polling interval. Enter a number in seconds, as a power of 2. For example, 10 means 2^10, or 1,024 seconds. The default is 10, and the maximum value is 17.
Force	Enable to force the addition of the NTP server, even if it is currently unreachable.

Storage Card

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.

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.

Replication Card

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.

Access Card

The Access widget shows a list of all active sessions, including the current logged-in user session and the time it started.

Administrators can manage other active sessions and configure the session timeout for their accounts.

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.

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.

TrueNAS Enterprise
Enterprise-licensed systems include the Allow Directory Service users to access WebUI option on the Access Settings screen. After enabling this option, TrueNAS automatically creates a new entry, named as the domain admin group, in the Privileges screen table. For example, if the domain is ad03.mydomain.net, then you should see a group of that name listed as well as any of the groups AD creates on the system.

Allowed IP Addresses Card

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.

Self-Encrypting Drive Card

TrueNAS Enterprise
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.

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.

Figure 32: Self-Encrypting Drive Config Screen

Self-Encrypting Drive Settings

Settings	Description
SED Password	Enter the global password to unlock SEDs.
Confirm SED Password	Re-enter the global password to unlock SEDs.

Isolated GPU Device(s) Card

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.

Isolated GPU PCI IDs Configuration Screen

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.

NVIDIA Drivers Card

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.

Global Two Factor Authentication Card

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.

Global Two Factor Authentication Card — Figure 37: Global Two Factor Authentication Settings Card

Configure opens the Global Two Factor Authentication configuration screen.

Global Two Factor Authentication Settings

Setting	Description
Enable Two Factor Authentication Globally	Select to prompt users to set up 2FA for the system. When enabled, users without 2FA configured are prompted to set it up on their next login. Users can skip the initial setup if needed.
Window	Enter the number of valid authentication codes (tolerance window). Extends code validity beyond the current to the previous code(s) based on the number entered. For example, setting this to 1 means the current and previous codes are valid. If the previous code is a and the current code is b, then both codes are valid. If set to 2, the current code (c) and the two previous codes (a and b) are valid. Setting this to 3 works the same. Extending the window is useful in high-latency situations.
Enable Two Factor Authentication for SSH	Select to enable 2FA for system SSH access. Leave this disabled until you complete a successful test of 2FA with the UI.

System Security Card

TrueNAS Enterprise
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.

Failover Card

TrueNAS Enterprise
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.

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 or From Peer

Sync To Peer and Sync From Peer buttons each open a confirmation dialog before TrueNAS performs the operation requested.

FailoverSyncToPeerDialog

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: Provides instructions on managing the boot pool and boot environments in TrueNAS.

Boot Screens: Provides reference descriptions of the boot environment screens and settings.

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.

Boot Environments

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.

Following Best Practices

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.

Activating a Boot Environment

The option to activate a boot environment only displays for boot entries not set to Active

Activating an environment means the system boots into the point of time saved in that environment the next time it is started. Click the Activate (Activate) icon for an inactive boot environment to open the Activate dialog.

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 a Boot Environment

Cloning copies the selected boot environment into a new inactive boot environment that preserves the boot-pool state at the clone-creation time.

Click the Clone (Clone) icon to open the Clone Boot Environment window.

Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.

The Source field displays the boot environment you are cloning. If the displayed name is incorrect, close the window and select the correct boot environment to clone.

Click Save.

Deleting a Boot Environment

Deleting a boot environment removes it from the ** Boot Environment** screen and the boot menu.

Click on the Delete (Delete) icon for a boot environment to open the Delete dialog. Select Confirm and then click Delete.

You cannot delete the default or any active entries. Because you cannot delete an activated boot entry, this option does not show for activated boot environments. To delete the active boot environment, first, activate another entry and then delete the environment you want to remove.

Keeping a Boot Environment

By default, TrueNAS prunes boot environments when the boot pool runs out of remaining storage space.

Keep toggles with the Unkeep option, and they determine whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.

Click the Keep (Keep) icon for a boot environment to open the Keep dialog. Select Confirm and then click Keep Flag.

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.

Recovering a Boot Pool

When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and restore your system configuration. This process involves a complete system rebuild while preserving your data pools and configuration settings.

Recovery Steps

Replace the failed boot drive - Install a new drive to serve as the boot device.
Perform a clean TrueNAS installation - Follow the standard installation procedure to install TrueNAS on the new boot drive.
Upload your configuration file - Use your previously saved configuration backup to restore system settings:
- Go to System > General > Manage Configuration
- Click Upload Config and select your configuration backup file
- Follow the prompts to restore your settings
Import existing data pools - Your data pools should be automatically detected and imported after the configuration restore. If not:
- Go to Storage > Import Pool
- Select your existing pools and import them

Important Considerations

By default, TrueNAS creates a new boot environment when you update or reinstall the system, 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 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

Changing the Scrub Interval

The Stats/Settings option shows current system statistics. It also allows you to change the scrub interval or how often the system runs a data integrity check on the operating system device.

Go to the System > Boot Environment screen and click Stats/Settings. The Stats/Settings window shows statistics for the operating system device: Boot Pool Condition as Online or Offline, Size in GiB, the consumed space in Used, and Last Scrub Run with the date and time of the most recent scrub task. By default, the operating system device is scrubbed every seven days.

Figure 6: Boot Environment Stats/Settings

To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.

Boot Pool Device Management

From the Boot Environment screen, click Boot Pool Status to open the Boot Pool Status screen. This screen shows the boot-pool. Expand it to show the devices allocated to that pool. Read, write, or checksum errors show for the pool.

Replace Device

Click the more_vert to open the Actions options. Click Replace, select the device from the Member Disk dropdown, and then click Save.

Attach Device

Click the more_vert 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.

Scrubbing a Boot Pool

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.

Boot Pool Status

The System > Boot > Boot Pool Status screen shows the status of the current boot pool. It includes the current status, the path, and the number of read, write, and checksum errors.

The 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 more_vert shows two options, Replace and Attach.

Replace opens the Replace window.

Attach opens the Attach window.

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.

Replace 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.

Clone Boot Environment Screen

Each time the system updates to a new software release, it creates a new boot environment. The CloneClone icon button opens the Clone Boot Environment screen where you can clone an existing boot environment to create an operating system restore point.

Name - The name of the new cloned boot environment. The name can use upper and lowercase alphanumeric and special characters dash (-), underscore (_), and periods (.).

Source shows the selected boot environment to be cloned.

Batch Operations

Select the checkbox to the left of each boot environment to show the Batch Operations option at the top of the screen. Currently only Delete is available as a batch operation.

Delete opens the Delete window.

Services

TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

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: Provides instructions on configuring the FTP service including storage, user, and access permissions.

Configuring NFS Service: Provides information on configuring NFS service in TrueNAS.

Configuring SMB Service: Provides instructions on configuring the SMB service in TrueNAS.

Configuring SNMP Service: Provides information on configuring SNMP service in TrueNAS.

Configuring SSH Service: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.

Configuring UPS Service: Provides information on configuring UPS service in TrueNAS.

Services Screens: Information on the Services screen and individual service articles in the Services area.

FTP Service Screen: Provides information on the FTP services screens and settings.

iSCSI Services Screen: Provides information on iSCSI service screen and settings.

NFS Services Screen: Provides information on NFS service screen and settings.

SMB Service Screen: Provides information in the SMB service screen and settings.

SNMP Service Screen: Provides information on SNMP service screen settings.

SSH Service Screen: Provides information on the SSH service screens and settings.

UPS Services Screen: Provides information on the UPS service screen settings.

WebShare Service Screen: Provides information on the WebShare service screen and settings.

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 to configure the related service.

Configuring FTP Service

FTP requires a new dataset and a local user account.

Go to Storage to add a new dataset to use as storage for files.

Next, add a new user. Go to Credentials > Users and click Add to create a local user on the TrueNAS.

Assign a user name and password, and link the newly created FTP dataset as the user home directory. Add ftp to the Auxiliary Groups field. You can do this for every user or create a global account for FTP (for example, OurOrgFTPaccnt). You cannot create multiple accounts utilizing the same dataset as your home directory.

By default, only members of the ftp group can authenticate via FTP. Add your newly created user to the ftp group, or change this behavior in the FTP service configuration:
Enable Allow Local User Login to allow any local user to authenticate
Enable Allow Anonymous Login to allow anonymous connections without authentication
Dataset permissions are configured separately and control what files authenticated users can access.

Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.

Enter or select the new user account in the User and Group fields. Select Apply User and Apply Group. Select the Read, Write, and Execute for User, Group, and Other you want to apply. Click Save.

Configuring Service Settings

To configure FTP, go to System > Services and find FTP, then click to open the Services > FTP screen.

Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.

When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.

To confine FTP sessions to the home directory of a local user, select chroot.

Authentication Options:

By default, only ftp group members can authenticate (no additional configuration needed)
Enable Allow Local User Login to allow any local user to authenticate without ftp group membership
Enable Allow Anonymous Login to allow anonymous connections without authentication

Do not allow anonymous access unless it is necessary.

Enable TLS when possible (especially when exposing FTP to a WAN). TLS creates FTPS for better security.

Click Save, then start the FTP service.

Connecting with FTP

Use a browser or FTP client to connect to the TrueNAS FTP share. The images below show FileZilla, a free option.

The user name and password are those of the local user account on the TrueNAS system. The default directory is the same as the user home directory. After connecting, you can create directories and upload or download files.

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 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.

Configuring NFS Service

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 more_vert + Config Service. Alternatively, you can go to System > Services and click the edit edit icon for the SMB service.

Configuring SMB Service

The SMB Services screen displays setting options to configure TrueNAS SMB settings to fit your use case. In most cases, you can set the required fields and accept the rest of the setting defaults. If you have specific needs for your use case, click Advanced Options to display more settings.

SMBServiceOptionsSCALE

Enter the name of the TrueNAS host system if not the default displayed in NetBIOS Name. This name is limited to 15 characters and cannot be the Workgroup name.

Enter any alias name or names that do not exceed 15 characters in the NetBIOS Alias field. Separate each alias name with a space between them.

Enter a name that matches the Windows workgroup name in Workgroup. TrueNAS detects and sets the correct workgroup when Active Directory is configured and the field is left unset.

NetBIOS names (workgroup, domain, and computer names) are limited to 15 characters and cannot contain the following characters: \ / : * ? " < > |
Microsoft and RFC 852 define reserved words that should not be used as NetBIOS names. TrueNAS 25.04 and later enforce these restrictions through validation.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
Microsoft Reserved Words: ANONYMOUS, AUTHENTICATED USER, BATCH, BUILTIN, DIALUP, DOMAIN, ENTERPRISE, INTERACTIVE, INTERNET, LOCAL, NETWORK, NULL, PROXY, RESTRICTED, SELF, SERVER, USERS, WORLD
RFC 852 Reserved Words: GATEWAY, GW, TAC
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.

Use Minimum Protocol to set the minimum SMB version the server accepts from clients. The default SMB2 is appropriate for most environments. Select SMB1 – legacy clients (not recommended) only when an older client requires SMB1 connections. SMB1 is deprecated, and selecting it disables audit logging and prevents setting transport encryption to Required. We advise upgrading legacy clients to operating system versions that support modern SMB protocols. Select SMB3 – modern clients only to restrict access to clients that support the SMB3 dialect family, but note this could break access for embedded devices that only support SMB2.

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.

Configuring Transport Encryption

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 Minimum Protocol set to 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.

Auditing SMB Events

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.

Configuring Watch List

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.

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 .

ServicesSNMPSCALE

See SNMP Service Screen for setting information.

Port UDP 161 listens for SNMP requests when starting the SNMP service.

Management Information Bases (MIBs)

Click to view or download a static copy of the TrueNAS 26 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 /usr/local/share/snmp/mibs/.

Example (replace mytruenas.example.com with your system IP address or hostname):

PS C:\Users\ixuser> scp admin@mytruenas.example.com:/usr/local/share/snmp/mibs/* .\Downloads\
admin@mytruenas.example.com's password:
TRUENAS-MIB.txt                                                 100%   11KB 112.0KB/s   00:00
PS C:\Users\ixuser>

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.

Configuring SSH Service

To configure SSH go to System > Services, find SSH, and click to open the basic settings General Options configuration screen.

Use the Password Login Groups and Allow Password Authentication settings to allow specific TrueNAS account groups the ability to use password authentication for SSH logins.

Click Save. Select Start Automatically and enable the SSH service.

Configuring Advanced SSH Settings

If your configuration requires more advanced settings, click Advanced Settings. The basic options continue to display above the Advanced Settings screen. Configure the options as needed to match your network environment.

Select specific network interfaces from Bind Interfaces for SSH to listen on, or deselect all options to have SSH listen on all interfaces (default). Select Compress Connections to reduce latency over slow networks.

Configure SFTP logging by selecting the appropriate SFTP Log Level and SFTP Log Facility.

Select additional cipher options in Weak Ciphers if needed. None allows unencrypted SSH connections while AES128-CBC allows the 128-bit Advanced Encryption Standard cipher. These ciphers are security vulnerabilities and should only be used in secure network environments.

Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.

Add sshd_config options not covered by other settings in Auxiliary Parameters. Enter one option per line. Parameters are case-sensitive.

SSH auxiliary parameters are unsupported. Certain configurations can prevent the SSH service from starting.

Remember to enable the SSH service in System > Services after making changes.

Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.

Using SSH File Transfer Protocol (SFTP)

SFTP (SSH File Transfer Protocol) is available by enabling SSH remote access to the TrueNAS system. SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.

Go to System > Services, find the SSH entry, and click the 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 Validation
Users must have a home directory and shell access to log in with SSH.

SSH with root is a security vulnerability. It allows users to fully control the NAS remotely with a terminal instead of providing SFTP transfer access.
Choose a non-root administrative user to allow SSH access.

Review the remaining options and configure them according to your environment or security needs.

Remember to enable the SSH service in System > Services after making changes.

SSH and Two-Factor Authentication

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.

Using SFTP Connections

Open an FTP client (like FileZilla) or command line. This article shows using FileZilla as an example.

Using FileZilla, enter SFTP://{TrueNAS IP} {username} {password} {port 22}. Where {TrueNAS IP} is the IP address for your TrueNAS system, {username} is the administrator login user name, and {password} is the administrator password, and {port 22} to connect.

SFTP does not offer chroot locking. While chroot is not 100% secure, lacking chroot lets users move up to the root directory and view internal system information. If this level of access is a concern, FTP with TLS might be the more secure choice.

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.

Setting Up UPS Service

Connect the TrueNAS system to the UPS device. To configure the UPS service, go to System > Services, finding UPS, and click .

See UPS Service Screen for details on the UPS service settings.

TrueNAS Enterprise
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).

Some UPS models are unresponsive with the default polling frequency (default is two seconds). TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.

Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.

If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10.

How do I find a device name?

For USB devices, the easiest way to determine the correct device name is to enable and view console messages in the TrueNAS UI. Go to System > General Settings, find the GUI widget, and click Settings. Select Show Console Messages under Other Options. Click Save.

Plug in the USB device and look for a /dev/ugen or /dev/uhid device name in the console messages.

Can I attach Multiple Computers to One UPS?

A UPS with adequate capacity can power multiple computers. One computer connects to the UPS data port with a serial or USB cable. This primary system makes UPS status available on the network for other computers. The UPS powers the secondary computers, and they receive UPS status data from the primary system. See the NUT User Manual and NUT User Manual Pages.

Services Screens

The edit 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 play_circle start or stop_circle stop button. The start button starts the service and the stop button stops it if it is running. It is recommended to stop services before changing configuration settings.

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 for FTP to open the Basic Settings configuration screen.

FTP Basic Settings

To configure FTP, go to System > Services and find FTP, then click .

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.

FTP Advanced Settings

Advanced Settings include the General Options on the Basic Settings configuration screen and allow you to specify access permissions, TLS settings, bandwidth, and other settings to customize FTP access.

Access and TLS Setting Options

Access Settings

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

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 .tlslogin file containing one or more PEM-encoded certificates. If not found, the user must enter their password.
TLS Allow Per User	Select to allow sending a user password unencrypted.
TLS Common Name Required	Select to require the common name in the certificate to match the FQDN of the host.
TLS Enable Diagnostics	Select for more verbose logging, which is helpful when troubleshooting a connection.
TLS Export Certificate Data	Select to export the certificate environment variables.
TLS No Certificate Request	Select if the client cannot connect, likely because the client server is not correctly handling the server certificate request.
TLS No Empty Fragments	Not recommended. This option bypasses a security mechanism.
TLS No Session Reuse Required	This option reduces connection security. Only use it if the client does not understand reused SSL sessions.
TLS Export Standard Vars	Select to set several environment variables.
TLS DNS Name Required	Select to require the client DNS name to resolve to its IP address and the cert contain the same DNS name.
TLS IP Address Required	Select to require the client certificate IP address to match the client IP address.

Other Options

Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.

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

Bandwidth settings specify the space you want to allocate for local and anonymous user uploads and downloads.

Figure 5: FTP Advanced Settings Bandwidth

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

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).

iSCSI Terminology

Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively. iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network. The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes. It also requires that each node is given a unique iSCSI name. To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
- dash (-)
- dot (.)
- colon (:)
- lower case characters (a…z). Upper-case characters must be mapped to their related lower-case counterparts.
- digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN. The result is an iSCSI connection that emulates a connection to a SCSI hard disk. Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs. When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size. This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU). A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways. Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames. Systems administrators should also account for the impact on host CPU utilization. Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment. Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.

TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system. HA storage clusters can provide multiple paths to the same storage. For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer. The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage. If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage. When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.

iSCSI Configuration Methods

There are a few different approaches for configuring and managing iSCSI-shared data:

TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores. This is all managed through the vCenter web interface.

TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.

iSCSI Configuration Screens

Target Global Configuration Screen

The Target Global Configuration displays configuration settings that apply to all iSCSI shares. There are no add, edit, or delete options for this screen. It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.

The System > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.

iSCSIManualTargetGlobalConfig

Setting	Description
Base Name	Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
ISNS Servers	Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing `Enter`.
Pool Available Space Threshold (%)	Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port	The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators.
Asymmetric Logical Unit Access (ALUA)	Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server.

Portals Screens

Initiators Groups Screen

Authorized Access Screen

Targets Screen

Extents Screen

Associated Targets Screen

The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.

SharingiSCSIAssociatedTargetsScreen

Add opens the Add Associated Target screen.

The 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.

iSCSIManualAddAssocAuthTargets

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.
edit 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.

NFS Service Screen

The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.

You can access it from System > Services screen. Locate NFS and click 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.

General Options Settings

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.

NFSv4 Settings

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.

Ports Settings

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).

Other Options Settings

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.
edit Configure icon opens the SMB Service screen showing the Basic Settings by default.

SMB Service Screen

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.

Basic Settings

Setting	Description
NetBIOS Name	Enter the NetBIOS name for the TrueNAS system (maximum 15 characters). Cannot contain: `\ / : * ? " < >
NetBIOS Alias	Enter alias names (maximum 15 characters each). Cannot contain: `\ / : * ? " < >
Workgroup	Enter a name that matches the Windows workgroup name (maximum 15 characters). Cannot contain: `\ / : * ? " < >
Description	(Optional) Enter any notes or descriptive details about the service configuration.
Minimum Protocol	Select the minimum SMB protocol version the server accepts from clients. Default is SMB2. SMB1 – legacy clients (not recommended) allows SMB1 connections in addition to SMB2/3. Use only when an older client requires SMB1. SMB audit logging is not available and transport encryption cannot be set to Required. SMB2 – default accepts SMB2 dialect 2.04 and later, including SMB3. Disables SMB1. SMB3 – modern clients only restricts access to clients that support the SMB3 (3.0+) dialect family. Could break access for embedded devices that only support SMB2.
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.

Advanced Settings

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: 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 Minimum Protocol set to SMB1) the TrueNAS and Samba default behavior allows SMB clients to negotiate different encryption levels for SMB shares. When set to Default, there is no technical limitation preventing an SMB client from negotiating an encrypted session if it is required. Default enables negotiating encryption but does not turn on data encryption globally per share. For more information on SMB1 and SMB2 session or per-share encryption, see Samba Server SMB Encrypt(s). For more information on using Windows client-side SMB signing, see Windows SMB Signing Policies.
Use Debug	Select to log more detailed information about SMB. By default, TrueNAS logs error and warning-level messages. We do not recommend enabling debug logging for production servers as it can generate large log files and impact performance.
Use Syslog Only	Select to log authentication failures in /var/log/messages instead of the default /var/log/samba4/log.smbd.
Local Master	Selected by default and determines if the system participates in a browser election. Leave cleared when the network contains an Active Directory server or when Vista or Windows 7 machines are present.
Enable Apple SMB2/3 Protocol Extensions	Select to allow MacOS to use these protocol extensions to improve the performance and behavioral characteristics of SMB shares. TrueNAS requires Apple SMB2/3 protocol extensions for Time Machine support and Final Cut Pro Storage Share workflows. You must enable this setting before creating shares with the Time Machine Share or Final Cut Pro Storage Share purpose options.
Multichannel	SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance. SMB multichannel does not function if you combine NICs into a 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 Minimum Protocol set to SMB1 and with shares using the Multi-Protocol Share or Legacy Share purpose.

Figure 3: SMB Service Advanced Settings (continued)

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 to open the Services > SNMP configuration screen.

General Options

SCALESNMPOptions

SNMP v3 Options

Setting	Description
Location	Enter the location of the system.
Contact	Enter the email address to receive SNMP service messages.
Community	Enter a community other than the default public to increase system security. Value can only contain alphanumeric characters, underscores (_), dashes (-), periods (.), and spaces. Not required and can leave this empty for SNMPv3 networks.

SNMP v3 Support Options

SNMPServiceSettingsV3Options

Setting	Description
SNMP v3 Support	Select to to enable support for SNMP version 3 and display the SNMP v3 setting fields. See snmpd.conf(5) for configuration details.
Username	Enter a user name to register with this service.
Authentication Type	Select an authentication method: — for none, SHA, or MD5 from the dropdown list.
Password	Enter a password of at least eight characters.
Privacy Protocol	Select a privacy protocol: — for none, AES, or DES from the dropdown list.
Privacy Passphrase	Enter a separate privacy passphrase. Password is used when this is left empty.

Other Options

Auxiliary parameters are an unsupported configuration. Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.

Setting	Description
Auxiliary Parameters	Enter any additional snmpd.conf options. Add one option for each line.
Expose zilstat via SNMP	Select to enable. If enabled this option might have performance implications on your pools.
Log Level	Select how many log entries to create. Dropdown list options are Emergency, Alert, Critical, Error, Warning, Notice, Info and Debug.

SSH Service Screen

The System > Services > SSH screen allows you to set up SSH service on TrueNAS.

Click to open the Services > SSH configuration screen.

Allowing external connections to TrueNAS is a security vulnerability! Do not enable SSH unless you require external connections. See Security Recommendations for more security considerations when using SSH.

You must also configure SSH backup credentials to allow SSH access. See SSH Screens for more information.

SSH Basic Settings Options

The Basic Settings options display by default when you edit the SSH service.

Figure 1: SSH Basic Settings General Options

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.

SSH Advanced Settings Options

Advanced Settings include the General Options settings. Advanced settings specify bind interfaces, SFTP settings, ciphers and any additional parameters you want to use.

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 to open the Services > UPS configuration screen.

TrueNAS Enterprise
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).

General Options and Monitor Settings

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

Monitor settings specify the primary username and password, other users that have administrative access to the UPS service, and whether the default configuration listens on all interfaces.

Setting	Description
Monitor User	Enter a user to associate with this service. Keeping the default is recommended.
Monitor Password	Change the default password to improve system security. The new password cannot include a space or #.
Extra Users	Enter accounts that have administrative access. See upsd.users(5) for examples.
Remote Monitor	Select to have the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.

Shutdown Settings

Shutdown settings specify the UPS shutdown mode, command, and timer for the UPS service.

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

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: Provides information on using the TrueNAS shell.

Shell Screen: Provides information on the TrueNAS Shell screen, buttons, and slider.

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 and buttons adjust the displayed text size in the Shell.

The shell window stores the command history for the current session.

Leaving the Shell screen clears the command history.

Navigating In Shell

This section provides keyboard navigation shortcuts you can use in Shell.

Action	Keyboard/Command	Description
Scroll up	Up arrow expand_less	Scroll up through previous commands.
Scroll down	Down arrow expand_more	Scroll down through following commands.
Top of screen	`Home`	Moves the cursor to the top of the screen when viewing entries and results.
Bottom of screen	`End`	Moves the cursor to the bottom of the screen command when viewing entries and results.
Delete	`Delete`	Deletes highlighted text.
Auto-fill text	`Tab`	Type a few letters and press `Tab` to complete a command name or filename in the current directory.
right-click		Right-clicking in the terminal window opens the browser default right click menu, which allows you to use native copy and paste functions.
Exit to root prompt	`exit`	Entering `exit` leaves the session.
Copy text	`Ctrl+Insert`	Enter `Ctrl+Insert` to copy highlighted text in Shell.
Paste text	`Shift+Insert`	Enter `Shift+Insert` to paste copied text in Shell.
Kill running process	`Ctrl+c`	Enter `Ctrl+c` to kill a process running in Shell. For example, the `ping` command.

Changing the Default Shell

zsh is the default shell, but you can change this by going to Credentials > Users. Select the admin or other user to expand it. Click Edit to open the Edit User screen. Scroll down to Shell and select a different option from the dropdown list. Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh. Click Save.

Admin users can set the Shell to default to the TrueNAS Console by selecting TrueNAS Console in Shell on the Edit User screen.

Clicking other TrueNAS UI menu options closes the shell session and stops commands running in the Shell screen.

Tmux allows you to detach sessions in Shell and then reattach them later. Commands continue to run in a detached session.

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.

Shell	Required Privilege and Role
System > Shell (host system)	Web Shell Access privilege only
VM Serial Shell	Web Shell Access privilege plus the VM write role (`VM_WRITE`)
Container Shell	Web Shell Access privilege plus the container write role (`CONTAINER_WRITE`)
Container Shell (Apps)	Web Shell Access privilege plus the apps write role (`APPS_WRITE`)

When authorized, shell commands run as the root user.

The Font Size and 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

AlertServicesScreen

Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.

Add/Edit Alert Service Screen

The Add Alert Service and Edit Alert Service screens show the same settings.

AddAlertServiceScreen

Name and Type Settings

Setting	Description
Name	Enter a name for the new alert service.
Enabled	Clear the checkmark to disable this service without deleting it.
Type	Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or 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 edit icon for the service to display the Edit Alert Service screen.

Alert Service Types

AWS SNS

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.

Email

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.

InfluxDB

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.

MatterMost

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.

OpsGenie

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).

PagerDuty

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.

Slack

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.

SNMP Trap

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.

Splunk On-Call

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.

Alert Categories

Use the Category dropdown list to display alert settings for each category.

Applications

Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.

Click here for more information

You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.

Audit

Audit alert settings apply to the audit and verification services on your TrueNAS system.

Click here for more information

You can customize alert settings for when the audit service backend fails, the audit service has a health failure, and when the TrueNAS verify service detects changes in the root file system.

Certificates

Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.

Click here for more information

You can customize alert settings for when a certificate has expired, is expiring, or is expiring soon, when a certificate parsing fails, and when the web UI HTTPS certificate setup fails.

Directory Service

Directory Service alert settings apply to the directory services configured on your TrueNAS.

Click here for more information

You can customize alert settings for when the directory service bind is not healthy and when a directory service DNS update fails.

High Availability Settings

TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only 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

Hardware alert settings apply to the IPMI network connections and disk health monitoring on your TrueNAS system.

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)

Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.

Click here for more information

You can customize alert settings for when the system fails to communicate with the KMIP server, sync the SED global password, sync SED keys, or sync ZFS keys with the KMIP server.

Network

Network alert settings apply to network interfaces configured on your TrueNAS.

Click here for more information

You can customize alert settings for when a BOND interface references missing ports, when ports are not active on a BOND interface, and when there are no active ports on a BOND interface.

Reporting

Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.

Click here for more information

You can customize alert settings for when Netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.

Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.

Click here for more information

You can customize alert settings for when a deprecated service configuration is detected or a deprecated service is running, and when Fibre Channel HBAs are added or replaced.

You can also set alerts for when a share is unavailable because it uses a locked dataset.

Storage

Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.

Click here for more information

You can also change alert settings for when a scrub pauses, too many snapshots exist on the system or on a specific dataset.

System

System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system restarts, updates, and the web interface.

Click here for more information

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.

Tasks

Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub, and snapshot tasks scheduled on your TrueNAS.

Click here for more information

TrueNAS Connect Service

TrueNAS Connect Service alert settings apply to the TrueNAS Connect service on your TrueNAS system.

Click here for more information

You can customize alert settings for when TrueNAS Connect is disabled or unconfigured and when the system is unable to connect to the TrueNAS Connect heartbeat service.

UPS

UPS alert settings apply to a UPS connected to your TrueNAS.

Click here for more information

You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.

Alert Warning Levels

Use the Set Warning Level dropdown list to customize alert importance. Each warning level has an icon and color to express the level of urgency.

Level	Icon	Alert Notification?
INFO		No
NOTICE		Yes
WARNING		Yes
ERROR		Yes
CRITICAL		Yes
ALERT		Yes
EMERGENCY		Yes

Alert Frequency

Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.

Audit

Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.

Audit Screen: Provides information on the TrueNAS Audit screens and settings.

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.

Auditing Event Types

Audit logs retain at least one week of data. Logs are downloadable.

Auditing event types are:

Session and user
Sudo and root user commands (includes STIG-compliant shell commands)
SMB protocol and share
iSCSI protocol and share
FTP service
STIG-compliant security objects
HA shutdown and restart reason

Enterprise and Enterprise HA systems have security object (FIPS and STIG) event logging. HA primary and standby controller event logs are downloadable from either the primary or the standby controller.

Session and User Auditing Events

Session and user auditing events include authentication, method call, sudo accept/reject, and web shell events.

Authentication Events

Audit messages are generated every time a client logs into the TrueNAS UI or an SSH session or makes changes to user credentials.

TrueNAS terminates inactive sessions when it reaches the specified timeout limit. If a user initiates a new session within five minutes of the last session, TrueNAS logs the user as associated with the previous session. If the log-in occurs outside the five minutes, TrueNAS initiates a new websocket session.

Method Call Events

Audit messages are generated every time a currently logged-in user creates a new user account or changes user credentials.

Sudo Accept or Reject Events

Sudo accept or reject events are generated every time a user logs into a shell session and uses sudo to perform a command as root, or is denied sudo permission. The event data for a sudo event includes the command.

Web Shell Authentication Events

Web shell authentication events are generated every time a user attempts to open a web shell, for both successful and denied attempts. The event data includes the shell type (host, app, container, or VM), the target resource, the user name, and, for a denied attempt, the reason for the denial.

Web Shell Logout Events

Web shell logout events are generated when an authenticated web shell session disconnects. The event data includes the shell type (host, app, container, or VM), the target resource, and the user name.

SMB Auditing Events

SMB events are omitted by default from the System > Audit screen. To view these audit results, go to System > Services and click 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.

Connect Events

Generated every time an SMB client performs an SMB tree connection (TCON) to a given share. Each session can have zero or more TCONs.

Disconnect Events

Generated every time an SMB client performs an SMB tree disconnect to a given share.

Create Events

Generated every time an SMB client performs an SMB create operation on a given tree connection (TCON). Does not log internally-initiated create operations. Each SMB tree connection can have multiple open files.

Read or Write Events

Generated at configurable intervals as an SMB client reads from or writes to a file. Specifies the minimum time to wait before generating another read or write event for a given file type.

For example, when set to 5 and an SMB client does constant writes to a file, only 12 events are generated per minute. The default value is 60, or one event per type per minute. File-based counters are printed within close messages, and connection-based counters are included in disconnect messages.

Read or Write Offload Events

Generated at configurable intervals as an SMB client performs offloads of reads from or writes to a file. Specifies the minimum time to wait before generating another offload read or write event for a given file type.

Open or Close Events

Generated every time an SMB client opens or closes a file. When a file is opened or closed, a summary of file system operations performed on the type is included in the audit message.

Rename Events

Generated when a client attempts to rename a file.

Set_Attr Events

Generated when a client attempts to set basic file attributes (for example, DOS mode or file timestamps). The key attr_type indicates the precise type of attributes changed in the event this message records.

Set_Quota Events

Unlink Events

Generated when a client attempts to delete a file or directory from a share.

Set_ACL Events

Generated when a client attempts to set an NFSv4 ACL on a file system or to grant a user (OWNER) read and write permissions to the file system.

Audit Message Records

Audit records contain information that establishes:

Type of event
When the event occurred (timestamp)
Where the event occurred (source and destination addresses)
Source of the event (user or process)
Outcome of the event (success or failure)
Identity of any individual or file names associated with the event

Each audit message is a single JSON file containing mandatory fields. It can also include additional optional records. Message size is limited to not exceeding 1024 bytes for maximum portability with different syslog implementations.

Use the Export button on an audit screen to download audit logs in CSV, JSON, or YAML format. CSV format is readable in spreadsheet programs. Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file. The JSON object for an audit message contains the version information, the service that might be the name of the SMB share, a session ID, and the tree connection (tcon_id).

Message Fields

Each audit message JSON object includes:

Field	Description
aid	GUID uniquely identifying the audit event.
vers	JSON object containing version information of the audit event. Audit version identifiers represent the major and minor versions of the internal TrueNAS audit message. Major versions are not made outside a major TrueNAS release. Minor version changes indicate non-breaking changes to the format, such as adding a new optional field. Major version changes that can be renaming or removing an existing mandatory field.
time	UTC timestamp indicating when the event occurs.
addr	IPv4 or IPv6 address for the client generating the audit message.
user	Username of the user or client generating the audit message. If no username, it can be the user ID prefixed with UID.
svc	Unique human-readable service identifier (all uppercase alpha characters) for the TrueNAS service generating the audit message (always SMB).
event	Human-readable name for the event type for the audit message. Name is in all uppercase alpha characters that can include the underscore (_) or dot (.) special characters. See Audit Event Types above for more information.
svc_data	A JSON object containing tree connection (TCON) specific data. This is standardized for all events.
event_data	A JSON object containing event-specific data. This varies based on the event type.
sess	GUID unique identifier for the session.
success	Shows true if the operation succeeds or false if it fails.

Accessing Auditing Screens

Users have access to audit information from three locations in the TrueNAS UI:

Credentials > Users details screen through the Audit Logs option * On the Users screen, click Audit Logs on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user. For more details, see Audit Screen.
Shares > Window (SMB) Shares details screen through the share edit Audit Logging option * On the Sharing screen, click the edit 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 receipt_long 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.

Searching Audit Logs

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 when the syntax is valid and 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 (Copy to Clipboard) icon shows two options, Copy Text and Copy Json. Copy Text copies the event to a text file. Copy Json copies the event to a JSON object.

Configuring SMB Auditing

Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.

SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.

From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.

Selecting Enable turns auditing on for the share you are creating or editing.

At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.

Configuring Watch List

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.

Configuring Audit Storage and Retention Policies

To configure Audit storage and retention settings, click Audit Settings on the Audit screen or go to System > Advanced Settings, then click Configure on the Audit widget.

The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.

Audit Settings

Settings	Description
Retention (in days)	Enter the number of days to retain local audit messages.
Reservation (in GiB)	Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)	Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)	Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range: 5 - 80.
Quota Fill Critical (in %)	Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range: 50 - 95.

For example, to change the percent usage warning threshold for the storage allocated to the Audit database:

Navigate to System > Advanced screen.
Select the Configure button on the Audit widget.
In the Audit configuration popup, change the value in the Quota Fill Warning field to the desired percentage.
Select the Save button to effect the change.

Audit Screen

TrueNAS auditing logs record all operations performed by a session, user, or service (SMB, middleware).

Audit Screen

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.

Audit Screen Search

The Search field shows the Switch to Advanced option that replaces the default basic search with the advanced search option. The advanced search option allows entering filter parameters to narrow results to a specific type of record. Click in the Search field to see the advanced filter options in advanced search mode.

Switch to Advanced toggles to Switch to Basic that reverts the search operation to the default simple word search method. Clicking in the Search field does not show search filter options in basic search mode.

Search starts the search operation based on the search parameters entered.

Export dropdown exports audit log records in multiple formats. Select CSV, JSON, or YAML to generate a compressed file (tar.gz format) that downloads to your browser’s default download location. The export includes all audit entries that match the current filter settings.

Audit Screen Log Details Widgets

The Audit screen shows two widgets for a selected record in the audit table:

Metadata - Shows the selected audit record properties Audit ID, Version, and Session ID.
Event Data - Shows the selected audit record method, a description of the recorded event, authentication status, and authorization information. The data varies based on the type of event.

The Copy to Clipboard icon on the Event Data widget copies the fields listed on the Event Data widget formatted as straight text or a JSON file record that you can paste into any text editor.

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.

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.

Elements Options

The Elements button at the top right of the View Enclosure screen displays a dropdown list of options to view information about the system or expansion shelf. The options vary by TrueNAS platform, if the system is connected to expansion shelves, and if you have an expansion shelf image selected instead of the main system. All TrueNAS systems include the Disks option. TrueNAS systems with expansion shelves include the Temperature, Power Supply, and Voltage options. The expansion shelf includes the Disks, Cooling, Services, Power Supply, SAS, Temperature, and Voltage options. Each option displays a table with readings from the system’s internal components taken over a period of time.

Change Enclosure Label

Edit Label displays for the main system (except TrueNAS Minis) and expansion shelves. Edit Label opens the Change Enclosure Label window.

Type a name or description for the system and click Save to apply the label. To simplify system maintenance, use labels that help identify the physical location of the system, such as ES102 Rack D5 U20. Reset to Default restores the default name for the system.

System Image Screens

System images display the front view of the system by default.

System image screens include options to change the information on the screen:

Show Pools shows disks highlighted in pools on the system image.
Show Status shows healthy or failed disks in the system and a status indicator color legend.
Show Expander Status shows a SAS expander status indicator for systems with one or more expander.

TrueNAS Mini Enclosure Screens

TrueNAS Mini systems display the front view of the system chassis.

Pool information displays at the top of the screen. The drive bay number and disk label displays to the left of the image and the status to the right of the image. The Disk Overview section provides general details about the system drive hardware and capacity. Drive Temperatures displays current readings for each drive in the system.

Click on a disk to show drive details and stats.

TrueNAS Enterprise Enclosure Screens

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.

Figure 7: View Enclosure Expansion Shelf

Disk Image Screens

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.

Figure 8: View Enclosure Disk Information

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.

Figure 9: View Enclosure Expansion Shelf Disk Information

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.

API Documentation

TrueNAS (25.04 and later) uses a versioned JSON-RPC 2.0 over WebSocket API. API versions are numbered in conjunction with TrueNAS version releases.

Viewing API Documentation

TrueNAS API documentation is available in several ways:

In the web interface, click My API Keys on the top right toolbar user settings dropdown menu to open the User API Keys screen. Click API Docs on the User API Keys or User screen to access the TrueNAS API documentation built into the system. A new browser window opens, showing the API documentation Table of Contents.
Append /api/docs/ to your TrueNAS host name or IP address in a browser to access the API documentation.
Go to the API Docs website and use the dropdown to view documentation for a specific TrueNAS (and API) version.

API Access

User-linked API access keys allow administrators to configure per-user access to the TrueNAS API. Keys are revocable and 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.

TrueNAS 26 (Early)

Annual Release Cadence and Simplified Versioning

WebShare with TrueSearch

Containers

SMB Stateful Failover

SMB Spotlight Search

OpenZFS 2.4

Linux Kernel 6.18

API Changes

26 Featured Content

Getting Started

Contents

Enterprise Deployment Guide

TrueNAS 26 Version Notes

Notable Changes and Known Issues

26-BETA.2 Notable Changes

26-BETA.1 Notable Changes

Current Known Issues

Annual Release Cadence and Simplified Versioning

WebShare with TrueSearch

Containers

SMB Stateful Failover

SMB Spotlight Search

OpenZFS 2.4

Linux Kernel 6.18

API Changes

Features Removed in 26

REST API

JSON-RPC API Methods

pool.is_upgraded

pool.ddt_prefetch

Deprecated Features (Removal in Future Versions)

JSON-RPC API Methods

Legacy Authentication Methods

Pool Scrub Methods

system.advanced consolemsg Attribute

config.save pool_keys Parameter

Upgrading TrueNAS

API Improvements in TrueNAS 26

REST API Removal

Improved API Authentication

Containers and Virtual Machines

Containers

Drive Health Management

TrueNAS Apps

Upgrade Paths

Migrating from TrueNAS 13.0 or 13.3

Component Versions and ZFS Feature Flags

Software Component Versions

OpenZFS Feature Flags

Feature Deprecations

Features Removed in 26

REST API

JSON-RPC API Methods

pool.is_upgraded

pool.ddt_prefetch

Deprecated Features (Removal in Future Versions)

JSON-RPC API Methods

Legacy Authentication Methods

Pool Scrub Methods

system.advanced consolemsg Attribute

config.save pool_keys Parameter

Additional Resources

TrueNAS Hardware Guide

Minimum Hardware Requirements

Storage Considerations

Storage Device Quantities

Storage Media

Storage Solutions

Storage Device Sizing

Storage Device Burn-In

Storage Controllers

SAS Expanders

Storage Device Cooling

Memory, CPU, and Network Considerations

Memory Sizing

Error Correcting Code Memory

Central Processing Unit (CPU) Selection

Remote Management: IPMI

Power Supply Units

system.advanced `consolemsg` Attribute

config.save `pool_keys` Parameter

system.advanced `consolemsg` Attribute

config.save `pool_keys` Parameter