Instructions for configuring the various TrueNAS features. Articles are organized parallel to the TrueNAS interface layout.
This guide collects various how-tos for both simple and complex tasks using primarily the TrueNAS web interface.
Tutorials are organized parallel to the TrueNAS web interface structure and grouped by topic.
Tutorials are living articles and continually updated with new content or additional in-depth tutorials that guide in unlocking the full potential of TrueNAS.
To display all tutorials in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
TrueNAS Tutorials
⎙ Download or Print: View all TrueNAS Tutorials as a single page for download or print.
Top Toolbar: Tutorials about options available from the TrueNAS top toolbar.
Using UI Global Search: This tutorial shows how to use the Global Search feature to explore the TrueNAS UI and documentation.
Managing API Keys: This tutorial shows how to add, create, or edit an API key in TrueNAS and access API Documentation.
Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.
Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.
Storage Encryption: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.
Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.
Shares: Tutorials for configuring the various data sharing features in TrueNAS.
AFP Migration: Provides information on migrating AFP shares from FreeBSD- to Linux-based TrueNAS versions.
Block Shares (iSCSI): Describes the iSCSI protocol and has tutorials for various configuration scenarios.
Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.
Multiprotocol Shares: Provides instructions on setting up SMB and NFSv4 mixed-mode shares.
Windows Shares (SMB): Provides information on SMB shares and instructions on creating a basic share and setting up various specific configurations of SMB shares.
NVMe-oF Subsystems: Provides information on NVMe-oF subsystems and instruction on creating a subsystem and setting up enterprise configurations of subsystems.
Data Protection: Tutorials related to configuring data backup features in TrueNAS.
Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.
Cloud Sync Tasks: Tutorials for configuring and managing data backups to from TrueNAS to various 3rd party Cloud Service Providers.
Configuring Rsync Tasks: Provides instructions on adding rsync tasks with two methods, SSH connection and module.
Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.
Configuring Static Routes: Provides instructions on configuring a static route using the TrueNAS web UI.
Setting Up IPMI: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.
Accessing NAS from VMs and Containers: Provides instructions on how to create a bridge interface for virtual machines or applications and provides Linux and Windows examples.
Credentials: Tutorials for configuring the different credentials needed for TrueNAS features.
Using Administrator Logins: Explains role-based administrator logins and functions. Provides instructions on configuring SSH and working with the admin and root user passwords.
Managing Users: Provides instructions on adding and managing administrator and user accounts.
Managing Groups: Provides instructions on adding and managing groups.
Backup Credentials: Backup credential tutorials for integrating TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about adding and managing certificates, CSRs, CAs, and ACME DNS-Authenticators in TrueNAS.
Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.
Containers: Tutorials for configuring the TrueNAS Containers feature, creating, and managing containers.
Virtual Machines: Tutorials for configuring TrueNAS SCALE virtualization features and creating virtual machines.
Reporting: Provides information on changing settings that control how TrueNAS displays report graphs, how to interact with graphs, and configuring reporting exporters.
System Settings: Tutorials for configuring the system management options in the System Settings area of the TrueNAS web interface.
Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.
Using Shell: Provides information on using the TrueNAS shell.
Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.
Top Toolbar
The TrueNAS top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI.
Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens.
It also shows the name of the user currently logged into the system to the left of the Settings icon.
You can also collapse or expand the main function menu on the left side of the screen.
The Search UI global search bar allows users to search for screens and elements within the TrueNAS UI or to redirect search terms to the TrueNAS Documentation Hub.
Searching UI Fields
Click the Search UI bar or type Ctrl + / to select the UI global search.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
TrueNAS
The TrueNAS logo returns to the Dashboard from any other screen.Send Feedback
TrueNAS provides two feedback options, one to rate a UI screen and the other to report a problem encountered with the system.
To send feedback, click the Send Feedback icon on the top toolbar to open the Send Feedback window.
Alternatively, go to System > General Settings and click File Ticket on the Support widget.
Rating a UI Screen
Click Rate this page to send feedback on a UI page.
You can include a screenshot of the current page and/or upload additional images with your comments.
You can also click the link to visit the TrueNAS forum, where you can vote for new features, report problems, or suggest improvements directly to the development team.
Click Report a bug to create an engineering ticket when a TrueNAS screen or feature is not working as intended.
This submits the ticket directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click Report a bug to see the fields to create an engineering ticket for system errors, bugs, or unexpected behavior.
For example, report a bug where a middleware error and traceback occurred while saving a configuration change.
Enter a descriptive summary in the Subject.
For example, if a configuration change does not update after clicking Save and you get an error message or traceback after attempting the change, enter XYZ setting fails to save with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
I clicked the edit XYZ settings option, modified the XYZ setting, and clicked Save. The operation failed and showed the following traceback message: [include the traceback text]. My system is running TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to speed up the issue resolution.
Select Attach debug.
To attach a screenshot of the current page, select Take screenshot of the current page.
Or, before using this form, take screenshots of the screen, traceback or other error message, copy a log into a text file, or create any other file to attach.
Open this form and attach those files by selecting Attach additional images and clicking Choose File to open a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
TrueNAS displays a message telling users to check their email for verification instructions.
Status of TrueNAS Connect
TrueNAS provides quick access to TrueNAS Connect from the top toolbar in your TrueNAS system.
The Status of TrueNAS Connect icon opens the TrueNAS Connect dialog.
Before you sign up for TrueNAS Connect, the dialog shows it is waiting to connect.
After connecting to TrueNAS Connect and registering the system, the Status of TrueNAS Connect icon shows an active status indicator.
The TrueNAS Connect dialog shows the status of the active connection.
Click Open TrueNAS Connect to open the TrueNAS Connect management interface.
Click cloud_offDisable Service to disconnect the system from TrueNAS Connect.
Click on either service to go to its configuration screen.
Jobs
The Running Jobsassignment icon button opens the Running Jobs window showing a minimized view of all running, waiting, and failed jobs/processes.
Hover the mouse over an error job to view a pop-up window with the error message for that failed job.
Click the minus (-) at the top right corner of any dialog or pop-up window to minimize a job/process.
Click on a running job to open a dialog for that job.
A running job shows a progress bar and a stop_circle button to the right of the job. Click on this to show the Abort dialog.
Click Abort to stop the job and abort the process.
Beginning in 25.04, the Abort option is only available for select jobs. Jobs that are unable to be aborted are listed without the stop_circle button as an option.
Click on Go to Jobs to open the Jobs screen with tabs to screens listing all successful, active, or failed and aborted jobs.
Click on the All, Active, or Failed button at the top of the screen to show the log of jobs that fit that classification.
Click View next to a task to see the log information and error message for that task.
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the TrueNAS Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Settings
The Settingsaccount_circle icon opens a dropdown list of options to change passwords, modify two-factor authentication settings (when configured), create and manage API keys, access the TrueNAS documentation, and to log out of the TrueNAS UI.
Change Password
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
My API Keys
Click on My API Keyslaptop to go to the User API Keys screen.
API keys identify an outside resource or application without a principal.
For example, when adding a new system to TrueCommand if you are required to add an API key to authenticate the system.
Use this function to create an API key for this purpose.
Click API Docs to access the API documentation portal with information on TrueNAS API commands.
See API Keys for more information on adding or managing API keys.
See API Keys for more information on adding or managing API keys.
Guide
Click on Guidelibrary_books to open the TrueNAS Documentation Hub in a new tab.
Log Out
Log Out logs the current user out of the TrueNAS UI, but does not power off the system.
The Read-Only Admin and Sharing Admin roles only have access to the Log Out option.Power Options
Click the Powerpower_settings_new button to open the dropdown list of power options.
Restart logs you out of the TrueNAS UI and restarts the server. Shut Down logs you out of the TrueNAS UI and powers off the system as though you pressed the power button on the physical server.
TrueNAS Enterprise
Please consult your specific hardware documentation to find notes about possible hardware-specific controls for power-on or off behaviors.
With the implementation of administrator roles, the power options are locked based on the level of privileges for the administrator role.
The full administrator has access to both power options, but read-only and sharing admin roles do not.
The power options that show a lock icon indicate the function is not permitted.
Content
Using UI Global Search: This tutorial shows how to use the Global Search feature to explore the TrueNAS UI and documentation.
Managing API Keys: This tutorial shows how to add, create, or edit an API key in TrueNAS and access API Documentation.
TrueNAS 24.10 (Electric Eel) introduces global search function that allows users to quickly access screens and management functions across the TrueNAS UI.
Global search also allows users to redirect queries to the TrueNAS Documentation Hub to retrieve relevant documentation.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS indicates the selected element with a glow effect.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
User-linked API keys allow administrators to configure per-user access to the TrueNAS API.
Keys are revocable. You can also configure them to expire on a preset date.
Click laptopMy API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen.
The User API Keys screen shows a table listing API keys added to the system, and allows adding, searching for, editing, or deleting keys.
Click API Docs to view API Documentation embedded within the system.
TrueNAS Connect API Keys
TrueNAS Connect automatically creates an API key when you register your system in the TrueNAS Connect service. TrueNAS uses this key, shown on the User API Key screen, to authenticate with the TrueNAS Connect service.
There are instances where you might see more than one tnc key listed.
If you delete a tnc API key, the TrueNAS Connect prompts you to re-authenticate the next time you connect to the service.
Adding an API Key
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
Always back up and secure keys.
TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware.
API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account.
A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys.
TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport.
A revoked API key cannot be used until it is reset.
Resetting generates a new key-string.
Remember to update clients to use the new key.
Select My API Keys from the Settings dropdown on the top toolbar.
Alternatively, you can go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.
If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.
Enter a descriptive name for the key.
Select an administrative user to associate with this key from the Username dropdown.
To add a user API key token that does not expire (no expiration date), leave Non-expiring enabled.
A non-expiring key remains active until it is manually revoked or changed to expire.
To create a key with a scheduled expiration, disable Non-expiring by clearing the checkbox.
Click on the calendar icon in the Expires On field and select the expiration date. The field does not allow typing a date.
The token only shows in the API Key dialog.
To save the key for use as an authentication token, click Copy to Clipboard, paste it into a text file, then save the fle in a secure location.
Can I view the API Key again after closing the API Key dialog?
You cannot view the API key string after closing the API Key dialog.
If you close the dialog before copying the key, select the user row and click Edit to open the Edit API Key screen.
Select Reset. TrueNAS opens the API Key dialog showing a new key string. Copy the key before closing the dialog.
Remember to update settings using the API key token.
Click Close to return to the User API Keys screen.
Migrating API Keys
Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.
Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system.
Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, generate a new user-linked API key, and distribute it to the API client.
Editing an API Key
Select the user row and then click edit edit to open the Edit API Key screen.
To remove the existing API key string and generate a new random key, select Reset.
The API Key dialog opens, showing a new key string.
Click Copy to Clipboard to copy the token, then paste it into a text file and save it in a secure location.
Update any clients using the reset API Key with the new key string.
Deleting an API Key
Click delete delete for any API key on the list to remove that key.
TrueNAS opens a Delete API Key dialog.
Click API Docs on the User or User API Keys screen to access the TrueNAS API documentation built into the system.
A new browser window opens, showing the API documentation Table of Contents.
Click the link for the content you want to access:
JSON-RPC 2.0 over WebSocketAPI shows an overview of the JSON-RPC 2.0 format with example objects.
API Methods shows a table of contents listing TrueNAS API methods
API Events shows the list of API methods with query call options
Jobs shows an overview of the job options, uploading/downloading file example scripts, and information on running a query for job status.
Query Methods shows query basic usage, supported operators, and information on query operations and syntax.
TrueNAS (25.04 and later) uses a versioned JSON-RPC 2.0 over WebSocket API.
API versions are numbered in conjunction with TrueNAS version releases.
The API documentation provides information about supported API methods and events.
Documentation is included for all API versions supported by the current TrueNAS release and defaults to the latest supported API.
Use the dropdown to view documentation for different supported API versions.
Advanced users can interact with the TrueNAS API to perform management tasks using the TrueNAS API Client as an alternative to the TrueNAS web UI.
This websocket client provides the command line tool midclt and allows users to communicate with middleware using Python by making API calls.
The client can connect to the local TrueNAS instance or to a specified remote socket.
For more information on the API documentation see API Reference.
Shutting Down TrueNAS Enterprise HA
TrueNAS Enterprise
This procedure applies to TrueNAS Enterprise High Availability (HA) systems only.
If you need to power down your TrueNAS Enterprise system with HA enabled, this is the procedure:
Shut Down From the TrueNAS Web UI
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.
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.
If changing an existing widget, locate the widget group on the screen, then click Edit at the top right of that widget group to open the Widget Editor with the layout and settings for that widget group.
Click on the layout image you want to use. The image on the screen show the new widget layout.
If adding a new widget, the default layout is full size with the category and type set to Empty.
If editing an existing widget, the current layout changes to show the existing category and type in the first widget of the new layout.
An error shows in the selected widget of the group if the widget size does not support the selected category and type.
Select the widget in the group you want to add or change.
If the layout includes half and/or quarter size widgets, the first widget in the group is selected by default.
To configure another widget in the layout, select the position in the group you want to configure.
Select the Widget Category and Widget Type to apply to the selected widget.
For example, if configuring a network widget, you can use one full size layout or select one with half and quarter size widgets.
The example below shows two layout options for configuring a network widget.
If the selected category is not supported for the selected widget, either select a new layout or change the Widget Category and/or Widget Type to one the widget supports.
(Optional) Edit the next widget in the widget group for the selected layout.
After adding or changing the widget category and type, either click on the next widget in the group to configure it.
Click Save to close the Widget Editor and return to the Dashboard.
Edit or add as many widgets as you want.
Click Save at the top right of the Dashboard screen to save all changes and exit configuration mode.
To exit configuration mode without saving changes, click Cancel.
Deleting a Widget
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.
Storage
The TrueNAS Storage section has controls for pools, snapshots, and disk management.
This section also provides access to datasets, zvols, quotas, and permissions.
Use the Import Pool button to reconnect pools exported/disconnected from the current system or created on another system.
This also reconnects pools after users reinstall or upgrade the TrueNAS system.
Use the Disks button to manage, wipe, and import storage disks that TrueNAS uses for ZFS data storage.
Use the Create Pool to create ZFS data storage “pools” from physical disks. Pools efficiently store and protect data.
The Storage screen displays all the pools added to the system.
Each pool shows statistics and status, along with buttons to manage the different elements of the pool.
The articles in this section offer specific guidance for the different storage management options.
Storage Articles
Import Pool: Provides information on ZFS importing for storage pools in TrueNAS. It also addresses GELI-encrypted pools.
Disks: Articles with instructions for managing, replacing, and wiping disks.
Replacing Disks: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.
Wiping a Disk: Provides instructions for wiping a disk.
Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.
Create Pool: Provides background considerations and a simple tutorial on creating storage pools in TrueNAS.
Fusion Pools: Provides information on setting up and using fusion pools.
Managing Pools: Provides instructions on managing storage pools, VDEVs, and disks in TrueNAS.
Import Pool
ZFS pool importing works for pools exported or disconnected from the current system, those created on another system, and for pools you reconnect after reinstalling or upgrading the TrueNAS system.
The import procedure only applies to disks with a ZFS storage pool.
TrueNAS supports pool imports using the WebUI or API only.
Manual pool import via command line can cause unexpected behavior and system issues.
Do I need to do anything different with disks installed on a different system?
When physically installing ZFS pool disks from another system, use the zpool export poolname command in the Linux command line or a web interface equivalent to export the pool on that system.
Shut down that system and move the drives to the TrueNAS system.
Shutting down the original system prevents an in use by another machine error during the TrueNAS import.
To import a pool, go to the Storage Dashboard and click Import Pool at the top of the screen.
TrueNAS detects the pools that are present but not connected and adds them to the Pools dropdown list.
Select a pool from the Pool dropdown list, then click Import.
Can I import GELI-encrypted pools?
GELI encryption is specific to FreeBSD so Linux-based TrueNAS cannot import GELI-encrypted pools.
See the GELI Pool Migrations section in the TrueNAS 13.0 Storage Encryption article.
The Preparing to Migrate article provides information on what you can and cannot migrate and a checklist of actions to take before migrating from TrueNAS 13.0 (or 13.3 for community users) with GELI-encrypted pools to 24.04.
Disks
To manage disks, go to Storage and click Disks on the top right of the screen to open the Disks screen.
To view details on a disk, click on the disk to expand it. Select Edit to open the Edit Disk screen.
The Disks screen lets users edit disks or delete obsolete data off an unused disk.
Contents
Replacing Disks: Provides disk replacement instructions that take a failed disk offline and replaces a disk in an existing VDEV. The replacement process automatically triggers a pool resilvers.
Wiping a Disk: Provides instructions for wiping a disk.
Managing Self-Encrypting Drives (SED): Covers self-encrypting drives including supported specifications, implementing and managing SEDs in TrueNAS, and managing SED passwords and data.
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:
If you configure your main TrueNAS Dashboard to include an individual Pool or the Storage widgets, they show the status of your system pools as on or offline, degraded, or in an error condition.
From the main Dashboard, you can click the on either the Pool or Storage widget or you can click Storage on the main navigation menu to open the Storage Dashboard screen and locate the pool in the degraded state.
My disk is faulted. Should I replace it?
If a disk shows a faulted state, TrueNAS has detected an issue with that disk and you should replace it.Can I use a disk that is failing but still active?
There are situations where you can leave a disk that has not completely failed online to provide additional redundancy during the replacement procedure.
We do not recommend leaving failed disks online unless you know the exact condition of the failing disk.
Attempting to replace a heavily degraded disk without offlining it significantly slows down the replacement process.
Taking a Failed Disk Offline
We recommend users off-line a disk before starting the physical disk replacement.
Offlining a disk removes the device from the pool and can prevent swap issues.
To offline a disk:
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click next expand the VDEV, then look for the disk with the REMOVED status.
Click on the failed disk, then click Offline in the ZFS Info widget to take the disk offline.
The disk status changes to OFFLINE.
The offline failed?
If the off-line operation fails with a Disk offline failed - no valid replicas message, go to Storage Dashboard and click Scrub on the ZFS Health widget for the pool with the degraded disk. The Scrub Pool confirmation dialog opens. Select Confirm and then click Start Scrub.
When the scrub operation finishes, return to the VDEVs screen, expand the VDEV, then click the disk, and try to offline it again.
After offlining the failed disk, physically remove it from the system.
Replacing a Failed Disk Without a Hot Spare
After taking the failed disk offline and physically removing it from the system, insert the replacement disk now.
The new disk must have the same or greater capacity as the failed disk.
If replacing a failed disk with an available disk in the system, proceed to the next step.
Click Replace on the Disk Info widget on the Devices screen for the disk you off-lined.
Select the new drive from the Member Disk dropdown list on the Replacing disk dialog.
Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
Preserve disk description maintains any descriptions associated with the original disk, which prevents you from needing to copy descriptors to the new disk manually. This option is enable by default. Select to clear the checkmark if you want the replacement disk to use descriptors that differ from those attached to the original disk.
Click Replace Disk to add the new disk to the VDEV and bring it online.
Disk replacement fails when the selected disk has partitions or data present.
To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.
When the disk wipe completes, TrueNAS starts replacing the failed disk.
TrueNAS resilvers the pool during the replacement process.
For pools with large amounts of data, this can take a long time.
When the resilver process completes, the pool status returns to Online on the Devices screen.
Refresh the screen to ensure the replacement disk appears in the pool as expected.
Replacing a Failed Disk With a Hot Spare
A Hot Spare vdev sets up drives as reserved to prevent larger pool and data loss scenarios.
TrueNAS automatically inserts an available hot spare into a Data vdev when an active drive fails.
TrueNAS resilvers the pool after the hot spare is activated.
Detaching a Failed Disk
After taking the failed disk offline and physically removing it from the system, go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click next to the VDEV to expand it, then look for the disk with the REMOVED status.
Click Detach on the ZFS Info widget on the VDEVs screen for the disk you off-lined.
Select Confirm, then click Detach.
TrueNAS detaches the disk from the pool and promotes the hot spare disk to a full member of the pool.
Refresh the screen to ensure the promoted hot spare appears in the pool as expected.
Recreating a Hot Spare
After promoting the hot spare, recreate the Spare vdev and assign a disk to it.
Do I really need to promote the hot spare and then recreate the spare vdev?
If you have a hot spare inserted into the pool and then follow the instructions in Replacing a Failed Disk Without a Hot Spare, TrueNAS automatically returns the hot spare disk to the existing Spare vdev and ONLINE status.
However, we do not recommend this method because it causes two resilver events: one when activating the hot spare and again when replacing the failed disk.
Resilvering degrades system performance until completed and causes unnecessary strain on the disk.
To avoid unnecessary resilvers, promote the hot spare by [detaching the failed disk]](#detaching-a-failed-disk) then recreate the hot spare vdev.
If recreating the spare with a replacement in place of the failed disk, insert the replacement disk now.
The new disk must have the same or greater capacity as the failed disk.
If recreating the spare with an available disk in the system, proceed to the next step.
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget for the degraded pool to open the VDEVs screen for that pool.
Click Add VDEV to open the Add Vdevs to Pool screen.
Select a disk size equal to or greater than the failed disk or click Manual Disk Selection to choose the replacement disk.
Click Save And Go To Review.
Review changes, then click Update Pool.
Select Confirm, then click Continue.
After completing the job, TrueNAS returns to the Storage Dashboard screen.
Review Spare VDEVs on the VDEVs widget to confirm the hot spare is added.
Wiping a Disk
The disk wipe option deletes obsolete data from an unused disk.
Wipe is a destructive action and results in permanent data loss!
Back up any critical data before wiping a disk.
TrueNAS only shows the Wipe option for unused disks.
Ensure you have backed-up all data and are no longer using the disk.
Triple check that you have selected the correct disk for the wipe.
Recovering data from a wiped disk is usually impossible.
Click Wipe to open a dialog with additional options:
Quick erases only the partitioning information on a disk without clearing other old data, making it easy to reuse. Quick wipes take only a few seconds.
Full with zeros overwrites the entire disk with zeros and can take several hours to complete.
Full with random overwrites the entire disk with random binary code and takes even longer than the Full with zeros operation to complete.
After selecting the appropriate method, click Wipe and confirm the action. A Confirmation dialog opens.
Verify the name to ensure you have chosen the correct disk. When satisfied you can wipe the disk, set Confirm and click Continue.
Continue starts the disk wipe process and opens a progress dialog with the Abort button.
Abort stops the disk wipe process. At the end of the disk wipe process a success dialog displays.
Close closes the dialog and returns you to the Disks screen.
For more general information on SLOG disks, see SLOG Devices.
Because this is a potentially disruptive procedure, contact TrueNAS Enterprise Support to review your overprovisioning needs and schedule a maintenance window.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later).
SED configuration options are not visible in the TrueNAS Community Edition.
Community users wishing to implement SEDs can continue to do so using the command line sedutil-cli utility.
Note: Additional changes to SED management options in the TrueNAS UI ahead of the 25.04.0 release version, with documentation updates to follow.
Supported Specifications
Legacy interface for older ATA devices (Not recommended for security-critical environments!)
TCG Pyrite Version 1 and Version 2 are similar to Opalite, but with hardware encryption removed
Pyrite provides a logical equivalent of the legacy ATA security for non-ATA devices. Only the drive firmware protects the device.
Pyrite Version 1 SEDs do not have PSID support and can become unusable if the password is lost.
TCG Enterprise is designed for systems with many data disks.
These SEDs cannot unlock before the operating system boots.
See this Trusted Computing Group and NVM Express® joint white paper for more details about these specifications.
TrueNAS Implementation
TrueNAS implements the security capabilities of sedutil-cli for TCG-compliant devices.
You can configure a SED before or after assigning the device to a pool.
By default, SEDs are not locked until the administrator takes ownership of them.
Ownership is taken by explicitly configuring a global or per-device password in the web interface and adding the password to the SEDs.
Adding SED passwords in the web interface also allows TrueNAS to automatically unlock SEDs on boot.
A password-protected SED protects the data stored on the device when the device is physically removed from the system.
This allows secure disposal of the device without having to first wipe the contents.
Repurposing a SED on another system requires the SED password or a full cryptographic erase with PSID revert.
Deploying SEDs
TrueNAS supports setting a global password for all detected SEDs or setting individual passwords for each SED.
Using a global password for all SEDs is strongly recommended to simplify deployment and avoid maintaining separate passwords for each SED.
SED passwords are used during initial setup and for unlocking SEDs.
Configuring Global SED Settings
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive widget.
Select the user to unlock SEDs from the ATA Security User dropdown list.
Options are USER or MASTER.
Enter the global SED password in SED Password and in Confirm SED Password.
Click Save.
Remember SED passwords!
If you lose the SED password, you cannot unlock SEDs or access their data.
After configuring or modifying SED passwords, always record and store them in a secure location!
Check SED Functionality
When SED devices are detected during system boot, TrueNAS checks for configured global and device-specific passwords.
Unlocking SEDs allows a pool to contain a mix of SED and non-SED devices.
Devices with individual passwords are unlocked with their password.
Devices without a device-specific password are unlocked using the global password.
Managing SED Disks and Data
Improper use of the sedutil-cli can be destructive to data and passwords.
Keep backups and use with caution.
Additional SED management options are available using a shell session and the sedutil-cli utility.
Enter sedutil-cli -h or see the sedutil-cli.8 man page for more information.
TrueNAS Enterprise
TrueNAS Enterprise customers should contact TrueNAS Enterprise Support for assistance with the initial setup and management of SEDs using sedutil-cli.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
What is a pool?
Storage pools attach drives organized into virtual devices called VDEVs.
Drives arranged inside VDEVs provide varying amounts of redundancy and performance.
ZFS and VDEVs combined create high-performance pools that maximize data lifetime.
ZFS and TrueNAS periodically review and heal when discovering a bad block in a pool.
Reviewing Storage Needs
We strongly recommend that you review your available system resources and plan your storage use case before creating a storage pool. Considerations:
Allocating more drives to a pool increases redundancy when storing critical information.
Maximizing total available storage at the expense of redundancy or performance entails allocating large-volume disks and configuring a pool for minimal redundancy.
Maximizing pool performance entails installing and allocating high-speed SSD drives to a pool.
RAIDz pool layouts are well-suited for general use cases and especially smaller (<10) data VDEVS or storage scenarios that involve storing multitudes of small data blocks.
dRAID pool layouts are useful in specific situations where large disk count (>100) arrays need improved resilver times due to increased disk failure rates and the array is intended to store large data blocks.
TrueNAS recommends defaulting to a RAIDz layout generally and whenever a dRAID vdev would have fewer than 10 data storage devices.
Determining your specific storage requirements is a critical step before creating a pool.
The ZFS and dRAID primers provide a starting point to learn about the strengths and costs of different storage pool layouts.
You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.
Data Encryption
Security requirements can mean the data must be protected with additional encryption.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Creating a Pool
Click Create Pool to open the Pool Creation Wizard.
Pool Creation Wizard
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least two disks in the VDEV.
Storage capacity is the size of a single disk in the VDEV.
RAIDZ and dRAID
Each of these layouts has 1, 2, and 3 options.
The options indicate the number of disks reserved for data parity and the number of disks that can fail in the VDEV without data loss to the pool.
For example, a RAIDZ2 layout reserves two additional disks for parity, and two disks can fail without data loss.
Automated Disk Selection - Stripe, Mirror, and RAIDZ layouts
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Width
Select the number of disks from the options provided on the dropdown list.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list.
Automated Disk Selection - dRAID layouts
Similar to RAIDZ, dRAID layout numbers (1, 2, or 3) indicate the parity level and how many disks can fail without data loss to the pool.
TrueNAS defaults to allocating 10 disks minimum as dRAID VDEV in Children.
If creating a data VDEV with fewer than 10 disks, using a RAIDZ layout is strongly recommended for better performance and capacity optimization.
Setting
Description
Disk Size
Select the disk size from the list that displays. The list shows disks by size in GiB and type (SSD or HDD).
Treat Disk Size as Minimum
Select to use disks of the size selected in Disk Size or larger. If not selected, only disks of the size selected in Disk Size are used.
Data Devices
Data stripe width for the VDEV. Select the number of disks from the options provided on the dropdown list. TrueNAS recommends that dRAID layouts have data devices allocated in multiples of two.
Distributed Hot Spares
Number of disk areas to actively provide spare capacity to the entire VDEV. These areas are active within the pool and function in of adding a Spare VDEV to the pool. We recommend setting this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Enclosure Option only shows for TrueNAS Enterprise systems with connected expansion shelves.
You can rename your enclosure on the Enclosure screen to include the rack and U number in the name, which helps identify the physical location while in the pool creation screen.
Enter a name of up to 50 lowercase alpha-numeric characters.
Use only the permitted special characters that conform to ZFS naming conventions.
The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
You cannot change the pool name after creation.
(Enterprise systems only) Select the Enclosure Option to apply the dispersal strategy of your choice.
This option only shows for TrueNAS Enterprise systems with connected expansion shelves.
The dispersal strategy sets how the system adds disks by size and type to the pool VDEVs created using the Automated Disk Selection option. Enclosures mentioned in the options below refer to the disk enclosures in the expansion shelves and main system chassis.
No Enclosure Dispersal Strategy does not apply a dispersal strategy, and does not show additional options.
Disks added to the pool VDEVs are assigned in sequence based on disk availability and are not balanced across all enclosures.
Maximum Dispersal Strategy applies a maximum dispersal strategy.
This option balances disk selection across all enclosures and available disks and does not show additional options.
Disks added to the pool VDEVs are spread across all available enclosure disks.
Limit Pool To A Single Enclosure applies a minimum dispersal strategy.
Select the expansion shelf option on the Enclosure dropdown.
Disks added to the pool VDEVs are spread across the enclosure disks that align with the selection in Enclosure.
Select the layout from the Layout dropdown list, then use the Automated Disk Selection fields to select and add the disks, or click Manual Disk Selection to add specific disks to the chosen Layout.
dRAID layouts do not show the Manual Disk Selection button but do show additional Automated Disk Selection fields.
When configuring a dRAID data VDEV, first, choose a Disk Size then select a Data Devices number.
The remaining fields update based on the Data Devices and dRAID layout selections.
ZFS allows groups to span multiple rows, which means it does not require each row to contain a whole number of redundancy groups. This layout has several advantages over requiring whole groups in each row:
Group count - Group count is not a relevant parameter when defining a dRAID layout. ZFS only needs the group width and all groups will have the desired size.
Group widths - ZFS can support all possible group widths (greater than or equal to the physical disk count).
ZFS determines the number of groups by the least common multiple (LCM) of the group width (D+P) and the number of physical drives minus spares (C-S). The logic within dRAID is simplified when the group width is the same for all groups, although some aspects, such as computing permutation numbers and drive offsets, are more complex. This flexible layout ensures even distribution of data and parity while maintaining high performance and resilvering efficiency.
Click Save And Go To Review if not adding other VDEV types to the pool or click Next to move forward to the next wizard screen.
Add optional VDEVs to suit your storage redundancy and performance requirements.
Click Create Pool on the Review wizard screen to add the pool.
Fusion Pools
Fusion Pools are also known as ZFS allocation classes, ZFS special vdevs, and metadata vdevs (Metadata vdev type on the Pool Manager screen.).
What's a special VDEV?
A special VDEV can store metadata such as file locations and allocation tables.
The allocations in the special class are dedicated to specific block types.
By default, this includes all metadata, the indirect blocks of user data, and any deduplication tables.
The class can also be provisioned to accept small file blocks.
This is a great use case for high-performance but smaller-sized solid-state storage.
Using a special vdev drastically speeds up random I/O and cuts the average spinning-disk I/Os needed to find and access a file by up to half.
Creating a Fusion Pool
Go to the Storage Dashboard and click Create Pool.
A pool must always have one normal (non-dedup/special) VDEV before you assign other devices to the special class.
Enter a name for the pool using up to 50 lowercase alpha-numeric and permitted special characters that conform to ZFS naming conventions.
The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
Click ADD VDEV and select Metadata to add the VDEV to the pool layout.
Add disks to the primary Data VDevs, then to the Metadata VDEV.
Add SSDs to the new Metadata VDev and select the same layout as the Data VDevs.
Metadata VDEVs are critical for pool operation and data integrity. Protect them with redundancy measures such as mirroring, and optionally hot spare(s) for additional fault tolerance. It is suggested to use an equal or greater level of failure tolerance in each of your metadata VDEVs; for example, if your data VDEVs are configured as RAIDZ2, consider the use of 3-way mirrors for your metadata VDEVs.
UPS Recommendation
When using SSDs with an internal cache, add an uninterruptible power supply (UPS) to the system to help minimize the risk from power loss.
Using special VDEVs identical to the data VDEVs (so they can use the same hot spares) is recommended, but for performance reasons, you can make a different type of VDEV (like a mirror of SSDs).
In that case, you must provide hot spare(s) for that drive type as well. Otherwise, if the special VDEV fails and there is no redundancy, the pool becomes corrupted and prevents access to stored data.
While the metadata VDEV can be adjusted after its addition by attaching or detaching drives, the entire metadata VDEV itself can only be removed from the pool when the pool data VDEVs are mirrors. If the pool uses RAIDZ data VDEVs, a metadata VDEV is a permanent addition to the pool and cannot be removed.
When more than one metadata VDEV is created, then allocations are load-balanced between all these devices.
If the special class becomes full, then allocations spill back into the normal class.
Deduplication table data is placed first onto a dedicated Dedup VDEV, then a Metadata VDEV, and finally the data VDEVs if neither exists.
Create a fusion pool and Status shows a Special section with the metadata SSDs.
Managing Pools
The Storage Dashboard widgets provide enhanced storage provisioning capabilities and access to pool management options to keep the pool and disks healthy, upgrade pools and VDEVs, open datasets, snapshots, and data protection screens.
This article provides instructions on pool management functions available in the TrueNAS UI.
Select Storage on the main navigation panel to open the Storage Dashboard.
Locate the Storage Health widget for the pool, then click the Edit Auto TRIM. The Pool Options for poolname dialog opens.
With Auto TRIM selected and active, TrueNAS periodically checks the pool disks for storage blocks it can reclaim.
Auto TRIM can impact pool performance, so the default setting is disabled.
For more details about TRIM in ZFS, see the autotrim property description in zpool.8.
Exporting/Disconnecting or Deleting a Pool
Use the Export/Disconnect button to disconnect a pool and transfer drives to a new system where you can import the pool.
It also lets you completely delete the pool and any data stored on it.
Click on Export/Disconnect on the Storage Dashboard.
A dialog displays showing any system services affected by exporting the pool, and options based on services configured on the system.
To delete the pool and erase all the data on the pool, select Destroy data on this pool.
The pool name field displays at the bottom of the window. Type the pool name into this field. To export the pool, do not select this option.
Select Delete saved configurations from TrueNAS? to delete shares and saved configurations on this pool.
Select Confirm Export/Disconnect
Click Export/Disconnect. A confirmation dialog displays when the export/disconnect completes.
Upgrading a Pool
Upgrading a storage pool is typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Do not do a pool-wide ZFS upgrade until you are ready to commit to this TrueNAS major version! You can not undo a pool upgrade, and you lose the ability to roll back to an earlier major version!
The Upgrade button displays on the Storage Dashboard for existing pools after an upgrade to a new TrueNAS major version that includes new OpenZFS feature flags.
Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS version.
Upgrading pools only takes a few seconds and is non-disruptive.
However, the best practice is to upgrade a pool while it is not in heavy use.
The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
It is not necessary to stop sharing services to upgrade the pool.
Running a Pool Data Integrity Check (Scrub)
Use Scrub Now on the Storage Health pool widget to start a pool data integrity check.
Click Scrub Now to open the Scrub Pool dialog, then click Start Scrub to begin the process.
If TrueNAS detects problems during the scrub operation, it either corrects them or generates an alert in the web interface.
A scrub is a data integrity check of your pool. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
Scheduling Scrub Tasks
TrueNAS automatically creates a scheduled scrub for each pool that runs every Sunday at 12:00 AM.
The Storage Health widget shows the scheduled scrub status:
Scheduled Scrub: None Set with a Schedule link if no scrub task exists
Scheduled Scrub: [when] with a Configure link if a scrub task is configured and enabled
Click Schedule to create a new scrub schedule or Configure to modify an existing schedule. This opens the Configure Scheduled Scrub screen where you can set the schedule, threshold days, and enable or disable the scheduled scrub.
Threshold Days sets the days before a completed scrub is allowed to run again.
This controls the task schedule.
For example, scheduling a scrub to run daily and setting threshold days to 7 means the scrub attempts to run daily.
When the scrub is successful, it continues to check daily but does not run again until seven days have elapsed.
Using a multiple of seven ensures the scrub always occurs on the same weekday.
Starting in TrueNAS 25.10, resilver priority settings are now located in System Settings > Advanced Settings on the Storage widget.
Managing Pool Disks
The Storage Dashboard screen Disks button and the View Disks button on the Disk Health widget both open the Disks screen.
View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
To manage disks in a pool, click on the VDEV to expand it and show the disks in that VDEV.
Click on a disk to see the widgets for that disk.
You can take a disk offline, detach it, replace it, manage the SED encryption password, and perform other disk management tasks from this screen.
See Replacing Disks for more information on the Offline, Replace and Online options.
Expanding a Pool
There are a few ways to increase the size of an existing pool:
Add one or more drives to an existing RAIDZ VDEV.
Add a new VDEV of the same type.
Add a new VDEV of a different type.
Replace all existing disks in the VDEV with larger disks.
Adding a new special VDEV increases usable space in combination with a special_small_files VDEV, but it is not encouraged. A VDEV limits all disks to the usable capacity of the smallest attached device.
When using one of the above methods, TrueNAS does not automatically expand the pool to fit newly available space.
Go to Storage and click Expand Pool above the Usage widget.
Select Confirm in the Expand Pool dialog.
Click Continue to start the pool expansion process.
TrueNAS expands the pool to use the additional available capacity.
Extending a RAIDZ VDEV
Extend a RAIDZ VDEV to add additional disks one at a time, expanding capacity incrementally.
This is useful for small pools (typically with only one RAID-Z VDEV), where there is not enough hardware capacity to add a second VDEV, doubling the number of disks.
Overview and Considerations
TrueNAS 24.10 (Electric Eel) introduces the RAIDZ extension to allow incremental expansion of an existing RAIDZ VDEV using one more disk.
RAIDZ extension allows resource- or hardware-limited home lab and small enterprise users to expand storage capacity with lower upfront costs compared to traditional ZFS expansion methods.
To expand a RAIDZ array, TrueNAS reads data from the current disks and rewrites it onto the new configuration, including any additional disks.
Data redundancy is maintained.
Make sure the pool is healthy before beginning the expansion process.
If a disk fails mid-expansion, the process pauses until the RAIDZ virtual device (vdev) is healthy again, typically by replacing the failed disk and waiting for the system to rebuild.
The storage pool remains accessible throughout the expansion.
If you restart or export/import the pool, the expansion resumes from where it left off.
After the expansion, the extra space becomes available for use.
The fault-tolerance level of the RAIDZ array remains unchanged.
For example, a four-disk-wide RAIDZ2 expanded to a six-disk-wide RAIDZ2 still cannot lose more than two disks at a time.
You can expand a RAIDZ vdev multiple times.
Existing data blocks retain their original data-to-parity ratio and block width, but spread across the larger set of disks.
New data blocks adopt the new data-to-parity ratio and width.
Because of this overhead, an extended RAIDZ VDEV can report a lower total capacity than a freshly created VDEV with the same number of disks.
Before (left) and after (right) expansion of a four-disk to five-disk RAIDZ1 Thanks to Matt Ahrens (Source)
Extended VDEVs recover lost headroom as existing data is read and rewritten to the new parity ratio.
This can occur naturally over the lifetime of the pool as you modify or delete data.
To manually recover capacity, simply replicate and rewrite the data to the extended pool.
You can use the RAIDZ Extension Calculator to visualize potential lost headroom and capacity available to recover by rewriting existing data.
While this process can recover the actual lost capacity, reported capacity continues to rely on the old data-to-parity ratio.
An expanded vdev can continue to report a lower than expected capacity, even after rewriting old data to the new parity ratio.
This accounting inconsistency does not impact the actual available capacity of the vdev.
Select an available disk from the New Disk dropdown menu.
Click Extend.
A job progress window opens.
TrueNAS returns to the Poolname VDEVs screen when complete.
Adding a VDEV to a Pool
ZFS supports adding VDEVs to an existing ZFS pool to increase the capacity or performance of the pool.
To extend a pool by mirroring, you must add a data VDEV of the same type as existing VDEVs.
You cannot change the original encryption or data VDEV configuration.
Adding VDEV Examples
To make a striped mirror, add the same number of drives to extend a ZFS mirror.
For example, you start with ten available drives. Begin by creating a mirror of two drives, and then extend the mirror by adding another mirror of two drives. Repeat this three more times until you add all ten drives.
To make a stripe of two 3-drive RAIDZ1 VDEVs (similar to RAID 50 on a hardware controller), add another three drives as a new RAIDZ1 VDEV to the existing single 3-drive RAIDZ1 VDEV pool.
To make a stripe of two 6-disk RAIDZ2 VDEVs (similar to RAID 60 on a hardware controller), add another six drives as a new RAIDZ2 VDEV to the existing single 6-drive RAIDZ2 VDEV pool.
To add a deduplication VDEV, we suggest creating the VDEV when you first create the pool to ensure that all metadata or deduplication tables are stored on it.
Special or deduplication VDEVs added to a pool with existing data are only populated with new writes.
To add a VDEV to a pool:
Click View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
Click Add VDEV on the PoolnameVDEVs screen to open the Add Vdevs to Pool screen.
Adding a vdev to an existing pool follows the same process as documented in Create Pool.
Click on the type of vdev you want to add, for example, to add a spare, click on Spare to show the vdev spare options.
To use the Automated Disk Selection option, select the disk size. The Width and Number of VDEVs fields populate with default values based on the layout and disk size selected. To change this, select new values from the dropdown lists.
Adding a VDEV Manually
To add the vdev manually, click Manual Disk Selection to open the Manual Selection screen.
Click Add to show the vdev options available for the vdev type.
The example image shows adding a stripe vdev for the spare.
Vdev options are limited by the number of available disks in your system and the configuration of any existing vdevs of that type in the pool.
Drag the disk icon to the stripe vdev, then click Save Selection.
You have the option to accept the change or click Edit Manual Disk Selection to change the disk added to the strip vdev for the spare, or click Reset Step to clear the strip vdev from the spare completely.
Click either Next or a numbered item to add another type of vdev to this pool.
Repeat the same process above for each type of vdev to add.
Click Save and Go to Review to go to the Review screen when ready to save your changes.
To make changes, click either Back or the vdev option (i.e., Log, Cache, etc.) to return to the settings for that vdev.
To clear all changes, click Start Over.
Select Confirm, then click Start Over to clear all changes.
Click Update Pool to save changes.
Adding a Deduplication VDEV
You can add a deduplication VDEV to an existing pool, but files in the pool might or might not have deduplication applied to them.
When adding a deduplication VDEV to an existing pool, any existing entries in the deduplication table remain on the data VDEVs until the data they reference is rewritten.
After adding a deduplication VDEV to a pool, and when duplicated files are added to the pool, the Storage Health widget on the Storage Dashboard shows two links, Prune and Set Quota. These links do not show if duplicated files do not exist in the pool.
Use Prune to set the parameters used to prune the deduplication table (DDT). Select the measurement used, percentage or age, when pruning the table size.
Use Set Quota to set the DDT quota that determines the maximum table size allowed.
The default setting, Auto, allows the system to determine the quota based on the size of a dedicated dedup vdev when setting the quota limit.
This property works for both legacy and fast dedup tables.
Change to Custom to set the quota to your preference.
Click Save to save and close the dialogs.
Replacing Disks to Expand a Pool
To expand a pool by replacing disks with a higher capacity disk, follow the same procedure as in Replacing Disks.
Insert a new disk into an empty enclosure slot. Remove the old disk only after completing the replacement operation.
If an empty slot is not available, you can offline the existing disk and replace it in the same slot, but this reduces redundancy during the process.
Go to the Storage Dashboard and click View VDEVs on the VDEVs widget opens the Poolname VDEVs screen..
Click anywhere on the VDEV to expand it and select one of the existing disks.
(Optional) If replacing disks in the same slot, take one existing disk offline.
Add the new disk to the existing VDEV. Click Replace Disk to add the new disk to the VDEV and bring it online.
Disk replacement fails when the selected disk has partitions or data present.
To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.
After the disk wipe completes, TrueNAS starts replacing the failed disk.
TrueNAS resilvers the pool during the replacement process.
For pools with large amounts of data, this can take a long time.
When the resilver process completes, the pool status returns to Online status on the Poolname Devices screen.
Wait for the resilver to complete before replacing the next disk.
Repeat steps 1-4 for all attached disks.
After replacing the last attached disk, click Expand on the Storage Dashboard to increase the pool size to fit all available disk space.
Removing VDEVs
You can always remove the L2ARC (cache) and SLOG (log) VDEVs from an existing pool, regardless of topology or VDEV type.
Removing these devices does not impact data integrity, but it can significantly impact performance for reads and writes.
In addition, you can remove a data VDEV from an existing pool under specific circumstances.
This process preserves data integrity but has multiple requirements:
The pool must be upgraded to a ZFS version that includes the device_removal feature flag.
The system shows the Upgrade button after upgrading TrueNAS when new ZFS feature flags are available.
All top-level VDEVs in the pool must be only mirrors or stripes.
Special VDEVs cannot be removed when RAIDZ data VDEVs are present.
All top-level VDEVs in the pool must use the same basic allocation unit size (ashift).
The remaining data VDEVs must contain sufficient free space to hold all of the data from the removed VDEV.
When a RAIDZ data VDEV is present, it is generally not possible to remove a device.
To remove a VDEV from a pool:
Click *View VDEVs on the VDEVs widget opens the Poolname VDEVs screen.
Click the device or drive to remove, then click the Remove button in the ZFS Info widget.
If the Remove button is not visible, check that all conditions for VDEV removal listed above are correct.
Confirm the removal operation and click the Remove button.
The VDEV removal process status shows in the Jobs screen (or alternately with the zpool status command).
Avoid physically removing or attempting to wipe the disks until the removal operation completes.
Datasets
This section has tutorials about dataset configuration and management.
Creating Snapshots: Provides instructions on creating ZFS snapshots in TrueNAS.
Managing Snapshots: Provides instructions on managing ZFS snapshots in TrueNAS.
Storage Encryption: Provides information on TrueNAS storage encryption for pools, root datasets, datasets, and zvols.
Configuring ACL Permissions: Provides general information on ACLs, and instructions on editing and viewing ACL permissions using the ACL editor screens.
Adding and Managing Datasets
A TrueNAS dataset is a file system within a data storage pool.
Datasets can contain files, directories, and child datasets, and have individual permissions or flags.
Datasets can also be encrypted.
In TrueNAS 22.12.3 or later, the TrueNAS UI requires encryption for child datasets created in encrypted parent datasets, but you can change the encryption type from key to passphrase.
You can create an encrypted dataset if the parent is not encrypted and set the type as either key or passphrase.
We recommend organizing your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.
Creating a Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
Setting Dataset Compression Levels
Compression encodes information in less space than the original data occupies.
We recommend choosing a compression algorithm that balances disk performance with the amount of saved space.
The Compression Level setting lists several compression algorithm to choose from. Select the option that best suits your needs from the dropdown list.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Setting Dataset Quotas
You can set dataset quotas while adding datasets using the quota management options in the Add Dataset screen under Advanced Options.
You can also add or edit quotas for an existing dataset, by clicking Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset.
You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space.
You can configure quotas for only the new dataset or both the new dataset and any child datasets of the new dataset.
Define the maximum allowed space for the dataset in either the Quota for this dataset or Quota for this dataset and all children field.
Enter 0 to disable quotas.
Dataset quota alerts are based on the percentage of storage used.
To set up a quota warning alert, enter a percentage value in Quota warning alert at, %.
When consumed space reaches the defined percentage it sends the alert.
To change the setting from the parent dataset warning level, clear the Inherit checkbox and then change the value.
To set up the quota critical level alerts, enter the percentage value in Quota critical alert at, %.
Clear the Inherit checkbox to change this value to something other than using the parent alert setting.
When setting quotas or changing the alert percentages for both the parent dataset and all child datasets, use the fields under This Dataset and Child Datasets.
Enter a value in Reserved space for this dataset to set aside additional space for datasets that contain logs, which could eventually take all available free space.
Enter 0 for unlimited.
By default, many dataset options inherit their values from the parent dataset.
When settings on the Advanced Options screen are set toInherit the dataset uses the setting from the parent dataset.
For example, the Encryption or ACL Type settings.
To change any setting that datasets inherit from the parent, select an available option other than Inherit.
Deduplication is found on the Add Datasets Advanced Settings screen.
Best practice is to add deduplication when you first create the dataset.
You can add deduplication to an existing dataset but existing files do not have deduplication applied to them.
Adding deduplication to an existing dataset only applies deduplication to data written after you enable the function.
When enabling deduplication for a dataset of a pool that does not have a deduplication or special VDEV, the deduplication table (DDT) is stored on a regular VDEVs of the pool.
To store the DDT outside of the regular VDEVs, add a deduplication or special VDEV to the pool.
To add deduplication to a new dataset, after entering the name and selecting the dataset preset, click Advanced Settings.
To add deduplication to an existing dataset, select the dataset on the Dataset screen tree table, click Edit on the Dataset Details widget to open the Edit Dataset screen. Click Advanced Settings.
Scroll down to the ZFS Deduplication setting, then change to On.
A warning dialog opens and states that deduplication is an experimental and not fully supported feature.
Select the root dataset of the pool (with the metadata VDEV), then click Add Dataset to add the dataset.
Click Advanced Options. Enter the dataset name, select the Dataset Preset, then scroll down to Metadata (Special) Small Block Size setting to set a threshold block size for including small file blocks into the special allocation class (fusion pools).
Blocks smaller than or equal to this value are assigned to the special allocation class while greater blocks are assigned to the regular class.
Valid values are zero or a power of two from 512B up to 1M.
The default size 0 means no small file blocks are allocated in the special class.
Enter a threshold block size for including small file blocks into the special allocation class (fusion pools).
Managing Datasets
After creating a dataset, users can manage additional options from the Datasets screen.
Select the dataset, then click Edit on the dataset widget for the function you want to manage.
The Datasets Screen article describes each option in detail.
Editing a Dataset
Select the dataset on the tree table, then click Edit on the Dataset Details widget to open the Edit Dataset screen and change the dataset configuration settings. You can change all settings except Name, Case Sensitivity, or Device Preset.
Editing Dataset Permissions
To edit the dataset ACL permissions, click Edit on the Permissions widget.
If the ACL type is NFSv4, the Permissions widget shows ACE entries for the dataset.
Each entry opens a checklist of flag options you can select or clear without opening the Edit ACL screen.
To modify ownership, configure new or change existing ACL entries, click Edit to open the ACL Editor screen.
To edit a POSIX ACL type, click Edit on the Permissions widget to open the Unix Permissions Editor screen.
To access the Edit ACL screen for POSIX ACLs, select Create a custom ACL on the Select a preset ACL window.
Select the dataset on the tree table, then click Delete on the Dataset Details widget.
This opens a delete window where you enter the dataset path (root/parent/child) and select Confirm to delete the dataset, all stored data, and any snapshots from TrueNAS.
To delete a root dataset, use the Export/Disconnect option on the Storage Dashboard screen to delete the pool.
Deleting datasets can result in unrecoverable data loss!
Move any critical data stored on the dataset off to a backup copy or obsolete the data before performing the delete operation.
Adding and Managing Zvols
A ZFS Volume (zvol) is a dataset that represents a block device or virtual disk drive.
TrueNAS requires a zvol when configuring iSCSI Shares.
Adding a virtual machine also creates a zvol to use for storage.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused.
Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume.
Do not assign capacity that exceeds what is required for TrueNAS to operate properly. For more information, see TrueNAS Hardware Guide for CPU, memory and storage capacity information.
Adding a Zvol
To create a zvol, go to Datasets.
Select the root or non-root parent dataset where you want to add the zvol, and then click Add Zvol.
Enter a name that does not exceed 60 characters, enter a number and letter for the unit of measure in Size, and then click Save.
Managing Zvols
Options to manage a zvol are on the zvol widgets shown on the Dataset screen when you select the zvol on the dataset tree table.
Delete Zvol removes the zvol from TrueNAS.
Deleting a zvol also deletes all snapshots of that zvol. Click Delete on the Zvol Details widget.
Deleting zvols can result in unrecoverable data loss!
Remove critical data from the zvol or verify it is obsolete before deleting a zvol.
Edit on the Zvol Details widget opens the Edit Zvol screen where you can change settings. Name is read-only and you cannot change it.
To create a snapshot, click Take Snapshot on the Data Protection widget.
Cloning a Zvol from a Snapshot
To clone a zvol from an existing snapshot, select the zvol on the datasets tree table, then click View Snapshots on the Data Protection widget to open the Snapshots screen.
You can also access the Snapshots screen from the Periodic Snapshot Tasks screen. Click on the Periodic Snapshot Task widget header on the Data Protection screen to open the Period Snapshot Tasks screen.
Click Snapshots to open the Snapshots screen.
Click on the snapshot you want to clone, then click Clone to New Dataset.
Enter a name for the new dataset or accept the one provided, then click Clone.
The cloned zvol shows on the Datasets screen.
Managing User or Group Quotas
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
You can use the quota settings on the Add Dataset or Edit Dataset configuration screens in the Advanced Options settings to set up alarms and set aside more space in a dataset.
See Adding and Managing Datasets for more information.
To manage the dataset overall capacity, use Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Configuring User Quotas
To view and edit user quotas, go to Datasets and click Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.
Click Add to open the Add User Quota screen.
Click in the field to view a list of system users including any users from a directory server that is properly connected to TrueNAS.
Begin typing a user name to filter all users on the system to find the desired user, then click on the user to add the name.
Add additional users by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual user quotas, click anywhere on a user row to open the Edit User Quota screen where you can edit the User Data Quota and User Object Quota values.
User Data Quota is the amount of disk space that selected users can use. User Object Quota is the number of objects selected users can own.
Configuring Group Quotas
Click Add to open the Add Group Quota screen.
Click in the Group field to view a list of system groups on the system.
Begin typing a name to filter all groups on the system to find the desired group, then click on the group to add the name.
Add additional groups by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual group quotas, click anywhere on a group name to open the Edit Group Quota screen where you can edit the Group Data Quota and Group Object Quota values.
Group Data Quota is the amount of disk space that the selected group can use. Group Object Quota is the number of objects the selected group can own.
Creating Snapshots
Snapshots are one of the most powerful features of ZFS.
A snapshot provides a read only point-in-time copy of a file system or volume.
This copy does not consume extra space in the ZFS pool.
The snapshot only records the differences between storage block references whenever the data is modified.
Why do I want to keep snapshots?
Snapshots keep a history of files and provide a way to recover an older or even deleted files.
For this reason, many administrators take regular snapshots, store them for some time, and copy them to a different system.
This strategy allows an administrator to roll the system data back to a specific point in time.
In the event of catastrophic system or disk failure, off-site snapshots can restore data up to the most recent snapshot.
Taking snapshots requires the system have all pools, datasets, and zvols already configured.
Creating a Snapshot
Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.
There are two ways to access snapshot creation:
From the Data Protection Screen
To access the Snapshots screen, go to Data Protection > Periodic Snapshot Tasks and click the Snapshots button in the lower left corner of the widget.
If you click Create Snapshot the Snapshots screen opens filtered for the selected dataset.
Clear the dataset from the search field to see all snapshots.
You can also click the Manage Snapshots link on the Data Protection widget to open the Snapshots screen.
Click Add at the top right of the screen to open the Add Snapshot screen.
Select a dataset or zvol from the Dataset dropdown list.
Accept the name suggested by the TrueNAS software in the Name field or enter any custom string to override the suggested name.
(Optional) Select an option from the Naming Schema dropdown list that the TrueNAS software populated with existing periodic snapshot task schemas.
If you select an option, TrueNAS generates a name for the snapshot using that naming schema from the selected periodic snapshot and replicates that snapshot.
You cannot enter a value in both Naming Schema and in Name as selecting or entering a value in Naming Schema populates the other field.
(Optional) Select Recursive to include child datasets with the snapshot.
Click Save to create the snapshot.
Managing Snapshots
Viewing the List of Snapshots
File Explorer limits the number of snapshots Windows presents to users. If TrueNAS responds with more than the File Explorer limit, File Explorer shows no available snapshots.
TrueNAS displays a dialog stating the dataset snapshot count has more snapshots than recommended and states performance or functionality might degrade.
There are two ways to view the list of snapshots:
Go to Datasets > Data Protection widget > Manage Snapshots link to open the Snapshots screen.
The Snapshots screen displays a list of snapshots on the system. Use the search bar at the top to narrow the selection. Clear the search bar to list all snapshots.
Use the Clone to New Dataset button to create a clone of the snapshot.
The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen.
Click Clone to New Dataset to open a clone confirmation dialog.
The Delete option destroys the snapshot.
You must delete child clones before you can delete their parent snapshot.
While creating a snapshot is instantaneous, deleting one is I/O intensive and can take a long time, especially when deduplication is enabled.
Why?
ZFS has to review all allocated blocks before deletion to see if another process is using that block. If not used, the ZFS can free that block.
Click the Delete button. A confirmation dialog displays. Select Confirm to activate the Delete button.
Deleting with Batch Operations
To delete multiple snapshots, select the left column box for each snapshot to include. Click the deleteDelete button that displays.
To search through the snapshots list by name, type a matching criteria into the searchFilter Snapshots text field.
The list now displays only the snapshot names that match the filter text.
Confirm activates the Delete button. If the snapshot has the Hold options selected, an error displays to prevent you from deleting that snapshot.
Using Rollback to Revert a Dataset
The Rollback option reverts the dataset to the point in time saved by the snapshot.
Rollback is a dangerous operation that causes any configured replication tasks to fail.
Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out of order.
A less disruptive method to restore data from a point in time is to clone a specific snapshot as a new dataset:
Clone the desired snapshot.
Share the clone with the share type or service running on the TrueNAS system.
Allow users to recover their needed data.
Delete the clone from Datasets.
This approach does not destroy any on-disk data or disrupt automated replication tasks.
TrueNAS asks for confirmation before rolling back to the chosen snapshot state.
Select the radio button for how you want the rollback to operate.
All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden .zfs located at the root of every dataset.
A snapshot and any files it contains are not accessible or searchable if the snapshot mount path is longer than 88 characters.
The data within the snapshot is safe but to make the snapshot accessible again shorten the mount path.
Users can browse and search any files they have permission to access throughout the entire dataset snapshot collection.
When creating a snapshot, permissions or ACLs set on files within that snapshot might limit access to the files.
Snapshots are read-only, so users do not have permission to modify a snapshot or its files, even if they had write permissions when creating the snapshot.
From the Datasets screen, select the dataset and click Edit on the Dataset Details widget.
Click Advanced Options and set Snapshot Directory to Visible.
To access snapshots using a share, configure the client system to view hidden files.
For example, in a Windows SMB share, enable Show hidden files, folders, and drives in Folder Options.
From to the dataset root folder, open the .zfs directory and navigate to the snapshot.
Storage Encryption
TrueNAS offers ZFS encryption for your sensitive data in datasets and zvols.
Users are responsible for backing up and securing encryption keys and passphrases!
Losing the ability to decrypt data is similar to a catastrophic data loss.
The local TrueNAS system manages keys for data-at-rest.
Users are responsible for storing and securing their keys.
TrueNAS includes the Key Management Interface Protocol (KMIP).
Pool and Dataset Encryption
Encryption is for users storing sensitive data.
It does not apply encryption to the storage vdev or the disks in the pool.
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Leave Encryption unselected on the Pool Creation Wizard screen to create a pool with an unencrypted root dataset.
You can create both encrypted and unencrypted datasets within an unencrypted pool.
By default, child datasets inherit encryption settings from the parent.
Disabling Inherit under Advanced Options allows modifying the encryption configuration for a child dataset.
You cannot change a child dataset of an encrypted parent dataset to unencrypted.
However, datasets created outside the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured.
For example, the ix-apps dataset on the pool selected for applications does not inherit encryption settings.
Can I change dataset encryption?
Before saving a new dataset, you can change the type of encryption of an encrypted dataset to key to passphrase.
After saving a dataset with encryption applied you cannot change the dataset to unencrypted.Can I unencrypt my data?
Yes, you can move encrypted data to an unencrypted pool or dataset using either rsync or replication.
You can also move data from an unencrypted pool or dataset to an encrypted dataset using rsync or replication.
If your system loses power or you restart the system, all encrypted datasets and zvols automatically lock to protect data.
Encryption Visual Cues
TrueNAS uses lock icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen.
Each icon shows a text label with the state of the dataset when you hover the mouse over the icon.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
A dataset that inherits encryption shows the mouse hover-over label Locked by ancestor or Unlocked by ancestor.
Select an encrypted dataset to see the ZFS Encryption widget on the Datasets screen.
The dataset encryption state is unlocked until you lock it using the Lock button on the ZFS Encryption widget.
After locking the dataset, the icon on the tree table changes to locked, and the Unlock button appears on the ZFS Encryption widget.
Implementing Encryption
Before creating a encrypted pool (root dataset) or dataset, decide if you want to encrypt all child datasets, zvols, and data stored on that dataset.
If your system does not have enough disks to create a second storage pool, we recommend not using encryption at the pool level.
Apply encryption at the dataset level to non-root parent or child datasets.
All pool-level encryption is key-based encryption. When prompted, download the encryption key and keep it stored in a safe place where you can back up the key file.
You cannot use passphrase encryption at the pool level.
You cannot change an existing dataset from encrypted to unencrypted.
You can only change the dataset encryption type (key or passphrase).
Adding Encryption to a New Pool
Encrypting the root dataset (pool-level encryption) creates a single point of failure.
Losing one key makes the entire pool inaccessible.
Best practice
Do not enable encryption during pool creation.
Instead, create an unencrypted pool with individually encrypted datasets and zvols.
This allows independent key management, selective unlock, isolated failures, and simplified recovery.
Go to Storage and click Create Pool on the Storage Dashboard screen.
Or click Add to Pool on the Unassigned Disks widget and click Add to New to open the Pool Creation Wizard.
Enter a name for the pool, then select Encryption. Select the layout for the data VDEV and add the disks.
A warning dialog displays after selecting Encryption.
Read the warning, select Confirm, and then click I UNDERSTAND.
A second dialog opens where you click Download Encryption Key for the pool encryption key.
Click Done to close the window.
Move the encryption key to safe location where you can back up the file.
Add the VDEVs to the pool you want to include, then click Save to create the pool with encryption.
Adding Encryption to a New Dataset
To add an encrypted dataset, go to Datasets.
Select a dataset on the tree table where you want to add a new dataset.
The default dataset selected when you open the Datasets screen is the root dataset of the first pool on the tree table list.
If you have more than one pool and want to create a dataset in a pool other than the default, select the root dataset for that pool or any dataset under the root where you want to add the new dataset.
Click Add Dataset to open the Add Dataset screen, and enter a name.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
.
Click Advanced Options.
To add encryption to a dataset, scroll down to Encryption Options and select the inherit checkbox to clear the checkmark and show the Encryption option. Clear this checkbox to show the default settings for key type encryption.
If the parent dataset is unencrypted and you want to encrypt the dataset select the Inherit (non-encrypted) checkbox to clear it and show the Encryption option.
If the parent dataset is encrypted and you want to change the type, select Inherit (encrypted) to show the encryption configuration options.
To keep the dataset encryption settings from the parent, leave inherit selected.
Decide if you want to use the default key type encryption and want to let the system generate the encryption key.
To use key encryption and an existing key, disable Generate Key to display the Key field.
Enter the existing key in this field.
The passphrase must be longer than 8 and less than 512 characters.
Keep encryption keys and/or passphrases safeguarded in a secure and protected place.
Losing encryption keys or passphrases can result in permanent data loss!
Select the encryption algorithm from Algorithm or use the recommended default.
Leave the default selection if you do not have a particular encryption standard you want to use. What are these options?
TrueNAS supports AES Galois Counter Mode (GCM) and Counter with CBC-MAC (CCM) algorithms for encryption.
These algorithms provide authenticated encryption with block ciphers.
Changing Dataset (or Zvol) Encryption
You cannot add encryption to an existing dataset!
You can change the type of encryption for an already encrypted dataset using the Edit option on the Encryption widget for the dataset.
Save changes to the encryption key or passphrase, update your saved passcodes and keys file, and back up that file.
To change the encryption type, go to Datasets, select the encrypted dataset on the tree table, then click Edit on the Encryption widget.
The Edit Encryption Options dialog for the selected dataset opens.
Before making changes to a locked encrypted dataset you must unlock it.
If the dataset inherits encryption settings from a parent dataset, to change this, clear the Inherit encryption properties from parent checkbox to display the key type encryption setting options.
If the encryption type is set to passphrase, you can change the passphrase, or change Encryption Type to key.
You cannot change a dataset created with a key as the encryption type to passphrase.
Key type options are Generate Key (pre-selected) or clear to display the Key field. Enter your new key in this field.
Use a complex passphrase that is not easy to guess. Store in a secure location subject to regular backups.
Leave the other settings at default, then click Confirm to activate Save.
Click Save to close the window. The ZFS Encryption widget updates to reflect the changes made.
Locking and Unlocking Datasets
You can only lock and unlock an encrypted dataset if it is secured with a passphrase instead of a key file.
Before locking a dataset, verify that it is not currently in use.
Locking a Dataset
Select the encrypted dataset on the tree table, then click Lock on the Encryption widget to open the Lock Dataset dialog with the full path name for the dataset.
Use the Force unmount option only if you are certain no one is currently accessing the dataset.
Force unmount boots anyone using the dataset (e.g. someone accessing a share) so you can lock it.
Click Confirm to activate Lock, then click Lock.
You cannot use locked datasets.
Unlocking a Dataset
To unlock a dataset, go to Datasets then select the locked dataset on the tree table.
Click Unlock on the Encryption widget to open the Unlock Dataset screen.
Enter the key if key-encrypted, or the passphrase into Dataset Passphrase and click Save.
Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.
Select Force if the dataset mount path exists but is not empty. The unlock operation fails when this happens.
Using Force allows the system to rename the existing directory and file where the dataset should mount which prevents the mount operation from failing.
A confirmation dialog displays.
Click CONTINUE to confirm you want to unlock the datasets. Click CLOSE to exit and keep datasets locked.
A second confirmation dialog opens confirming the datasets unlocked.
Click CLOSE.
TrueNAS displays the dataset with the unlocked icon.
Encrypting a Zvol
Users are responsible for backing up and securing encryption keys and passphrases!
Losing the ability to decrypt data is similar to a catastrophic data loss.
To encrypt a Zvol, select a parent dataset and then create a new Zvol.
If the parent dataset is encrypted, select Inherit (encrypted) under Encryption Options.
If the parent dataset is not encrypted, disable Inherit (non-encrypted), select Encryption, and then configure the Encryption Type and related settings.
Next, go to Datasets and click on the Zvol and locate the Encryption widget.
If Encryption Type is set to Key, type an encryption key into the Key field or select Generate Key.
If using Passphrase, enter a passphrase of eight to 512 characters.Use a passphrase complex enough that is not easily guessed.
After making any changes, select Confirm, and then click Save.
Save changes to the encryption key or passphrase, update your saved passcodes and keys file, and back up the file.
Managing Encryption Credentials
There are two ways to manage the encryption credentials, with a key file or passphrase.
Creating a new encrypted pool automatically generates a new key file and prompts users to download it.
Always back up the key file to a safe and secure location.
To manually back up a root dataset key file, click Export Key on the Encryption widget.
A passphrase is a user-defined string of at least eight characters in length, and that is required to decrypt the dataset.
A passphrase is a user-defined string of eight to 512 characters that is required to decrypt the dataset.
The pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Users must enter a number greater than 100000.
Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase
TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.
Method 1: Construct JSON Manifest.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.
Method 2: Replicate Encrypted Dataset/zvol Without Properties.
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Method 3: Replicate Key Encrypted Dataset/zvol.
Go to Datasets on the system you are replicating from.
Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset.
Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
Configuring ACL Permissions
TrueNAS provides basic permissions settings and an access control list (ACL) editor to define dataset permissions.
ACL permissions control the actions users can perform on dataset contents and shares.
An Access Control List (ACL) is a set of account permissions associated with a dataset that applies to directories or files within that dataset.
TrueNAS uses ACLs to manage user interactions with shared datasets.
When you create a dataset, TrueNAS sets the ACL type based on the dataset preset, but you must configure the ACL before it becomes active.
ACL Types in TrueNAS
TrueNAS offers two ACL types: POSIX and NFSv4.
The Dataset Preset setting on the Add Dataset screen determines the type of ACL for the dataset.
Datasets created with the Generic dataset preset have the ACL type set to a POSIX (Unix) ACL.
Datasets created with the SMB dataset preset have the ACL type set to an NFSv4 ACL.
SMB shares require the more robust configurations in an NFSv4 ACL.
For most cases, a POSIX ACL is all you need.
If you want the more granular ACL controls in the NFSv4 ACL, you can create a dataset using the SMB dataset preset without creating an SMB share, or you can use the ACL Type option on the Add Dataset > Advanced Options screen to change a dataset using the Generic preset from a POSIX to NFSv4 ACL.
For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer.
How do I know what ACL Type my dataset has?
The Permissions widget for the dataset shows the dataset ACL type.
When Unix Permissions shows in the widget, the dataset has a POSIX ACL.
Alternatively, click Edit on the Dataset Details widget for the dataset to open the Edit Dataset screen, then click Advanced Options and scroll down to the ACL Type field to see the ACL type.
You can also check the ACL type while on the Edit ACL screen by clicking Use Preset, then clicking the down arrow for the Preset field in the Select a preset ACL window.
TrueNAS does not allow creating an ACL for the root dataset of a pool.
TrueNAS POSIX or NFSv4 ACL types, show different options on the ACL Editor screen.
Both the POSIX and NFSv4 ACL Editors screens allow you to:
Select a pre-configured ACL by clicking Use Preset and then selecting a Preset option
Customize the ACL by defining the owner user and group and adding ACL entries (ACEs) for individual user accounts or groups
Select a preset and customize the ACL
When using a preset and customising the ACL, select the preset first and then customize the ACL with new users or groups.
Selecting the preset after adding new ACL entries (ACEs) erases any ACEs added to the ACL, requiring you to re-enter them.
Click Save Access Control List when you are done configuring the ACL.
In most cases, the owner user and group should remain set to root, but you can change this to the primary admin user and group account with full privileges.
Add ACE items for users, groups, directories, etc., not included in preset configurations to customize access permissions to the dataset.
When adding a dataset using the SMB preset for a share or just setting up an NFSv4 ACL, TrueNAS shows the Set ACL for this dataset dialog after you save the dataset.
Click Go to ACL Manager to configure the ACL.
You must configure an ACL for the dataset.
The dataset does not have an ACL until you configure it even though you see ACL information in the Permissions widget.
This initially indicates the type of ACL created and the default basic permissions.
To access the dataset and files within it, you must set up the ACL with users and access permissions.
If you want to defer configuring the ACL, click Return to pool list, but make a note to return to the dataset to configure the ACL before attempting to use it.
Changing the ACL type affects how TrueNAS writes and reads on-disk ZFS ACLs.
When the ACL type changes from NFSv4 to POSIX, native ZFS ACLs do not convert to POSIX1e extended attributes, but ZFS uses the native ACL for access checks.
To prevent unexpected permissions behavior, you must manually set new dataset ACLs recursively after changing the ACL type.
Setting new ACLs recursively is destructive.
We suggest creating a ZFS snapshot of the dataset before changing the ACL type or modifying permissions.
While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.
Configuring POSIX ACL Permissions
The Unix Permissions Editor screen shows for datasets using the Generic dataset preset.
Accept the default root in Owner and Owner Group, or if you want to change this to a system administrator with full permissions, select the admin user name from each dropdown list, then click Apply Owner and Apply Group to make the change.
Next, select the Access levels using the Read, Write, Execute checkboxes for User, Group, Other.
Click Save to save changes and close the Unix Permissions Editor screen.
To further define the POSIX ACL, click Set ACL to open the Select a preset ACL window with two options: Select a preset ACL and Create a custom ACL.
Accept the default option Select a preset ACL to choose from the options on the Preset dropdown list.
Select Create a custom ACL to open the Edit ACL screen for a POSIX ACL with a minimal default configuration.
Selecting a preset also opens the Edit ACL screen, but with different default configurations based on the preset selected.
After selecting a preset, click Continue to close the preset window and show the Edit ACL screen for a POSIX ACL.
Next add ACL entries.
POSIX Preset Options
POSIX_OPEN - Gives the owner and group full dataset control. All other accounts can modify the dataset contents.
Use for collaborative datasets where multiple users need read/write access.
POSIX_RESTRICTED - Gives the owner full dataset control. The group can modify the dataset contents.
Others have no access. Use when you want group collaboration but need to restrict outside access.
POSIX_HOME - Gives the owner full dataset control. The group can modify the dataset contents.
All other accounts can navigate the dataset, but cannot read or modify files.
Use for private user directories where others need to traverse the path but not access the contents.
POSIX_ADMIN - Gives the admin user and builtin_administrators group full dataset control.
All other accounts can navigate the dataset but cannot read or modify files.
Use for administrative datasets that only system administrators should access.
Adding POSIX ACL Entries
The Edit ACL screen shows the ACL owner and owner group and allows you to change both, just as you can on the Unix Permissions Editor screen.
It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.
You can define the ACE entries when you first configure the POSIX ACL or change ACL entries (ACEs) and permissions for ACEs.
To edit an existing POSIX ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.
When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.
Click Add Item below the Access Control List on the left side of the screen.
If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List.
With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen.
Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset.
Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset.
This shows the Group field.
The group must be defined on the system.
In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users.
Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.
The options are Read, Modify, and/or Execute permissions.
(Optional) Select Default under Flags.
The POSIX flag for an ACL entry controls inheritance for newly created files and directories.
The default flag can only be set on directories, not on files.
When Default is selected, the ACL entry becomes a default ACL that applies to new objects created inside that directory, but it does not affect the access permissions of the current directory, just controls what new files/directories inherit.
New files inherit the default ACL as their access ACL. New directories inherit the default ACL as both their access ACL and their default ACL.
This continues down the tree of files and directories.
If not set, the ACL entry only affects access to the directory itself; new files and directories created inside the dataset do not inherit the permission.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets.
This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.
If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.
If you change your mind and want to discard the changes and revert to using a preset, click Use Preset.
This reopens the Select a Preset window where you can select a different preset to apply to the dataset.
Changing an ACL Owner or Owner Group
This applies to both POSIX and NFSv4 ACLs. The Edit ACL screen for POSIX and NFSv4 ACLs shows different configuration options, but the Owner and Owner Group settings are the same for both ACL types.
Think of the owner of the ACL as the main traffic cop granting other users access. In most cases, leave the default user set to root.
To allow a system administrator access, either change the owner and owner group to that admin user name, or add that admin user as an ACL entry (ACE) and grant it full permissions to allow it to administer the ACL and configure the dataset for other functions like an SMB share.
To change the owner and owner group:
Select the Owner user from the User dropdown list. To filter the list of users begin typing the name in the field.
Click Apply Owner to apply the change.
Next, change the Owner Group in the same manner as changing the owner.
Click Apply Group to apply the group change.
User and group options include those created manually or imported from a directory service.
To prevent errors, TrueNAS only submits changes after you select the apply options.
A common misconfiguration is not adding or removing the Execute permission from a dataset that is a parent to other child datasets.
Removing this permission results in lost access to the path.
If only changing the owner and owner group, click Save Access Control List.
If adding ACL entries, refer to the instructions for each ACL type.
To apply ACL settings to all child datasets, select Apply permissions recursively.
Change the default settings to your preferred primary account and group and select Apply permissions recursively before saving any changes.
See Edit ACL Screen for information on the ACL editor screens and setting options.
Users can grant root permissions to containers and instances through an unprivileged root account using the ACL editor in the UI or the TrueNAS API.
To ensure functionality, add an ACE for the truenas_container_unpriv_root user and assign the appropriate permissions (such as Read, Modify, and Execute).
For container environments, verify that the ACL includes an entry for truenas_container_unpriv_root with the required access to any dataset paths used by the container.
Selecting SMB in the Dataset Preset field on the Add Dataset screen applies an NFSv4 ACL type to the dataset.
You can use the SMB dataset preset and choose to not create an SMB share as the easiest way to apply an NFSv4 ACL to a dataset, or you can leave Dataset Preset set to Generic, click Advanced Options, scroll down to the ACL Type field, and select NFSv4 to apply this to the dataset.
After applying the NFSv4 ACL type to a dataset, you must configure the ACL.
If you uset the ACL Type setting on the Add Dataset > Advanced Options screen for a dataset with the Generic preset to change to an NFSv4 ACL, the Permissions widget for the dataset shows Unix Permission until you configure the NFSv4 ACL.
The Permissions widget for datasets with the SMB preset shows NFSv4 permissions, but you still need to configure the ACL permissions. The dataset does not have an ACL applied until you configure the ACL.
To edit or configure an NFSv4 ACL, select the dataset on the dataset tree table, then click Edit on the Permissions widget to open the Edit ACL screen.
You can change the owner and owner group, and/or change, add, or delete an ACE item on the Access Control List.
Either change the owner and owner group to the admin user on your system with full administration privileges or add the admin user name as an ACE item on the Access Control List.
This allows the admin user to make functional changes for the dataset and child datasets nested under it.
For example, when configuring shares and private dataset shares.
To rewrite the current ACL with a standardized preset, click Use Preset on the Edit ACL screen, which opens the Select a preset ACL window.
Select the preset option, then click Continue to apply the preset.
Presets load pre-configured permissions to match general permissions situations.
NFSv4 ACL Presets
NFS4_OPEN gives the owner and group full dataset control. All other accounts can modify the dataset contents.
NFS4_RESTRICTED gives the owner full dataset control. The group can modify the dataset contents.
NFS4_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_DOMAIN_HOME gives the owner full dataset control. The group can modify the dataset contents. All other accounts can navigate the dataset.
NFS4_ADMIN gives the admin user and builtin_administrators group full dataset control. All other accounts can navigate the dataset.
Adding NFSv4 ACL Entries
The Edit ACL screen shows the ACL owner and owner group and allows you to change both.
It also allows you to define ACL entries, such as users, groups, etc. Presets populate the Access Control List with default ACE entries.
You can define the ACE entries when you first configure the NFSv4 ACL or change ACL entries (ACEs) and permissions for ACEs when you edit an existing ACL.
To edit an existing NFSv4 ACL, go to Datasets, select the dataset on the tree table, click Edit on the Permissions widget to open the Edit ACL screen.
When adding an ACL entry (ACE), first add an item, and then assign the type and level of access given to that ACE entry.
Click Add Item below the Access Control List on the left side of the screen.
If the list includes one or more User Obj entries, TrueNAS adds a new ACE shown as a Mask on the Access Control List.
With this new item selected (highlighted), set the type of entry and the permissions level.
Click in the Who field under Access Control Entry on the right side of the screen.
Change Mask to user if adding a user to the ACL. This gives the selected user permissions to access this dataset.
Selecting User shows the User field.
Change Mask to group if granting a group of users permission to access the dataset.
This shows the Group field.
The group must be defined on the system.
In most cases, and if TrueNAS is set to create a new primary group for a new user, this group automatically created when you add a new users.
Active Directory can also provision groups and assign users to that group.
Select the user name on the User dropdown list. Or if creating a group, select the name of the group in Group.
Select the permission or access level to grant the user/group.
If Basic is selected, the Permissions dropdown list shows four options: Read, Modify, Traverse, and Full Control.
If Advanced is selected, the Permissions dropdown list shows 14 checkboxes for more granular control over the permissions granted to the selected ACE entry.
Options are: Read Data, Write Data, Append Data, Read Named Attributes, Write Named Attributes, Execute, Delete Children, Read Attributes, Write Attributes, Delete, Read ACL, Write ACL, Write Owner, and Synchronize.
(Optional) Select the ACL flags to apply the ACE item selected on the Access Control List, not to the entire ACL.
Each ACE entry can have different flags set. Flags apply to the files, directories, and subdirectories created in this dataset.
Flag options:
Basic shows the Inherit and No Inherit flags. Just as with the POSIX Default flag, this determines if files and directories in this dataset, for the ACE item selected (for example, a user item selected on the Access Control List), inherit the ACL from the dataset.
Advanced shows five flags for more granular control. Flag options are:
File Inherit - Selected by default. Limits ACL inheritance for files in the dataset for the selected ACE item.
Directory Inherit - Selected by default. Limits ACL inheritance for directories in the dataset for the selected ACE item.
No Propagate Inherit - Limits ACL inheritance to direct child directories. Files and directories created in this dataset inherit the ACL, but subdirectories cannot pass it further down the tree for the selected ACE item.
Inherit Only - Removes the ACE from permission checks but allows new files or subdirectories to inherit it for this dataset and the selected ACE item. Inherit Only is removed from these new objects.
Inherited - Selected by default. Indicates the selected ACE item inherited the ACL from the parent dataset (set by TrueNAS).
Selecting Advanced allows more granular control of file and directory permissions for a selected ACE item (such as a user) on the Access Control List.
See Debian nfs4_setfacl(1) NFSv4 ACL ENTRIES.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets.
This means the user/group has access to any child datasets nested under the selected dataset.
Add additional entries if required for your use case.
Click Save Access Control List to save changes.
If you want to save your changes as a new preset, click Save as Preset. This adds this ACL configuration to the list of ACL presets.
If you change your mind and want to discard the changes and revert to using a preset, click Use Preset.
This reopens the Select a Preset window where you can select a different preset to apply to the dataset.
Viewing Permissions
Basic ACL permissions are viewable and configurable from the Permissions widget on the Datasets screen.
Select a dataset, then scroll down to the Permissions widget to view owner and individual ACL entry permissions.
To view the Edit ACL screen, select the dataset and click Edit on the Permissions widget, or go to Sharing and click on the share widget header to open the list of shares. Select the share, then click the options icon and select Edit Filesystem ACL.
You can view permissions for any dataset, but the edit option only displays on the Permissions widget for non-root datasets.
Shares
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares. TrueNAS allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
When creating zvols for shares, avoid giving them names with capital letters or spaces since they can cause problems and failures with iSCSI and NFS shares.
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
Contents
AFP Migration: Provides information on migrating AFP shares from FreeBSD- to Linux-based TrueNAS versions.
Block Shares (iSCSI): Describes the iSCSI protocol and has tutorials for various configuration scenarios.
Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.
Adding NFS Shares: Provides instructions on adding NFS shares, starting NFS service, and accessing the share.
Multiprotocol Shares: Provides instructions on setting up SMB and NFSv4 mixed-mode shares.
Windows Shares (SMB): Provides information on SMB shares and instructions on creating a basic share and setting up various specific configurations of SMB shares.
Managing SMB Shares: Provides instructions on managing existing SMB share and dataset ACL permissions.
Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.
NVMe-oF Subsystems: Provides information on NVMe-oF subsystems and instruction on creating a subsystem and setting up enterprise configurations of subsystems.
Managing NVMe-oF Subsystems: Provides information on managing NVMe-oF subsystems, namespaces, hosts, and ports.
AFP Migration
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
Since the Apple Filing Protocol (AFP) for shares is deprecated and no longer receives updates, it is not present in TrueNAS.
However, users can sidegrade AFP configurations into TrueNAS to migrate previously-saved AFP configurations into SMB configurations.
Migrating AFP Shares
To prevent data corruption that could result from the sidegrade operation, in TrueNAS, go to Windows (SMB) Shares, select the more_vert for the share, then select Edit to open the Edit SMB screen.
Click Advanced Options and scroll down to the Other Options section.
Select Legacy AFP Compatibility to enable compatibility for AFP shares migrated to SMB shares.
Do not select this option if you want a pure SMB share with no AFP relation.
Netatalk service is not present in TrueNAS 21.06 or later.
AFP shares automatically migrate to SMB shares with the Legacy AFP Compatibility option enabled.
Do not clear the Legacy AFP Compatibility checkbox, as it impacts how data is written to and read from shares.
Any other shares created to access these paths after the migration must also have Legacy AFP Compatibility selected.
Once you have migrated to TrueNAS, you can find your migrated AFP configuration in Shares >Windows Shares (SMB) with the prefix AFP_.
To make the migrated AFP share accessible, start the SMB service.
Connecting Migrated Shares
Since AFP shares migrate to SMB, you must use SMB syntax to mount them.
On your Apple system, press +K or go to Go > Connect to Server….
Enter smb://ipaddress/mnt/pool/dataset, where:
ipaddress* is your TrueNAS IP address
pool is the name of the pool
dataset is the name of the shared dataset
Block Shares (iSCSI)
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations.
IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack.
The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack.
Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance clould suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
OSI Layer Number
OSI Layer Name
Activity as it relates to iSCSI
7
Application
An application tells the CPU that it needs to write data to non-volatile storage.
6
Presentation
OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage.
5
Session
Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU).
4
Transport
OSI encapsulates the iSCSI PDU within a TCP segment.
3
Network
OSI encapsulates the TCP segment within an IP packet.
2
Data
OSI encapsulates the IP packet within the Ethernet frame.
1
Physical
The Ethernet frame transmits as bits (zeros and ones).
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing.
Block sharing provides the benefit of block-level access to data on the TrueNAS.
iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
iSCSI Terminology
Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively.
iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network.
The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes.
It also requires that each node is given a unique iSCSI name.
To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
dash (-)
dot (.)
colon (:)
lower case characters (a…z).
Upper-case characters must be mapped to their related lower-case counterparts.
digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN.
The result is an iSCSI connection that emulates a connection to a SCSI hard disk.
Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs.
When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size.
This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU).
A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways.
Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames.
Systems administrators should also account for the impact on host CPU utilization.
Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment.
Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.
TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system.
HA storage clusters can provide multiple paths to the same storage.
For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer.
The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage.
If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage.
When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.
iSCSI Configuration Methods
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores.
This is all managed through the vCenter web interface.
TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares.
This requires creating and populating zvol block devices with data, then setting up the iSCSI Share.
TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
Contents
Adding iSCSI Block Shares: Provides instructions on setting up iSCSI block shares manually or using the wizard and starting the service.
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Adding an iSCSI Block Share
Go to Shares and click Wizard on the Block (iSCSI) Shares Targets widget.
TrueNAS offers two methods to add an iSCSI block share: the setup wizard or the manual steps using the screen tabs.
Both methods cover the same basic steps but have some differences.
The setup wizard steps you through the process.
The setup wizard ensures you configure the iSCSI share completely so you can use it immediately.
The manual process has more configuration screens than the wizard and allows you to configure the block share in any order after creating the target.
Use this process to customize your share for special use cases.
It gives you additional flexibility to build or tune a share to your exact requirements.
Before You Begin
Before adding iSCSI shares, make sure you have already created a zvol or a dataset with at least one file to share. Do not use capital letters or spaces in the names or path.
Take note of the path to the zvol or file.
Creating a share with the iSCSI Wizard
Go to Shares, then click Wizard on the iSCSI Block Share Targets widget.
Click Create New on the Target screen, then click Next or on Extent to go to next screen.
a. Enter a name using up to 64 lowercase alphanumeric and/or special characters.
Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed.
b. Select the extent type. Choose between device and file based on your use case. The screen shows different settings based on the choice.
If using a zvol, select Device in Extent Type.
You can create a new zvol or select an existing zvol as the Device.
Adding a New Device
To create a new zvol, set Device to Create New.
Browse to select the path to the parent dataset using the file browser field below Pool/Dataset.
Selecting the parent dataset activates Create Dataset.
Click Create Dataset, enter a name that does not exceed 64 lowercase alphanumeric and/or special characters, then click Create.
The mount path under Pool/Dataset populates with the path to the new zvol.
To use an existing zvol, after selecting Device in Extent Type, select Existing, then browse to select the existing zvol.
Enter a numerical value and suffix to specify the size of the zvol you are creating in Size.
Adding a File
To use a file for the extent, select File in Extent Type.
Enter or browse to select the mount point to the directory you want to use.
If a directory does not exist, after selecting the parent dataset where you want to add the directory, enter a / followed by the name to add the directory to the dataset.
Enter the size for the directory in Filesize.
Leave this set to 0 to use the actual file size. This requires that the file already exists.
Otherwise, specify the file size for the new file.
c. Select the sharing platform, then click Next or on Protocol Options to advance to the next step.
Create a portal or select an available existing portal.
Select a portal from the dropdown list or click Create New to add a new portal.
If you create a new portal, click Add to enter an IP address and netmask (CIDR) for the portal. To add another, click Add again.
Leave Initiator blank to allow all, or enter a host name to limit access to the select client.
To enter more than one host name, press Enter after each to separate each entry.
You can edit initiators from the individual screens on the iSCSI screen after adding the target.
click Save.
iSCSI Manual Setup
This procedure guides you through adding an iSCSI share using the individual configuration screens.
While the procedure places each screen in order, you can select tab screens in any order.
Click on the Block (iSCSI) Share Targets widget header to open the iSCSI screen. The Targets screen shows by default.
b. Enter a name using lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in Target Name.
Use the iqn.format for the name. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
You can enter a common name for the target in Target Alias, but this is not required.
c. (Optional) Add authorized networks.
Click Add to show the Network fields to enter a publicly accessible IP address and netmask (CIDR).
This allows communication between client computers and the iSCSI target.
Click Add for each address you want to add.
Addresses are added to the iSCSI Authorized Networks widget.
d. (Optional) Click Add to the right of Add Groups to enter portal settings.
You can add a portal from the Portals screen. Click on the Portals tab, then click Add to open the Add iSCSI Portal screen.
Select a target with a number assignment from the dropdown list in Portal ID.
Select a group from the Initiator Group ID. You can add initiator groups (client groups) from the Initiators screen.
Click on the Initiators tab, then click Add to open the Add iSCSI Initiator screen.
Select the authentication method from the dropdown list.
None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication.
To show the Mutual CHAP option, you must set the peer user and secret password.
For more information on authentication methods, see iSCSI Screens.
The Authentication Group Number dropdown list populates after configuration groups on the Add Authorized Access screen.
Edit the target after adding these groups if you want to include them.
e. Click Save.
Add extent(s). Click on the Extents tab, then click Add to open the Add iSCSI Extent screen.
b. Add a description about the extent if you want, but this is not required.
The description shows in the Target table on the Targets screen and the iSCSI Block Share Targets widget and helps identify the share use or purpose.
c. Select Enabled to enable the extent.
d. Leave Enable TCP selected. To disable it, clear the checkbox.
Select Xen initiator compat mode if required for your share.
e. Set the device type as Device or File.
Adding a Device Extent
After choosing **Device** in **Extent Type**, select the zvol or zvol snapshot from the **Device** dropdown list. The zvol must already exist to add it here.
Accept the default in **Logical Block Size** or change the size to what fits your use case.
Adding a File Extent
After choosing **File** in **Extent Type**, enter or browse to select the path to an existing file.
Enter a slash (/) followed by a file name to create a file in a dataset and append the file name to the path (/filename.ext).
Enter the file size. Enter **0** to use the actual file size of an existing file, or specify the size to apply to the new file added in **Path to the Extent**.
f. Leave Disable Physical Block Size Reporting disabled unless you want to enable this function.
g. Enter a product identification for the extent in Product ID or leave it blank to use the default iSCSI Disk used when left empty.
h. Click Save.
Add initiator groups. Click on the Initiators tab, then click Add to open the Add Initiator screen.
Leave Allow All Initiators selected, or clear and enter the host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Click Save.
Add portals. Click on the Portals tab, then click Add to open the Add Portal screen.
a. Enter a number in Group ID. This field configures different groups with different authentication profiles.
For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.
b. Select the discovery method from the dropdown list. None allows anonymous discovery. CHAP uses one-way discovery.
Mutual CHAP uses two-way discovery, but not show as an option until you add the Peer User and Peer Secret credentials.
c. Enter a username and password for CHAP authentication to the remote system. These can be the admin user account credentials.
d. Enter a peer user account and password if using Mutual CHAP authentication.
The Peer Secret cannot be the same password entered in Secret. You can select Mutual CHAP as the discovery method now.
e. Click Save.
Creating a Quick iSCSI Target
TrueNAS allows users to add iSCSI targets without adding the extent, portal, initiators, etc. You can create the target and add the rest later.
Go to Shares and click the Block (iSCSI) Shares Targets widget header to open the iSCSI screen with the Targets tab selected by default.
Click Add to open the Add iSCSI Target screen.
Enter a name in Target Name. Use lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in the iqn.format.
See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
(Optional) Enter a user-friendly name in Target Alias.
Add authorized networks. Click Add to show the Network fields where you can enter an IP address and netmask (CIDR).
This allows communication between client computers and the iSCSI target. Click Add for each address you want to add.
Addresses are added to the authorized networks list.
Click Add to the right of Add Groups to enter portal settings.
Portal and group settings can be added later or on the Add Portal screen, and initiator groups can be added by editing the target or using the Add Initiators screen.
Select a target with a number assignment from the dropdown list in Portal ID.
Select the authentication method from the dropdown list.
None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication.
For more information on authentication methods, see iSCSI Screens.
Select a portal ID from the Initiator Group ID dropdown list.
The Authentication Group Number dropdown list is populated after configuration groups on the Add Authorized Access screen.
Edit the target after adding these groups if you want to include them.
Click Save.
Starting the iSCSI Service
After adding a share with the iSCSI wizard or manual entry screens, the system shows a dialog prompting you to start or restart the service.
You can also start the service by clicking on the more_vert on the Block (iSCSI) Shares Targets widget and selecting Turn On Service.
You can go to System > Services, locate iSCSI on the service list, and click the Start Service button to start the service.
Setting Up Fibre Channel
The Fibre Channel feature is available to Enterprise-licensed High Availability (HA) and non-HA systems.
Any Enterprise system, equipped with the required fibre channel hardware can implement this feature.
This article provides instructions for VMware VCenter ESXi.
If you are using a different platform for your block share backups, use the documentation for that platform for alternative instructions for the ESXi process documented in this tutorial.
.
Before You Begin
When setting up iSCSI fibre channel for the first time:
(Optional) Create a zvol for each fibre channel port with a network interface associated with it.
The wizard provides an option to create a dataset on the Extents screen when adding the device.
Selecting this option creates a dataset for organizational purposes and a zvol of the same name for block storage.
Configuring Fibre Channel - First-Time Install
We recommend using the iSCSI wizard to create your target, create the extents, and set up fibre channel ports.
If the system is a High Availability (HA) system, turn on ALUA.
Click on the iSCSI widget header to open the Sharing iSCSI screens. Click on Global Target Configuration. Scroll down and select Asynchronous Logic Unit Access (ALUA), then click Save.
b. Select Device in Extent Type, then select Create New on the Device dropdown list.
When selecting Create New, the Pool/Dataset and /mnt fields display.
Navigate through the pool and datasets to select the zvol and populate the /mnt field with the path.
Clicking Create Dataset allows you to add a dataset where the /mnt path indicates. TrueNAS creates the dataset for organizational purposes and a zvol of the same name for block storage.
c. Enter a value in Size.
d. Select the platform option that matches your use case and for this iSCSI share on the Sharing Platform dropdown list.
For example, if using the VMware ESXi platform for your block storage, select VMware: Extent block size 512b, TCP enabled, no Xen compat mode, SSD speed.
e. Click Next to show the Protocol Options screen.
Select the protocol option for your use case.
When installing iSCSI fibre channel ports the first time, select Create new virtual port.
Start the iSCSI service when prompted.
If you did not stop the iSCSI service, restart it by clicking the more_vert button, stop the service, and when the status indicates it is stopped, start it.
Log into your block storage backup platform (i.e., VCenter ESXi) and configure your adaptors, devices, and datastores.
Refer to VMWare or documentation for the platform used for instructions on completing the configuration.
Using an iSCSI Share
Connecting to and using an iSCSI share can differ between operating systems.
This article provides instructions on setting up a Linux and Windows system to use the TrueNAS iSCSI block share.
Using Linux iSCSI Utilities and Service
In this section, you start the iSCSI service, log in to the share, and obtain the configured basename and target. You also partition the iSCSI disk, make a file system for the share, mount it, and share data.
Click here for more information
Before you begin, open the command line and ensure you have installed the open-iscsi utility.
To install the utility on an Ubuntu/Debian distribution, enter command sudo apt update && sudo apt install open-iscsi.
After the installation completes, ensure the iscsid service is running using the sudo service iscsid start command.
First, with the iscsid service started, run the iscsiadm command with the discovery arguments and get the necessary information to connect to the share.
Next, discover and log into the iSCSI share.
Run the command sudo iscsiadm \--mode discovery \--type sendtargets \--portal {IPADDRESS}.
The output provides the basename and target name that TrueNAS configured.
Alternatively, enter sudo iscsiadm -m discovery -t st -p {IPADDRESS} to get the same output.
Note the basename and target name given in the output. You need them to log in to the iSCSI share.
When a Portal Discovery Authentication Method is CHAP, add the three following lines to /etc/iscsi/iscsid.conf.
discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = user
discovery.sendtargets.auth.password = secret
The user for discovery.sendtargets.auth.username is set in the Authorized Access used by the iSCSI share Portal.
Likewise, the password to use for discovery.sendtargets.auth.password is the Authorized Access secret.
Without those lines, the iscsiadm does not discover the portal with the CHAP authentication method.
Enter comand sudo iscsiadm \--mode node \--targetname {BASENAME}:{TARGETNAME} \--portal {IPADDRESS} \--login,
where {BASENAME} and {TARGETNAME} is the discovery command information.
Now you partition an iSCSI disk.
When the iSCSI share login succeeds, the device shared through iSCSI shows on the Linux system as an iSCSI Disk.
To view a list of connected disks in Linux, enter command sudo fdisk -l.
Because the connected iSCSI disk is raw, you must partition it.
Identify the iSCSI device in the list and enter sudo fdisk {/PATH/TO/iSCSIDEVICE}.
Use the fdisk command defaults when partitioning the disk.
Remember to type w when finished partitioning the disk.
The w command tells fdisk to save any changes before quitting.
After creating the partition on the iSCSI disk, a partition slice displays on the device name.
For example, /dev/sdb1.
Enter fdisk -l to see the new partition slice.
Next, make a file system on the iSCSI disk.
Finally, use mkfs to make a file system on the new partition slice.
To create the default file system (ext2), enter sudo mkfs {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.
Mount the iSCSI device and share the data.
Enter sudo mount {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.
For example, sudo mount /dev/sdb1 /mnt mounts the iSCSI device /dev/sdb1 to file /mnt.
Using the iSCSI Share with Windows
This section provides instructions on setting up Windows iSCSI Initiator Client to work with TrueNAS iSCSI shares.
Click here for more information
To access the data on the iSCSI share, clients need to use iSCSI Initiator software. An iSCSI Initiator client is pre-installed in Windows 7 to 10 Pro, and Windows Server 2008, 2012, and 2019. Windows Professional Edition is usually required.
First, click the Start Menu and search for the iSCSI Initiator application.
Next, go to the Configuration tab and click Change to replace the iSCSI initiator with the name created earlier. Click OK.
Next, switch to the Discovery Tab, click Discover Portal, and type in the TrueNAS IP address.
If TrueNAS changed the port number from the default 3260, enter the new port number.
If you set up CHAP when creating the iSCSI share, click Advanced…, set Enable CHAP log on, and enter the initiator name and the same target/secret set earlier in TrueNAS.
Click OK.
Go to the Targets tab, highlight the iSCSI target, and click Connect.
After Windows connects to the iSCSI target, you can partition the drive.
Search for and open the Disk Management app.
The current state of your drive should be unallocated. Right-click the drive and click New Simple Volume….
Complete the wizard to format the drive and assign a drive letter and name.
Finally, go to This PC or My Computer in File Explorer. The new iSCSI volume should display under the list of drives. You should now be able to add, delete, and modify files and folders on your iSCSI drive.
Increasing iSCSI Available Storage
Expanding LUNs
TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage in an iSCSI share.
Zvol LUNs
To expand a Zvol LUN, go to Datasets and click the Zvol LUN name. The Zvol Details widget displays. Click the Edit button.
TrueNAS prevents data loss by not allowing users to reduce the Zvol size.
TrueNAS also does not allow users to increase the Zvol size past 80% of the pool size.
File LUNs
Go to Shares and click Configure in the Block (iSCSI) Shares Targets screen, then select the Extents tab.
Enter a new size in Filesize.
Enter the new value as an integer that is one or more multiples of the logical block size (default 512) larger than the current file size.
Click Save.
Adding NFS Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
About UNIX (NFS) Shares
Creating a Network File System (NFS) share on TrueNAS makes a lot of data available for anyone with share access.
Depending on the share configuration, you can restrict users to read or write privileges.
NFS treats each dataset as its own file system. When creating the NFS share on the server, the specified dataset is the location that the client accesses.
If you choose a parent dataset as the NFS file share location, the client cannot access any nested or child datasets beneath the parent.
If you need to create shares that include child datasets, SMB sharing is an option. Note that Windows NFS Client versions currently support only NFSv2 and NFSv3.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Creating an NFS Share and Dataset
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
You have the option to create the share and a dataset at the same time from either the Add Dataset or Add NFS screens.
If creating a dataset and share from the Add Dataset screen, we recommend creating a new dataset with the Dataset Preset set to Generic for the new NFS share.
Or you can set it to Multiprotocol and only select the NFS share type.
Creating a Dataset Using Add Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
To create the share and dataset from the Add NFS Share screen:
Go to Shares > Unix (NFS) Shares and click Add to open the Add NFS Share configuration screen.
Enter the path or use the arrow_right icon to the left of /mnt to locate the dataset and populate the path.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Create Dataset, enter a name for the dataset, and click Create.
The system creates the dataset optimized for an NFS share, populates the share Name, and updates the Path with the dataset name.
The dataset name is the share name.
Enter text to help identify the share in Description.
Enable Service turns the NFS service on and changes the toolbar status to Running.
If you wish to create the share without immediately enabling it, select Cancel.
Adding NFS Share Networks and Hosts
If you want to enter allowed networks, click Add to the right of Networks.
Enter an IP address in Network and select the mask CIDR notation.
Click Add for each network address and CIDR you want to define as an authorized network.
Defining an authorized network restricts access to all other networks. Leave empty to allow all networks.
Click Add to the right of Hosts if you want to enter allowed systems.
Enter a host name or IP address to allow that system access to the NFS share.
Click Add for each allowed system you want to define.
Defining authorized systems restricts access to all other systems.
Press the X to delete the field and allow all systems access to the share.
Adjusting Access Permissions
To tune the NFS share access permissions or define authorized networks, click Advanced Options.
Select Read-Only to prohibit writing to the share.
To map user permissions to the root user, enter a string or select the user from the Maproot User dropdown list.
To map the user permissions to all clients, enter a string or select the user from the Mapall User dropdown list.
To map group permissions to the root user, enter a string or select the group from the Maproot Group dropdown list.
To map the group permissions to all clients, enter a string or select the group from the Mapall Group dropdown list.
Select an option from the Security dropdown. If you select KRB5 security, you can use a Kerberos ticket. Otherwise, everything is based on IDs.
Security Types
Setting
Description
SYS
Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5
Uses Kerberos for authentication.
KRB5I
Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P
Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.
Editing an NFS Share
To edit an existing NFS share, go to Shares > Unix (NFS) Shares and click the share you want to edit.
The Edit NFS screen settings are identical to the share creation options, but you cannot create a new dataset.
Starting the NFS Service
To begin sharing, click the more_vert on the toolbar and select Turn On Service. Turn Off Service displays if NFS is on. Turn On Service displays if NFS is off.
Or you can go to System > Services, locate NFS, and click the Start Service button to start the service.
Toggle Start Automatically on if you want NFS to activate when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
Configuring the NFS Service
You can configure the NFS service from either the System > Services screen or the Shares > Unix (NFS) Shares widget.
To configure NFS service settings from the Services screen, click edit on the System > Services screen to open the NFS service screen.
To configure NFS service settings from the Shares > Unix (NFS) Shares widget, click the Config Service from the more_vert dropdown menu on the widget header to open the NFS service screen.
Unless you need specific settings, we recommend using the default NFS settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
TrueNAS Enterprise
NFS over RDMA
TrueNAS Enterprise customers utilizing NFS shares with compatible hardware can enable NFS over RDMA to improve NFS performance and efficiency.
Remote Direct Memory Access (RDMA) lets a client system transfer data directly from server memory to its own, improving speed, reducing latency, and lowering CPU usage.
NFS over RDMA support requires an active Enterprise license and RDMA-capable network interface cards (NICs) in the TrueNAS host and client systems.
Interested customers should contact Enterprise Support for assistance.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Although you can connect to an NFS share with various operating systems, we recommend using a Linux/Unix OS.
First, download the nfs-common kernel module.
You can do this using the installed distribution package manager.
For example, on Ubuntu/Debian, entering the command sudo apt-get install nfs-common in the terminal.
After installing the module, connect to an NFS share by entering sudo mount -t nfs {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}.
Where {IPaddressOfTrueNASsystem} is the remote TrueNAS system IP address that contains the NFS share, {path/to/nfsShare} is the path to the NFS share on the TrueNAS system, and {localMountPoint} is a local directory on the host system configured for the mounted NFS share.
For example, sudo mount -t nfs 10.239.15.110:/mnt/Pool1/NFS_Share /mnt mounts the NFS share NFS_Share to the local directory /mnt.
You can also use the Linux nconnect function to let your NFS mount support multiple TCP connections.
To enable Linux nconnect, enter sudo mount -t nfs -o rw,nconnect=16 {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}.
Where {IPaddressOfTrueNASsystem}, {path/to/nfsShare}, and {localMountPoint} are the same ones you used when connecting to the share.
For example, sudo mount -t nfs -o rw,nconnect=16 10.239.15.110:/mnt/Pool1/NFS_Share /mnt.
By default, anyone who connects to the NFS share only has read permission.
To change the default permissions, edit the share, open the Advanced Options, and change the Access settings.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
You must have ESXI 6.7 or later for read/write functionality with NFSv4 shares.
Multiprotocol Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS 25.04.0: Time Machine shares are incompatible with multiprotocol (SMB/NFS) shares. TrueNAS automatically disables SMB2/3 lease support and AAPL extensions globally when multiprotocol shares are configured, preventing Time Machine functionality.
TrueNAS 25.04.1 and later: This limitation is removed. Multiprotocol shares now use per-share oplock management instead of global oplock disabling, allowing Time Machine and Final Cut Pro Storage Share shares to coexist with multiprotocol shares on the same system. SMB leases are permitted globally, with oplocks disabled only at the multiprotocol share level.
About Multi-Protocol Shares
A multi-protocol or mixed-mode NFS and SMB share supports both NFS and SMB protocols for sharing data.
Multi-protocol shares allow clients to use either protocol to access the same data.
This can be useful in environments with a mix of Windows systems and Unix-like systems, especially if some clients lack an SMB client.
Carefully consider your environment and access requirements before configuring a multi-protocol share.
For many applications, a single protocol SMB share provides a better user experience and ease of administration.
Linux clients can access SMB shares using mount.cifs.
To ensure security and data integrity when using multi-protocol sharing, it is important to properly configure permissions and access controls.
To maximize security on the NFS side of the multi-protocol share, we recommend using NFSv4 and Active Directory(AD) for Kerberos authentication.
It is also important that NFS clients preserve extended attributes when copying files, or SMB metadata could be discarded in the copy.
Multi-protocol shares are not compatible with APPL extensions such as Time Machine that rely on SMB3/3 lease support, which is no longer available in multi-protocol shares.
Choosing to configure a multi-protocol share disables options to enable AAPL extensions globally.
First Steps
Before adding a multi-protocol SMB and NFS share to your system:
Configure and start the SMB and NFS services.
Configure the NFS service to require Kerberos authentication.
Join the TrueNAS server to an existing Active Directory domain.
Configure a container, Kerberos admin, and user accounts in AD.
Before joining AD and creating a dataset for the share, start both the SMB and NFS services and configure the NFS service for Kerberos authentication.
Configure the NFS service before joining AD for a simpler Kerberos credential creation.
To configure services, you can use the Shares screen Config Service option on both the Windows (SMB) Share and the UNIX (NFS) Shares widgets, or go to System > Services and select the Edit option for the SMB and NFS services.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default SMB service settings.
After configuring the SMB and NFS share services, start the services.
From the Shares screen, click on the Windows (SMB) Sharesmore_vert to show the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
After adding a share, use the toggle to enable or disable the service for that share.
To enable the service from the System > Services screen, click the Start Service button to start the service and toggle Start Automatically on if you want the service to activate when TrueNAS boots.
Configuring and Starting the NFS Service
Open the NFS service screen, then select only NFSv4 on the Enabled Protocols dropdown list.
For security hardening, we recommend disabling the NFSv3 protocol.
Select Require Kerberos for NFSv4 to enable using a Kerberos ticket.
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 the NFS service is enabled with Require Kerberos for NFSv4 selected before joining Active Directory.
Click Save, then start the NFS service.
Go to the Shares screen, click on the Unix (NFS) Sharesmore_vert to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
Each NFS share on the list also has a toggle to enable or disable the service for that share.
To enable the service from the System > Services screen, click the Start Service icon to start the service and toggle Start Automatically on to start the service when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
Joining Active Directory
Multi-protocol SMB and NFS shares greatly simplify data access for clients running a range of operating systems.
They also require careful attention to security complexities not present in standard SMB shares.
NFS shares do not respect permissions set in the SMB share ACL.
Protect the NFS export with proper authentication and authorization controls to prevent unauthorized access by NFS clients.
We recommend using Active Directory to enable Kerberos security for the NFS share.
Configure a container (group or organizational unit), Kerberos admin, and user accounts in AD.
Creating a Multi-Protocol Share
You can create a share and a dataset from either the Add Dataset or Add SMB screen.
The multi-protocol share type is mutually exclusive with AAPL extension support, like Time Machine.
These extensions require the SMB2/3 lease support, which is no longer available in multi-protocol shares.
Therefore, the Multi-Protocol Share option does not include a Time Machine option. Selecting other Apple protocol options displays warning messages.
Multi-protocol shares can impact the performance of all SMB shares.
Using the Add Dataset Screen
TrueNAS allows you to create the dataset and add a multi-protocol (SMB and NFS) share using the Add Dataset screen.
This is the recommended method when creating a multi-protocol share.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
Select the parent dataset where you want to add the multi-protocol dataset, then click Add Dataset.
Enter a name for the dataset.
Select Multiprotocol from the Dataset Preset dropdown.
The share configuration options display with Create NFS Share and Create SMB Share preselected.
The dataset name populates the SMB Name field and becomes the name of the SMB and NFS shares.
(Optional) Click Advanced Options to customize other dataset settings such as quotas, compression level, encryption, and case sensitivity.
See Creating Datasets for more information on adding and customizing datasets.
Click Save.
TrueNAS creates the dataset and the SMB and NFS shares.
TrueNAS sets the same share presets as the Multi-Protocol Share option in Purpose on the Advanced Options for the Add SMB screen.
To configure other share settings, go to Shares, select the share, click on the more_vert icon, and select Edit to open the Edit SMB screen, and click Advanced Options to modify the settings.
After adding the dataset, edit the dataset ACL.
Using the Add SMB Screen
Adding a multi-protocol share from the Add SMB screen creates the SMB share and the dataset, but you must also use the Add NFS screen to add the NFS share.
To create a share and a dataset from the Add SBM share screen, go to Shares, and click Add on the Windows (SMB) Shares widget to open the Add SMB screen.
Enter or browse to select the parent dataset where you want to add the share dataset, then click Create Dataset.
Enter a name for the dataset/share, then click Create Dataset. The Path field populates with the path to the dataset, and the Name field populates with the dataset/share name. Both the dataset and the share have the same name.
Select Multi-Protocol Shares on the Purpose dropdown list.
This applies the pre-determined Other Options selected on the Advanced Options screen.
Click Advanced Options to modify any settings you want to use. Multi-mode shares cannot use APPL extension settings like Time Machine.
(Optional) Enter a Description to help explain the share purpose.
Click Save.
Configure the ACL when prompted.
Click Add on the UNIX (NFS) Shares widget to open the Add NFS screen.
Set the path to the same dataset created for the SMB share.
Customize the NFS share to suit your use case, and click Save.
Restart the NFS and SMB services when prompted.
You can modify share settings after creating it.
Editing the NFS Share
After creating the multi-protocol share on the Add Dataset screen, if you want to customize the NFS share further, go to Shares and edit the NFS share.
Select the new share listed on Unix (NFS) Shares widget, click on the more_vert icon and then click Edit.
The Edit NFS screen opens with the Basic Options settings showing.
Enable Kerberos security. Click Advanced Options.
Select KRB5 from the Security dropdown to enable the Kerberos ticket generated when you joined Active Directory.
If needed, select Read-Only to prohibit writing to the share.
Click Save.
Start or restart the service when prompted.
Adjusting the Dataset ACL
After joining AD and creating a multi-protocol dataset and the SMB and NFS shares, adjust the dataset permission or use the SMB file system permissions to match the container and users configured in AD.
You can modify dataset permissions from the Shares screen using securityEdit Filesystem ACL to open the Edit ACL screen for the selected share (SMB and NFS).
Select the share row on the widget, then click the edit icon to modify permissions for the share dataset.
Note: editing the dataset permissions sets permissions for the SMB and NFS.
Using the Edit Filesystem ACL only edits permissions for the SMB share in the multi-protocol share configuration.
Or go to Datasets, select the dataset row created for the multi-protocol share on the Datasets table, then scroll down to the Permissions widget for the dataset.
Click Edit to open the Edit ACL screen.
Check the Access Control List to see if the AD group you created is on the list and has the correct permissions.
If not, add this Access Control Entry (ACE) item on the Edit ACL screen for the multi-protocol dataset (or each share).
Enter Group in the Who field or use the dropdown list to select Group.
Type or select the appropriate group in the Group field.
Verify Full Control displays in Permissions. If not, select it from the dropdown list.
Click Save Access Control List to add the ACE item or save changes.
See Permissions for more information on editing dataset permissions.
After setting the dataset permission, connect to the share.
Connecting to a Multi-Protocol Share
After creating and configuring the shares, connect to the multi-protocol share using either SMB or NFS protocols from a variety of client operating systems, including Windows, Apple, FreeBSD, and Linux/Unix systems.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
About Windows (SMB) Shares
SMB (also known as CIFS) is the native file-sharing system in Windows.
SMB shares can connect to most operating systems, including Windows, Mac OS, and Linux.
TrueNAS can use SMB to share files among single or multiple users or devices.
SMB supports a wide range of permissions, security settings, and advanced permissions (ACLs) on Windows and other systems, as well as Windows Alternate Streams and Extended Metadata.
SMB is suitable for managing and administering large or small pools of data.
TrueNAS uses Samba to provide SMB services.
The SMB protocol has multiple versions. During the SMB session negotiation, a typical SMB client can negotiate the highest supported SMB protocol.
Industry-wide, SMB1 protocol (sometimes referred to as NT1) use is deprecated for security reasons.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
However, most SMB clients support SMB 2 or 3 protocols even when they are not the default.
Legacy SMB clients rely on NetBIOS name resolution to discover SMB servers on a network.
TrueNAS disables the NetBIOS name server (nmbd) by default. Enable it on the Network > Global Settings screen if this functionality is required.
Mac OS clients use mDNS to discover SMB servers present on the network. TrueNAS enables the mDNS server (avahi) by default.
Windows clients use WS-Discovery to discover the presence of an SMB server.
You can disable network discovery by default depending on the Windows client version.
Discoverability through broadcast protocols is a convenience feature and is not required to access an SMB server.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
How do I add an SMB Share?
Verify your Active Directory connections are working and error-free before adding an SMB share.
When an SMB share is configured but not working or is in an error state, AD cannot bind, and TrueNAS cannot start the SMB service.
Creating an SMB share on your system requires adding the share and then getting it working.
You can manually add user accounts or use directory services like Active Directory or LDAP to provide additional user accounts.
If setting up an external SMB share, we recommend using Active Directory or LDAP, or at a minimum, synchronizing the user accounts between systems.
You can use the Add SMB screen to create a basic SMB share or a more specific share type with specific feature requirements using the Advanced Options settings before saving the share.
The Add Dataset and the Add SMB share screens allow TrueNAS to create a dataset and SMB share from the same screen.
Use either option to create a basic SMB share.
When creating an SMB share that requires customization or is intended for a specific purpose, such as working with Veeam Backup & Restore immutability or a repository for block or fast cloning (requires an Enterprise license), use the Add SMB screen Purpose presets to create the share and dataset for these special SMB shares.
For more information on Veeam SMB shares, refer to the Solutions > IntegrationsVeeam and Veeam Immutability guides.
When setting up multi-protocol (SMB and NFS) shares, refer to the Multiprotocol Shares tutorial for configuration instructions.
This article describes adding a dataset while adding the share using the Add SMB screen.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled.
You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To add or edit users, go to Credentials > Users, then add or edit an existing user to create the SMB share user(s).
Click Add to create a new user or as many new user accounts as needed.
Joining TrueNAS to Active Directory creates the user accounts.
Enter the values in each required field, verify SMB Access is selected, then click Save.
For more information on the fields and adding users, see Creating User Accounts.
By default, all new users are members of a built-in group called builtin_users.
You can use a group to grant access to all users on the server or add more groups to fine-tune permissions for large numbers of users.
Why not just allow anonymous access to the share?
Anonymous or guest access to the share is possible, but allowing guest access can create a security vulnerability, so it is not recommended for Enterprise customers or systems with more than one SMB share administrator account.
Using a guest account increases the likelihood of unauthorized users gaining access to your data in the SMB share.
Major SMB client vendors are deprecating guest users, partly because signing and encryption are impossible for guest sessions.What about LDAP users?
Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel).
Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.
Adding an SMB Share and Dataset
You can create an SMB share while creating a dataset on the Add Dataset screen or create a dataset and the share using the Add SMB share screen.
This article covers adding the dataset using the Add SMB share screen.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
What are ZFS dataset setting defaults?
TrueNAS creates the ZFS dataset with these settings:
ACL Mode set to Restricted
The ACL Type influences the ACL Mode setting. When ACL Type is set to Inherit, you cannot change the ACL Mode setting.
When ACL Type is set to NFSv4, you can change the ACL Mode to Restricted.
For datasets with NFSv4 ACL type, SMB clients automatically use access-based enumeration.
This means directory listings over SMB only include files and directories for which the client has read permissions.
This behavior is enabled by default and matches FreeBSD behavior.
Case Sensitivity set to Insensitive
TrueNAS also applies a default access control list to the dataset.
This default ACL is restrictive and only grants access to the dataset owner and group.
You can modify the ACL later according to your use case.
If you want to organize the SMB share dataset under a parent dataset (for example, under smb-shares), create that parent dataset so you can select it as the parent in step 2 below.
Alternatively, you can create the parent and SMB share dataset using the Create Dataset option associated with the file browser in the Add SMB screen by making the create dataset instructions a two-=step process.
To create a basic Windows SMB share and a dataset, go to Shares, then click Add on the Windows Shares (SMB) widget to open the Add Share screen.
Enter or browse to select the SMB share mount path (parent dataset where you want to add a dataset for this share).
You cannot use a root dataset for a share. When the dataset selected has an existing ACL, a warning dialog shows. Click Continue.
Click on the dataset under which you want to add the SMB share dataset.
The blank Path field populates with the path selected in the file browser field directly below it.
The Path file browser field is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Create Dataset.
Enter a name for the dataset in the Create Dataset dialog, then click Create.
The system creates the new dataset and populates the Name field with the dataset name, which becomes the share
To make the new dataset the parent for an SMB share, select the just-added dataset, then click Create Dataset again to add the child dataset for the share.
The path forms part of the share pathname when SMB clients perform an SMB tree connect.
Because of how the SMB protocol uses the name, it must be less than or equal to 80 characters.
Do not use invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6.
If you change the name, follow the naming conventions for:
Select a share type on the Purpose dropdown list.
The share type selected locks or unlocks the pre-determined Advanced Options settings for the share.
Select Default Share to create a basic SMB share with the Browsable to Network Clients option preselected.
This determines whether this share name is included when browsing shares.
Select Private Datasets Share to create an alternative to home shares.
See Setting Up SMB Home Shares for more information on replacing this legacy feature with private SMB shares and datasets.
Select Multi-protocol Share to create a multi-protocol share (NFSv4/SMB). Set this if the path is shared through NFS, FTP, or used by containers or apps.
Note: This setting can reduce SMB share performance as it turns off some SMB features for safer interoperability with external processes.
See Setting Up SMB Multichannel for more information on creating multi-protocol shares.
Select Time Machine Share to create a Time Machine share. The SMB share is presented to Mac OS clients as a Time Machine target.
See Adding a Basic Time Machine SMB Share for more information on creating and using Time Machine shares.
Select Final Cut Pro Storage Share (available in TrueNAS 25.10.1 and later) to create a share optimized for Final Cut Pro workflows.
The SMB share is configured with Apple-style character encoding and requires Apple SMB2/3 protocol extensions for compatibility with Final Cut Pro.
See Setting Up Final Cut Pro SMB Shares for more information on creating shares for Final Cut Pro workflows.
Select External Share to create an external share. Enter the full domain name or IP address and the share name as 192.168.0.200\SHARE in Remote Path.
Select Time Locked Share to create a share that makes files read-only after the grace period you specify expires.
This setting does not work if the path is accessed locally or if another SMB share with the Time Locked Share purpose uses the same path.
Warning: This setting might not meet regulatory requirements for write-once storage.
(Optional) Enter a short description or explanation of the share purpose or use in Description.
This shows on both the SMB widget and Share > SMB screen to help explain how the share is used.
For example, if for an external share, enter external share in the field.
The description entered shows in the SMB table on the SMB screen and the Windows (SMB) Share widget.
Select Enabled to allow sharing of this path when the SMB service is activated.
Leave the checkbox cleared to disable the share without deleting the configuration.
(Optional) Click Advanced Options to show additional configuration settings.
Click to configure other advanced settings such as access, audit logging, or settings specific to the type of share selected in Purpose.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
Start or restart the SMB service when prompted.
Configuring Advanced Options
A basic SMB share does not need to use the Advanced Options settings. Click Advanced Options to finish customizing the SMB share settings.
Guest access adds security vulnerabilities and should be avoided.
Guest access allows users to connect to an SMB share without providing credentials.
In TrueNAS SCALE 25.10 and later, this feature is only available for shares with the Legacy Share preset (shares that used No Preset in releases before 25.10).
To enable guest access on a Legacy Share:
Go to Shares and click on the share name to expand the share widget, then click Edit.
Click Advanced Options and scroll down to the Access settings.
Select the Allow Guest Access checkbox.
Click Save.
The privileges granted are the same as those for a guest account.
Windows 10 version 1709 and later, and Windows Server 2019 and later disable guest access by default as a security measure.
Windows clients require additional configuration to connect to shares with guest access enabled.
To enable guest access on Windows clients, modify Windows registry settings or Group Policy to allow insecure guest logons.
See Microsoft documentation for configuration details.
For new shares:
New shares created in TrueNAS SCALE 25.10 and later cannot select the Legacy Share preset, and therefore cannot use guest access.
Guest access has been limited to legacy shares due to security concerns and client-side deprecation:
Windows 10 version 1709 and Windows Server 2019 and later disable guest access by default
Major SMB client vendors are deprecating guest users
Guest sessions cannot use signing and encryption features
Client-specific behavior:
Mac OS clients - Prevent automatic connection as guest account.
Users must explicitly select Connect As: Guest.
See the Apple documentation for more details.
Windows clients - Require registry or Group Policy modifications to enable insecure guest authentication
Alternative approaches:
Instead of guest access, consider these secure alternatives:
Create a dedicated guest user account with limited permissions
Use share ACL to restrict the guest user to read-only access
To prohibit writes to the share, select Export Read-Only.
Select Access Based Share Enumeration to restrict share visibility for users with read or write access to the share.
This setting applies to datasets with a POSIX ACL type.
For datasets with NFSv4 ACL type, access-based enumeration is automatically enabled and does not allow disabling.
See the smb.conf manual page.
Host Allow and Host Deny
Hosts Allow and Hosts Deny settings are available for all share presets except External Share.
Use the Host Allow and Host Deny options to allow or deny specific host names and IP addresses.
Use the Hosts Allow field to enter a list of allowed IP addresses.
Separate entries by pressing Enter.
Entering values in the Host Allow restricts access to only the addresses entered into this list!
This list can break UI access for all other IP or host name entries.
You can find a more detailed description with examples here.
Use the Hosts Deny field to enter a list of denied host names or IP addresses. Separate entries by pressing Enter.
Hosts Allow and Hosts Deny work together to produce different situations:
Leaving both Hosts Allow and Hosts Deny free of entries allows any host to access the SMB share.
Adding entries to the Hosts Allow list but not the Hosts Deny list allows only the hosts on the Hosts Allow list to access the share.
Adding entries to the Hosts Deny list but not the Hosts Allow list allows all hosts not on the Hosts Deny list to access the share.
Adding entries to both a Hosts Allow and Hosts Deny list allows all hosts on the Hosts Allow list to access the share and allows hosts not on the Hosts Allow or Hosts Deny list to access the share.
Legacy Share Preset (Upgraded Shares Only)
What is a legacy share?
When you upgrade to TrueNAS SCALE 25.10 from an earlier release, existing shares that used the No Preset option are automatically migrated to the Legacy Share preset.
This preset provides access to configuration options that are no longer available for new shares.
Why can I not create a new legacy share?
The Add SMB screen does not include Legacy Share as an option. This preset only appears in the Edit SMB screen for shares created before 25.10.
TrueNAS removed these options from new shares due to:
Security concerns (guest access, recycle bin)
Better alternatives available (ZFS snapshots instead of recycle bin)
Client-side deprecation (guest access no longer supported by major vendors)
Legacy share options:
Legacy shares provide access to additional settings not available in modern presets.
AFP shares are deprecated and not available in TrueNAS.
To customize your SMB share to work with a migrated AFP share or with your Mac OS, use the share option on the Purpose dropdown list and the Advanced Options settings provided for these use cases:
Use Apple-style Character Encoding, listed under Other Options for all share types except Time Machine Share and External Share, converts NTFS illegal characters like the Mac OS SMB clients do.
By default, Samba uses a hashing algorithm for NTFS illegal characters.
Private SMB Datasets and Shares
Used to set up an alternative to the legacy home shares function, select Private Dataset Share on the Purpose dropdown list, and customize settings listed under Other Options.
This allows you to add private datasets and shares for individual users, and is an alternate way to create home shares for them.
See Setting Up SMB Home Shares for more information.
SMB Audit Logging
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Tuning ACLs for SMB Shares
There are two levels to set SMB share permissions: at the share or for the dataset associated with the share.
See Managing SMB Shares for more information on these options.
See Permissions for more information on dataset permissions.
Tuning the Share ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses.
The permissions apply at the SMB share level for the selected share.
They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on shareEdit Share ACL to open the Edit Share ACL screen to modify permissions at the share level.
Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
Tuning the Dataset (Filesystem) Permissions
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option.
This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level.
To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, click on the more_vert dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share.
You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group.
Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default.
Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry.
Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group.
Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
Changing the built-in-user Group Permissions
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen.
Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
Adding a New Share Group
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Groups, click Add and create the new group.
Go to Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group.
Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL.
Add an ACE entry for the new group, and select Traverse.
Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
Using the Traverse Permission
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
Starting the SMB Service
To connect to an SMB share, start the SMB service.
After adding a new share, TrueNAS prompts you to start or restart the SMB service.
You can also start the service from the Windows (SMB) Share widget or on the System > Services screen from the SMB service row.
Starting the Service Using the Windows SMB Share
From the Sharing screen, click on the Windows (SMB) Sharesmore_vert to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
Each SMB share on the list also has a toggle to enable or disable the service for that share.
Starting the Service Using System Settings
To make SMB share available on the network, go to System > Services and click the SMBStart Service button to start the service.
Toggle Start Automatically on if you want the service to activate when TrueNAS boots.
Configuring the SMB Service
Configure the SMB service by clicking Config Service from the more_vert dropdown menu on the Windows (SMB) Shares widget header or by clicking edit on the Services screen.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.
Mounting the SMB Share
The instructions in this section cover mounting the SMB share on a system with the following operating systems.
Mounting on a Linux System
Verify that your Linux distribution has the required CIFS packages installed.
Create a mount point with the sudo mkdir /mnt/smb_share command.
Mount the volume with the sudo mount -t cifs //computer_name/share_name /mnt/smb_share command.
If your share requires user credentials, add the switch -o username= with the username after cifs and before the share address.
Mounting on a Windows System
To permanently mount the SMB share in Windows, map a drive letter in the computer for the user to the TrueNAS IP and share name.
Select a drive letter from the bottom of the alphabet rather than from the top to avoid assigning a drive dedicated to some other device.
The example below uses Z.
Open the command line and run the following command with the appropriate drive letter, TrueNAS system name or IP address, and the share name.
net use Z: \\TrueNAS_name\share_name /PERSISTENT:YES
Where:
Z is the drive letter to map to TrueNAS and the share
TrueNAS_name is either the host name or the system IP address
share_name is the name given to the SMB share
To temporarily connect to a share, open a Windows File Explorer window, type \\TrueNAS_name\share_name and then enter the user credentials to authenticate with to connect to the share.
Windows remembers the user credentials, so each time you connect, it uses the same authentication credentials unless you restart the system.
After restarting, you are prompted to enter the authentication credentials again.
Mounting on an Apple System
Before you begin this process, have the username and password for the user assigned to the pool or the credentials for the guest if the share has guest access ready.
Open Finder > Go > Connect To Server
Enter the SMB address as follows: smb://192.168.1.111.
Input the username and password for the user assigned to that pool or a guest user if the share has guest access.
Mounting on a FreeBSD system involves creating the mount point and mounting the volume.
Create a mount point using the sudo mkdir /mnt/smb_share command.
Mount the volume using the sudo mount_smbfs -I computer_name\share_name /mnt/smb_share command.
Setting up an External SMB Share
External SMB shares are essentially redirects to shares on other systems.
Administrators might want to use this when managing multiple TrueNAS systems with SMB shares, and if they do not want to keep track of which shares are on which boxes for clients.
This feature allows admins to see and connect to any TrueNAS system with external shares active.
Create the SMB share on another TrueNAS remote server (for example, system1), as described in Adding an SMB Share above.
We recommend using Active Directory or LDAP when creating user accounts, but at a minimum, synchronize user accounts between the system with the share (system1) and on the TrueNAS system where you set up the external share (for example, system2).
On system2 (the local system), select External Share, enter the full domain name or IP address, and the share name.
Separate the server and share name with the \ character. Example: 192.168.0.200\SHARE in Remote Path.
Click Save to add the share.
Repeat the system2 instructions above on system1 to see the SMB shares on each system.
Repeat for each TrueNAS system with SMB shares to add as an external share.
Setting Up an External Share with an Earlier Release
When setting up an external share between TrueNAS systems that are on different releases, for example, one system is on 25.04 and the other is on the latest release of 25.10, follow the external share instructions for each release.
Set the TrueNAS 25.04 system SMB Purpose to the default preset, leave the default settings associated with this share as is, and then enter the redirect path to share on the 25.10 system as EXTERNAL:ipaddress\sharename in the Path field. For example, EXTERNAL:10.220.3.33\testshare2.
Be aware, changing the path also changes the SMB share name. Verify the share name is set to the desired or existing share name and not renamed to the redirect string in Path.
Set the TrueNAS 25.10 system SMB Purpose to External Share, and then enter the path to the share on the 25.04 system as ipaddress*sharename* in the Remote Path field. For example, 10.220.1.34*testshare*.
Using SMB Shadow Copy: Provides information on SMB share shadow copies, enabling shadow copies, and resolving an issue with Microsoft Windows 10 v2004 release.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
To access SMB share management options, go to Shares screen with the Windows (SMB) Shares widget.
To access SMB share management options, go to Shares and locate the Windows (SMB) Shares widget.
The widget lists configured SMB shares, but it is not the complete list.
To see a complete list of shares, click on Windows (SMB) Shares launch header to open the Shares > SMB screen.
The more_vert dropdown list to the right of each share shows four options that open other screens or dialogs that provide access to share settings.
Sharing Administrator Access
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards.
The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Managing SMB Shares
To manage an SMB share, click more_vert dropdown list to the right of each share to see the options for the share you want to manage. Options are:
Edit opens the Edit SMB screen where you can change settings for the share.
Edit Filesystem ACL opens the Edit ACL screen, where you can edit the dataset permissions for the share.
The Dataset Preset option determines the ACL type and the type of ACL Editor screen that opens (POSIX or NSFv4).
Delete opens a delete confirmation dialog. Use this to delete the share and remove it from the system. Delete does not affect shared data.
Configuring SMB Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Modifying ACL Permissions for SMB Shares
When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
Click Continue to close the dialog and continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions widget, 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.
TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL if you did not stop to strip the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
You have two options that modify ACL permissions for SMB shares:
Edit Share ACL modifies ACL permissions that apply to the SMB share.
Edit Filesystem ACL modifies ACL permissions at the share dataset level.
See the ACL Primer for general information on Access Control Lists (ACLs) in general, the Permissions article for more details on configuring ACLs, and Edit ACL Screen for more information on the dataset ACL editor screens and setting options.
Configuring the SMB Share ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses.
The permissions apply at the SMB share level for the selected share.
They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on shareEdit Share ACL to open the Edit Share ACL screen to modify permissions at the share level.
Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
Configuring Dataset File System ACL
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option.
This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level.
To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, click on the more_vert dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share.
You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group.
Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default.
Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry.
Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group.
Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
Changing the built-in-user Group Permissions
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen.
Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
Adding a New Share Group
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Groups, click Add and create the new group.
Go to Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group.
Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field.
For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL.
Add an ACE entry for the new group, and select Traverse.
Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
Using the Traverse Permission
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
Adding a Basic Time Machine SMB Share
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS 25.04.0: Time Machine shares are incompatible with multiprotocol (SMB/NFS) shares. TrueNAS automatically disables SMB2/3 lease support and AAPL extensions globally when multiprotocol shares are configured, preventing Time Machine functionality.
TrueNAS 25.04.1 and later: This limitation is removed. Multiprotocol shares now use per-share oplock management instead of global oplock disabling, allowing Time Machine and Final Cut Pro Storage Share shares to coexist with multiprotocol shares on the same system. SMB leases are permitted globally, with oplocks disabled only at the multiprotocol share level.
TrueNAS uses predefined setting options to establish an SMB share that fits a predefined purpose, such as a basic Time Machine share.
Setting Up a Basic Time Machine SMB Share
To set up a basic time machine share:
Create the user(s) for this SMB share.
Go to Credentials > Users and click Add.
After creating the share, start or restart the SMB service.
When accessing from a Windows client, having more than 512 snapshots on the TrueNAS box can lead to performance issues, as the Windows client often attempts to load all snapshots into the Windows Previous Versions tab.
To avoid this, users should maintain fewer than 512 snapshots or consider accessing from a non-Windows client.
Alternatively, configure snapshot lifetimes or create an automatic deletion policy via the Periodic Snapshot Tasks screen. This screen helps users manage the snapshot count more effectively.
The latest maintained Mac OS versions allow setting the maximum Time Machine backup size from the Mac OS UI.
Setting this from the client side is generally recommended for better share flexibility and macOS coordination.
Note that enabling a multi-user Time Machine does not automatically replicate the backup data to another pool or offsite system. To protect against data loss, configure a Replication Task that includes the dataset used by the Time Machine share.
Creating the Share and Dataset
You can either create the dataset to use for the share on the Add Dataset screen and the share, or create the dataset when you add the share on the Add SMB screen.
We recommend using the Add SMB screen when setting up a Time Machine share, as it can create the dataset, enable the SMB2/3 protocol setting in the SMB service, and create the Time Machine share from the same screen.
When you want to customize the dataset, use the Add Dataset screen to create the customized dataset and a basic SMB share.
After saving, go to Shares, select the SMB share, and click Edit to change the purpose to Time Machine Share.
The Edit SMB screen shows the Enable Now button to configure the SMB service with the required SMB2/3 protocol option if it is not already enabled.
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
When using the file browser in the Add SMB or Edit SMB screens, if the parent dataset selected has an ACL, TrueNAS might show a warning message advising you to strip the ACL from the dataset.
Click Continue to close the dialog and continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions widget, 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.
TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL if you did not stop to strip the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
To use the Add SMB screen, click Add on the Windows (SMB) Shares widget to open the screen.
Set the Path to the existing dataset created for the share, or to where you want to add the dataset, then click Create Dataset.
Enter a name for the dataset and click Create Dataset.
The dataset name populates the share Name field and updates the Path automatically.
The dataset name becomes the share name.
Leave this as the default.
If you change the name, follow the naming conventions for:
Enabled is selected by default to allow sharing of this path when the SMB service is activated.
Clearing this option disables the share but does not delete the configuration.
Click Advanced Options to finish customizing the share, then click Save.
Start or restart the SMB service when prompted.
Modifying the SMB Service
You can configure the SMB service before you add the share, or you can enable this setting from the Add SMB or Edit SMB screens while adding the share or modifying an existing share. The system prompts you to restart the service after modifying the SMB service or adding/changing a share configuration.
Click on the on the Windows (SMB) Share widget, then click Config Service to open the SMB Service screen.
Go to System > Services and scroll down to SMB.
When using the Services screen, click the Stop Service button to turn off the SMB service if it is running, then click editEdit to open the SMB service settings screen.
Click Advanced Settings.
Select Enable Apple SMB2/3 Protocol Extension to enable it, then click Save.
Start or restart the SMB service.
Setting Up Final Cut Pro SMB Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
The Final Cut Pro Storage Share purpose enables Use Apple-style Character Encoding, which translates NTFS illegal characters to the Unicode private range. This ensures compatibility with Final Cut Pro.
Enabling this feature on shares with existing data might cause unexpected behavior for files that were written without Apple character encoding enabled. Test thoroughly before applying to production shares with existing content.
This share purpose requires Apple SMB2/3 Protocol Extensions to be enabled globally in the SMB service configuration.
About Final Cut Pro Storage Shares
The Final Cut Pro Storage Share purpose is available in TrueNAS 25.10.1 and later.
TrueNAS provides the Final Cut Pro Storage Share purpose for professional media production workflows.
This share type automatically enables Use Apple-style Character Encoding to translate NTFS illegal characters for proper file handling in Final Cut Pro.
Apple-style character encoding ensures that special characters and metadata are preserved correctly, which is essential when working with media files that have complex naming conventions.
Many online guides recommend manually configuring SMB VFS options for macOS compatibility:
vfs objects = catia fruit streams_xattr
TrueNAS does not support manual VFS module configuration. Manually setting VFS objects via auxiliary parameters or CLI overrides TrueNAS defaults and breaks Asynchronous I/O (AIO), Access Control Lists (ACLs), and Shadow Copies.
Why does TrueNAS handle VFS modules differently?
The TrueNAS SMB implementation integrates VFS modules with several advanced features. Manual VFS configuration breaks functionality including:
Asynchronous I/O (AIO): Overrides modules needed for SMB performance optimization, causing poor performance or stability issues.
Access Control Lists (ACLs): Bypasses or breaks ACL functionality, causing incorrect permission handling.
The Final Cut Pro Storage Share purpose preset automatically configures VFS modules to integrate properly with TrueNAS AIO, ACLs, and Shadow Copies. By using this preset instead of manual configuration, you get a share that works seamlessly with Final Cut Pro without risking system functionality.
Prerequisites
Before setting up a Final Cut Pro Storage Share:
Create user accounts for media users who access the share.
Go to Credentials > Local Users and click Add.
Ensure SMB Access is selected for each user.
Prepare a dataset for the share (or you can create one during share creation).
For best performance with large media files, consider:
Enabling compression (LZ4 is recommended for media files).
Setting appropriate record size (128K or larger for video files).
Configuring adequate space quotas.
Turn on Enable Apple SMB2/3 Protocol Extensions for the SMB service (instructions below).
Setting Up a Final Cut Pro Storage Share
To set up a Final Cut Pro storage share, complete the following steps in order:
If the SMB service is already running, restart it for the changes to take effect.
Create the Share and Dataset
You can either create the dataset first using the Datasets screen and then add the share, or create both together.
This tutorial uses the Add SMB screen to create both the dataset and share at the same time.
Go to Shares and click Add on the Windows (SMB) Shares widget.
In the Path field, browse to the parent dataset where you want to create the share dataset.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Click Enable Now to enable the required setting in the SMB service configuration. Wait for the service to update.
When complete, TrueNAS displays a success message confirming Apple SMB2/3 protocol extension support is enabled.
Configure Advanced Options
While creating a basic Final Cut Pro Storage Share requires no additional configuration, you can customize access and logging settings.
Click Advanced Options to expand additional settings.
Configure Access settings as needed:
Export Read-Only: Leave unselected to allow media file editing.
Browsable to Network Clients: Enabled by default (recommended).
Access Based Share Enumeration: Select to enable if needed for your access control requirements.
Configure Watch List and Ignore List as needed for monitoring specific users or groups.
Note that Use Apple-style Character Encoding is automatically enabled under Other Options and cannot be disabled.
TrueNAS enforces this setting because Final Cut Pro requires Apple character encoding to operate properly.
Click Save to create the share.
Configure Dataset Permissions
After creating the share, configure dataset permissions to grant access to media users.
On the Shares screen, locate the new share in the Windows (SMB) Shares widget.
Click and select Edit Filesystem ACL.
Configure ACL entries for users or groups who need access:
For individual users: Add ACL entries with appropriate permissions (FULL for editors, READ for reviewers).
For groups: Create a group like media_users and add users, then add a group ACL entry.
Click Save Access Control List.
See Managing SMB Shares for detailed information on configuring ACL permissions.
Start the SMB Service and Mount the Share
If the SMB service is not running, start it from the Windows (SMB) Shares widget:
Click on the widget header.
Select Turn On Service.
Connect from Mac Client
On the Mac client, connect to the share:
Open Finder.
Select Go > Connect to Server (or press Cmd+K).
Enter the SMB address:
smb://your-truenas-ip/share-name.
Authenticate with a user account that has access to the share.
The share is now available for use with Final Cut Pro.
Testing and Verification
After mounting the share, verify proper operation:
File Creation: Create test files from Final Cut Pro to verify proper file handling.
Character Handling: Test filenames with special characters to confirm Apple character encoding is working correctly.
Performance: Copy large media files to verify adequate transfer speeds for your workflow.
Permissions: Test access with different user accounts to verify ACL configuration.
Migrating Existing Media Libraries
If you have an existing Final Cut Pro workflow using a standard SMB share with default settings that works properly, TrueNAS recommends keeping your current configuration. Migration is only necessary if you are experiencing specific compatibility issues or need the character encoding features provided by the Final Cut Pro Storage Share preset.
Migrating an existing media library from a standard SMB share to a Final Cut Pro Storage Share requires careful planning because enabling Apple character encoding might affect existing files:
Files created without Apple character encoding might display differently or have access issues
Existing project files might need to be re-indexed by Final Cut Pro
Test thoroughly in a non-production environment before migrating production data
Migration Steps
Only proceed with migration if you have confirmed that your current setup is incompatible with your requirements:
Create a new Final Cut Pro Storage Share and dataset in TrueNAS following the instructions in this article.
Configure dataset permissions for the new share to grant appropriate access to media users.
Copy a small subset of test files to the new share using the Mac client:
Open Finder and connect to both the old and new shares
Copy a few representative project files and media assets from the old share to the new share
Test these files in Final Cut Pro to verify proper access and functionality
If testing is successful, migrate remaining data via the Mac client:
Use Finder to copy files from the old share to the new share
Monitor the transfer for errors or warnings
Verify file integrity after the transfer completes
Update Final Cut Pro libraries and project files to point to the new share location.
Keep the old share available for a period of time as a backup until you confirm all workflows function correctly with the new share.
Using SMB Shadow Copy
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
TrueNAS automatically enables shadow copies for SMB shares, exporting ZFS snapshots as Shadow Copies for Microsoft clients.
About SMB Shadow Copies
Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots.
You can use shadow copies to restore previous versions of files from within Windows Explorer.
By default, all ZFS snapshots for a dataset underlying an SMB share path are presented to SMB clients through the volume shadow copy service or are accessible directly with SMB when the hidden ZFS snapshot directory is within the SMB share path.
TrueNAS 25.10 and later does not support per-share disabling of SMB shadow copies on non-legacy shares.
If you need to completely disable shadow copies and prevent client access to ZFS snapshots, disable the ZFS snapshot directory for the shared dataset.
Go to Storage > Datasets, select the shared dataset, and click Edit on the Details widget.
In the Edit Dataset screen, select Advanced Options and set Snapshot Directory to Disabled.
When the snapshot directory is disabled, Samba automatically turns off the shadow copy feature.
Deleting Shadow Copies
Users with an SMB client cannot delete shadow copies.
Instead, the administrator uses the TrueNAS web interface to remove snapshots.
Managing Shadow Copies (Legacy Shares)
Enabling or disabling shadow copies is an available option in pre-25.10 TrueNAS releases or for legacy shares in 25.10 or later.
TrueNAS sets a share Purpose to Legacy Share after upgrading to 25.10 when shares created in a release before 25.10 have Purpose set to No Preset.
See Legacy Share Settings for more information.
To enable shadow copies for a compatible dataset go to Shares > Windows (SMB) Shares and locate the share.
Click on the Edit option for the share.
If not listed, click Windows (SMB) Shares launch to open the Sharing > SMB screen.
Select the share, then click the more_vert for the share, then click Edit to open the Edit SMB screen.
Click Advanced Options, scroll down to Other Options, and then select Enable Shadow Copies.
Click Save.
Windows 10 v2004 Issue
Some users might experience issues in the Windows 10 v2004 release where they cannot access network shares.
The problem appears to come from a bug in gpedit.msc, the Local Group Policy Editor.
Unfortunately, setting the Allow insecure guest logon flag value to Enabled in Computer Configuration > Administrative Templates > Network > Lanman Workstation in Windows does not affect the configuration.
To work around this issue, edit the Windows registry.
Use Regedit and go to HKLM\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters.
The DWORD AllowInsecureGuestAuth is an incorrect value: 0x00000000. Change this value to 0x00000001 (Hexadecimal 1) to allow adjusting the settings in gpedit.msc.
You can use a Group Policy Update to apply the edit to a fleet of Windows machines.
Disable shadow copies for an SMB share by clearing the Enable shadow copies checkbox on the Edit SMB screen in the Other Options on the Advanced Options screen for the SMB share.
Disabling does not prevent access to the hidden .zfs/snapshot directory for a ZFS dataset when it is within the path for an SMB share.
Setting Up SMB Private Dataset Shares
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
SMB Home Share is a legacy feature for organizations looking to maintain existing SMB configurations.
Microsoft deprecated the Home Shares feature in Windows 10 and removed it completely from Windows 11.
They no longer support Home Shares as of October 2025.
TrueNAS removed the home share option from the SMB share Purpose list in 24.04 (Dragonfish).
The SMB share Other Options in pre-25.10 releases includes a home share legacy option, but it is not recommended for new shares.
It is for organizations still using the legacy home shares option to add a single SMB share to provide a personal directory for every user account.
Future TrueNAS releases can introduce instability or require configuration changes affecting this legacy feature.
This option does not show in 25.10 and later releases unless an existing home share is upgraded to 25.10 or later.
Replacing SMB Home Shares
TrueNAS has removed the Use as Home Share option, found in the Other Options section of the Advanced Options screen for the Add SMB and Edit SMB screens in earlier releases of TrueNAS.
The Private Dataset Share found as a Purpose dropdown list option in 25.10 and later releases replaces home shares, and is the recommended method to provide users with a private personal folder they access through an SMB share.
The Private Dataset Share option allows creating a private personal directory for a user in the specified dataset, that when correctly configured, provides users with a private folder only they access through an SMB share.
A Private Dataset Share is not the same as guest access:
Private Dataset Share creates per-user isolated datasets - users must authenticate with credentials
Guest Access (Legacy Share only) allows anonymous access without credentials
If you are looking for guest access functionality, see the Guest Access section in the main SMB tutorial.
TrueNAS allows creating one private directory per user, while it still allows creating as many non-private directories as desired or needed.
When a user first authenticates to a Private Dataset Share, TrueNAS automatically creates a subdirectory named after their username (for example, /mnt/poolname/share-name/username/).
Each user only sees and can access their own subdirectory when connecting to the share.
Users can create as many directories as needed through a Windows File Explorer.
TrueNAS does not control what Windows allows through the File Explorer.
Share ACL settings control who can access the private directory share.
If the personal directories show in File Explorer, use Windows file properties and access control to hide the folder in the share.
A user home directory in TrueNAS is a function of the ZFS file system and is not related to the SMB private dataset share or (deprecated Home Share).
A user configuration does not need to specify or add a file system home directory for a private dataset share.
Other options for configuring individual user directories include:
Configure a single share on the TrueNAS and provision individual user directories on the client OS.
Create a single SMB share and configure the ACL so that users can create individual directories on the share that inherit write access for the user and grant read access to the administrator.
Create an SMB share using the Private SMB datasets and shares preset, and then create per-user datasets under the umbrella of a single share when users access the share.
Creating an SMB private dataset share requires provisioning users or joining Active Directory, and configuring the system storage and share.
Adding Private Dataset Shares
Private directories are not intended for every user on the system.
When setting the Purpose dropdown list to the Private Dataset Share option, TrueNAS might show the private directories to all users with access to the root level of the share but setting the share ACL prevents other users from accessing the private share.
Examples of setting up private SMB shares are those for backups, system configuration, and users or departments that need to keep information private from other users.
This article covers:
Adding the private dataset share user.
Creating the private dataset share and the dataset.
Modifying ACL permissions for the dataset(s) and the share.
Adding the Share User
SMB Access is the default user access type that allows using the account credentials to access data shared with SMB.
When creating a user, you must:
Enter a Full Name or description for the user, such as a first and last name.
Enter a Username.
Enter a Password.
Specify or accept the default user ID (UID)
TrueNAS requires other options based on the level of access and role assigned to the user.
The Shell option only shows for users with Shell Access or SSH Access selected.
To manually add a new user, click Credentials > Users, and then click Add to open the Add User screen.
Enter a username for the user. Names are case sensitive!
Set the level of access given to this user.
SMB Access is selected by default.
Select TrueNAS Access, then select 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.
Set up SSH authentication.
These options only show when you select the SSH Access 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.
Shell Access and SSH Access show the Shell and Sudo Command 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.
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list.
Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID.
TrueNAS suggests a user ID starting at 3000, but you can change it if you wish.
We recommend using an ID of 3000 or greater for non-built-in users.(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty.
This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.
If set to this path TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory.
The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset.
After clicking on a dataset, the Create Dataset option activates.
Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist.
pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure.
This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did.
This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished.
Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password.
To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password.
To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.
Using AD to Add Users 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.
Creating the Private Dataset Share
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled.
You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
You can use an existing dataset or create a new dataset for the share.
We recommend using the Add SMB screen to create a new share and dataset for this procedure, and for any customized SMB share, rather than using the Add Dataset screen to create the share and dataset.
In general, when creating a simple SMB share and dataset, you can use either screen.
We recommend using the Add Dataset screen to access the dataset advanced setting options when you want to customize the dataset, and using the Add SMB screen to create and 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.
Click Continue to close the dialog and continue adding the dataset.
Alternatively, close the Add SMB screen, go to the Datasets screen, select the same dataset, locate the Permissions widget, 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.
TrueNAaS shows a Configure ACL dialog to remind you to edit the ACL if you did not stop to strip the ACL.
Click Configure to open the Edit ACL screen, or No to close the dialog and do nothing.
Before You Begin
Before creating the private share dataset, go to Datasets, select the parent dataset for the private share dataset and check the permissions for that dataset.
Select the parent dataset on the dataset tree table, then click Edit on the Permissions widget to open the Edit ACL screen for that dataset.
Change the default in Owner and Owner Group to the admin user for your system, and click apply for both owner and owner group.
The owner and owner group default user is root, which means only the root user can create the private share dataset unless you add your admin user to the ACL and give the entry full access permissions.
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 leave the Owner and Owner Group set to root, but you must add a user entry for the admin user who creates the private dataset shares. Give that admin user full access permissions.
Adding the Private Dataset Share and Dataset
To create SMB private dataset share, go to Shares, and click Add on the Windows (SMB) Shares widget to open the Add SMB screen.
Select Private Dataset Share on the Purpose dropdown list, then click Advanced Options to configure additional share setting options.
Enter or browse to select the path to the parent dataset for the private share dataset, then 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 is populated with the full path to the new dataset.
If you create a simple share and dataset using the Add Dataset screen, to customize it, go to Shares, select it on the SMB screen (or widget if it shows on the list), then click Edit. Verify the path and Name field are populated, and change the “Purpose” from Default Share to Private Dataset.
The dataset name populates the share Name field and becomes the share name. The Path field is updated with the dataset name.
The share and dataset must have the same name.
(Optional) Click Advanced, scroll down to select Enable Logging to enable SMB share audit logging.
(Optional) Scroll down to Other Options while 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 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 option that applies to your share needs.
Click Save.
Enable or restart the SMB service when prompted and make the share available on your network.
When prompted by the system to configure the dataset ACL, accept the option. The Edit ACL screen for the new private share dataset opens.
Setting ACL Permissions
The private dataset share requires both the dataset and share ACL permissions to allow or prevent access to the share.
Dataset ACL permissions are configured on the Edit ACL screen. Share ACL permissions are configured using the Share ACL for rikka-private screen.
Setting Dataset Permissions
First, set the dataset permissions to allow your admin user and the user assigned to the private directory share access.
Your admin user must have permissions granted for the parent dataset covered in Before You Begin and the private dataset covered in this section.
If you want or need to grant another user access to the private share dataset, other than the private share user or a group of users, add an ACL entry to the dataset and 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 widget to open the Edit ACL screen.
See Setting Up Permissions for more information on editing dataset permissions.
From the Shares screen, click the triple dot icon for the share row, then click Edit Filesystem ACL to open the Edit ACL screen.
Set the permission for the private dataset to allow additional users or a group if others are permitted to access the private directory share.
Click the Owner dropdown, select the administration user with full control, and then repeat for Group.
You can set the owning group to your Active Directory domain admins. Click Apply Owner and Apply Group to apply the changes.
Click Use Preset and choose NFS4_HOME. If the dataset has a POSIX ACL, choose HOME.
Click Continue.
Next, click Add Entry to add user entries for each user that needs access to the dataset.
To assign required permissions, select User in Who and locate the user name in the User dropdown list.
Select the required permissions.
Repeat for each user that needs access.
Alternatively, if you added users to a group, select, set Who to Group and locate the group in the dropdown list.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
After adding all users or groups and setting the required permissions for each, click Save Access Control List.
Setting the Share Permissions
If the private dataset is nested under a parent dataset that also 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).
Windows File Explorer shows all datasets nested under the share parent but blocks other users not granted access permission from opening and viewing the contents of that folder or directory.
Click the triple dot icon at the right of the private dataset share on the Shares screen, then click Edit Share ACL to open the Share ACL for rikka-private screen.
Change Who from the default everyone@ to the private dataset share user. In the example, the user is rikka for the rikka-private share.
Leave Permissions set to Full and Type set to Allowed.
Click Add to show another Add entry group of settings. Change Who to the admin user to allow for share maintenance tasks, like moving the directory to a new location if that becomes necessary.
If granting other users in a group to a private share for that group, add an entry for each user and change the level of permissions to what is needed. For example, if the group members can read the files but not change them, set Permission to READ for those users, and grant the user that maintains the documents either FULL or CHANGE permissions.
Click Save when finished.
Adding Share Users with Directory Services
You can use Active Directory or LDAP to create the share users.
If not already created, add a pool, then join Active Directory.
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.
SMB Share MacOS Client Limitations When Using Decomposed Unicode Characters
There are normalize forms for a unicode character with diacritical marks: decomposed (NFD) and pre-composed (NFC).
Take for example the character ä (a + umlaut) and the encoding differences between NFC (b’\xc3\xa4’) and NFD (b’a\xcc\x88’).
The MacOS SMB client historically and at present forces normalization of unicode strings to NFC prior to generating network traffic to the remote SMB server.
The practical impact of this is that a file that contains NFD diacritics on a remote SMB server (TrueNAS, Windows, etc.) might be visible in the directory listing in the MacOS SMB client and thereby Finder, but any operations on the file (edits, deletions, etc.) have undefined behaviors since a file with NFC diacritics does not exist on the remote server.
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
>>> os.unlink('220118_M_HAN_MGK_X_4_Entwässerung.pdf')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
FileNotFoundError: [Errno 2] No such file or directory: '220118_M_HAN_MGK_X_4_Entwässerung.pdf'
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
Above is a short example of a MacOS SMB client attempting to delete a file with NFD normalization on remote Windows server.
Short of Apple providing a fix for this, the only strategy for an administrator to address these issues is to rename the files with pre-composed (NFC) form. Unfortunately, normalization is not guaranteed to be lossless.
When creating a share, do not attempt to set up the root or pool-level dataset for the share.
Instead, create a new dataset under the pool-level dataset for the share.
Setting up a share using the root dataset leads to storage configuration issues.
SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance.
SMB multichannel does not function if you combine NICs into a LAGG.
Configuring Multiple Network Interfaces
Do not configure multiple SMB multichannel interfaces on the same subnet. To ensure reliable multichannel performance, TrueNAS recommends placing each interface on a different subnet.
If interfaces share a subnet, the system could fail to initialize multichannel, experience several connectivity issues, and accept inbound traffic inconsistently. To avoid these issues, assign each NIC a unique IP address on a different subnet and avoid bridging interfaces used for multichannel.
Activating Multichannel in TrueNAS
If you already have clients connected to SMB shares, disconnect them before activating multichannel.
Go to System > Services and click the edit edit icon for the SMB service.
Click Advanced Settings, then enable Multichannel.
Save and restart the SMB service, then reconnect all clients to their SMB Shares.
Validating Multichannel Activated In Windows
After you connect a client to their SMB share, open Powershell as an administrator on a client, then enter Get-SmbMultichannelConnection. The terminal should list multiple server IPs.
# View active SMB multichannel connectionsGet‑SmbMultichannelConnection# Sample output:# Server Name Selected Client IP Server IP Client Interface Index Server# ------------- ----------- --------- --------- ------------------------- ------# 192.168.10.2 True 192.168.10.10 192.168.10.2 5 2# 192.168.20.2 True 192.168.20.10 192.168.20.2 16 5
You can also enter Get-SmbMultichannelConnection | ConvertTo-Json and ensure CurrentChannels is more than 1.
View details as JSON
# View details as JSONGet-SmbMultichannelConnection|ConvertTo-Json# Sample output:[{"CimClass":{"CimSuperClassName":null,"CimClass":null,"CimClassProperties":"...","CimClassQualifiers":"...","CimClassMethods":"...","CimSystemProperties":"Microsoft.Management.Infrastructure.CimSystemProperties"},"CimInstanceProperties":[{"ClientInterfaceFriendlyName":"Ethernet 3","ClientInterfaceIndex":5,"ClientIpAddress":"10.230.46.64","ClientLinkSpeed":10000000000,"ClientRdmaCapable":false,"ClientRSSCapable":false,"CurrentChannels":2}]}]
NVMe-oF Subsystems
Overview of NVMe-oF
NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for fused commands required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.
Configuring the NVMe-oF Service
You can access the NVMe-of service screen from the:
more_vert dropdown menu on the NVMe-oF Subsystems widget on the Shares screen
Global Configuration button at the top of the NVMe-oF screen
NVMe-oF service option on the System > Services screen
The NVMe-oF Global Configuration shows the base NQN for the service.
What is the Base NQN?
The Base NQN us the standardized NVMe Qualified Name for the service. It is the prefix used when a new subsystem is created.
The NQN standard structure follows the format defined in the base specification. The maximum length/size is 223 bytes.
TrueNAS subsystems use the Base NQN as the root identifier for the NVMe subsystems in fabric deployments.
Discovery controllers use the standardized NQN to advertise available subsystems.
Storage systems use the Base NQN to authenticate and authorize host connections.
The Base NQN format provides the foundation for all NVMe-oF naming, ensuring interoperability, and preventing naming conflicts across different vendors and implementations.
TrueNAS populates the Base NQN field with the NVMe identifier.
Accept this value or click in the field to copy/paste a new, properly formatted Base NQN identifier.
NQN is used as the prefix when creating a subsystem, if a subnqn is not supplied.
Modifying this value does not change the subnqn of any existing subsystems.
We recommend using caution if you change this Base NQN. A particular client might be configured to talk to a particular NQN, so changing this could break the client connection.
Select Generate Cross-port Referrals for Ports on This System if subsystems are published through multiple ports and connect-all functionality is desired by clients.
If ANA is active, referrals are always generated between the peer ports on each TrueNAS controller node.
Select the Enable Remote Direct Memory Access (RDMA) option. Click Save.
Enabling RDMA allows configuring one or more ports with RDMA selected as the transport when enabled.
This option requires an Enterprise license, and you must have an RDMA-capable system and network equipment.
This option is inactive on systems without an Enterprise licenses.
If the system is not equipped with required hardware, shows Not enabled, because this system does not support RDMA on the screen.
Adding Asymmetric Namespace Access (ANA)
Go to the NVMe-oF Global Configuration screen.
Select the Enable Asymmetric Namespace Access (ANA) option, and click Save.
This allows storage systems to inform hosts about the optimal controller path to access a namespace on Enterprise licensed systems.
It is similar to Asymmetric Logical Unit Access (ALUA) in iSCSI.
ANA helps storage arrays communicate to hosts which controller provides the best (lowest latency) path to specific namespaces, enabling intelligent multipathing and improved performance in NVMe-oF environments.
Adding a Subsystem
Subsystems correlate to iSCSI targets. Each subsystem has a namespace and port, hosts are optional for added security.
The Add Subsystem wizard steps through the subsystem creation process.
You can access the Add Subsystem wizard from the:
Add button on the NVMe-oF Subsystems widget on the Shares screen
Add Subsystem button at the top of the NVMe-oF screen
Enter a name for the subsystem. We recommend keeping the name short to avoid any possible issues with accessing the subsystem.
A name can consist of upper and lowercase alphabetical characters, numbers, and/or some special characters such as the dash (-), underscore (_), etc.
Leave the NQN set to Generate from global setting.
To change it, click on it or the edit edit icon, and then enter or copy/paste a correctly formatted NQN identification number in the field.
Add a namespace. Click Add to open the Add Namespace screen. The screen opens with the Zvol tab selected.
A subsystem can have only one namespace.
To add a new zvol, browse to and select the parent dataset where you want to add the zvol, then click Create Zvol to open the Add Zvol screen. See Creating a Zvol for more information on adding a new zvol.
To use an existing file, click on the Existing File tab, and then browse to select the path to the file.
Leave Allow any host to connect selected to allow any host to connect, or clear the checkbox to show the Add option for hosts.
Adding individual hosts limits access to the subsystem to only the host(s) added.
c. (Optional) Enter the DH-CHAP key obtained from the host system to use when connecting to TrueNAS.
Enter or copy/paste the key into the field.
To allow TrueNAS to create a key for the host, click in the field to activate Generate Key below the Key for Host to Present field. The field populates with a key. Copy/paste this into the host system connecting to TrueNAS.
d. (Optional) Add a bi-directional key for TrueNAS when it connects to the host system.
Click Generate Key below the Key for TrueNAS to Present to populate the field with a key. Copy/paste this into the host system to use when authenticating TrueNAS when it connects to it.
e. (Optional) Select Also use Diffie-Hellman key exchange for additional security.
f. Click Save, then click on the breadcrumb at the top of the screen to return to the Add Subsystem wizard.
Add a port. Click Add to the right of Ports to open the Add Ports screen.
Enter a port number that is at least four digits in length.
4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.
a. Select the transport type. TCP is the default setting.
If you have an Enterprise license and your system can support RDMA, this option shows as an available choice.
b. Enter an available port number of at least four digits in length.
c. Select the IP address from the dropdown list.
d. Click Save.
e. Click on the breadcrumb at the top of the screen to close the Add Port screen and return to the Add Subsystem wizard.
Click Save at the bottom of the Add Subsystem wizard screen to add the subsystem.
Creating a Zvol
The Add Zvol screen is accessed from the Add Subsystem wizard after clicking Add to the right of Namespaces.
You can also access it from the Namespace widget on the NVMe-oF screen.
Select the subsystem row on the NVMe-oF screen table, then click Add on the Namespaces widget to show the options.
Select Create New to open the Add Namespace screen.
Browse to and select the dataset where you want to add the zvol, then click on Create New to open the Add Zvol screen.
To add a new zvol:
Enter a name. We recommend keeping the name short.
You can use standard name alpha-numeric, upper or lower case letters, and approved special characters in the name.
Accept the default settings for the remaining settings, or click the edit edit icon to show a text entry or dropdown selection field.
Enter or select the desired new settings.
(Optional) Set encryption for the zvol.
If the parent dataset where you add the zvol is unencrypted, you can set encryption by clearing the Inherit (unencrypted) checkbox.
If the parent dataset is encrypted you can only change the type of encryption as key or passphrase type.
Clear the Inherit (encrypted) checkbox to see the encryption type options.
Click Save, then click the breadcrumb at the top of the screen to return to the previous screen.
Managing NVMe-oF Subsystems
NVME Structure
NVMe over TCP is incompatible with VMware ESXi environments. TrueNAS uses the Linux kernel NVMe over TCP target driver, which lacks support for fused commands required by VMware ESXi. This is an upstream kernel limitation that prevents path initialization in ESXi environments.
Editing a Subsystem
After configuring a NVMe-oF subsystem, you can change the subsystem by adding or deleting a namespace, removing or adding a port, or adding, removing, or deleting a host.
To access the subsystem configuration screen from the Shares screen:
Click the more_vert dropdown menu on the row for the subsystem listed in the NVMe-oF Subsystems widget.
Select View to open the NVMe-oF screen for that subsystem and showing the Details widgets for it.
or
Click on the NVMe-oF Subsystems widget header to open the NVMe-oF screen, and then locate and select the row in the Subsystem table for the desired subsystem to show the Details widgets for that subsystem.
Renaming the Subsystem
To change a subsystem name, while on the NVMe-oF screen, select the subsystem row in the table, then click on the subsystem name or the edit icon in the Details widget.
The name changes to a text entry field. Enter a new name for the subsystem, then click outside the field to save the change.
The subsystem NQN is not modified by this operation. You must choose to modify the NQN by clicking on the NQN or edit icon for the NQN shown in the Details widget, then enter or copy/paste a new correctly-formatted NQN in the field.
Copying the NQN
To copy the NQN identification number for the subsystem, while on the NVMe-oF screen, select the subsystem row in the table, then click Copy in the Details widget.
TrueNAS copies the identification number to the clipboard.
Deleting a Subsystem
Before deleting a namespace subsystem, delete the port and any associated host. TrueNAS shows an error if the subsystem has an active port and host.
While on the NVMe-oF screen, select the subsystem row in the table, then click Delete to the right of Details for name.
The Delete Subsystem dialog opens.
Delete the port. This does not delete the port configuration from the system, it removes it from the namespace subsystem.
Delete any associated host. This does not delete the host configuration from the system, it removes it from the namespace subsystem.
Delete the subsystem.
Verify the name of the subsystem listed in the dialog to confirm you have the desired subsystem.
Click Delete to delete the subsystem and namespace(s) associated with it.
Cancel closes the dialog without deleting the subsystem.
Select Force if the delete operation shows an in use error, or to delete with a port or host still associated with the subsystem, then click Delete again.
Deleting a Zvol Namespace
To delete a zvol namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the zvol in the Namespace widget.
The Delete Namespace dialog opens. Deleting the namespace from the zvol does not delete the zvol it only removes it from the subsystem.
To delete a file namespace, while on the NVMe-oF screen, select the subsystem row in the Subsystem table, then click the delete delete icon to the right of the file in the Namespace widget.
The Delete Namespace dialog opens with the option to delete the underlying file.
Select the Also delete the underlying file option, then click Delete to delete both the namespace and the file.
Editing Ports
You can add new ports or edit existing ports from the Ports widget on the NVMe-oF screen.
First, select the subsystem row in the table, then click the Add dropdown on the right of the Ports widget header.
Click Create New to open the Add Port screen and add a new port.
To edit or delete a port, click Manage Ports to open the Ports dialog.
Adding a Port
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports widget.
Click Create New to open the Add Port screen.
The Add Port screen creates a new port IP address:port assignment on the system for use by a subsystem.
Select the transport type. TCP is the default setting.
If your system has an Enterprise license, and it supports RDMA, this option is listed as available.
Enter an available port number of at least four digits in length. For example, 4420 is the default and recommended port number.
Select the IP address from the dropdown list. Only static IP addresses in the TrueNAS system show on this list.
Click Save.
The next time you click Add on the Ports widget, the added port shows as an option on the dropdown list.
Editing a Port
While on the NVMe-oF screen, with the subsystem selected in the table, click Add on the Ports widget.
Click Manage Ports to open the Ports window.
Select the edit edit icon for the port listed in the table to open the Edit Port screen.
The Edit Port screen shows current port settings for the selected subsystem.
Select the transport type from the dropdown list.
Leave TCP as the default option unless your system has an Enterprise license and it supports RDMA.
Enter a port number that is at least four digits in length. 4420 is the default port number, commonly selected for NVMe-oF with IP addresses, and we recommend using this port rather than adding a custom port.
Leave the IP address for the TrueNAS system, or select any static IP address shown on the list.
Click Save.
Removing a Port from the Subsystem
You can change the port number assigned to the subsystem using the Remove this port from the subsystem icon on the Ports widget.
After removing a port, the Add button lists any available port on the system, including the port removed from the subsystem, in the format IP address:port.
Deleting a Port
Deleting a port does not remove it from the system; it removes the port from the selected subsystem.
A deleted port shows on the Add dropdown list on the Ports widget for a selected subsystem on the NVMe-oF screen.
To delete the port, click on the delete delete icon at the right of the port row on the Ports window.
The Delete Port confirmation dialog opens. You are asked to confirm that you want to delete the port.
Delete Anyway removes the port assignment from the subsystem specified in the dialog.
Adding a Host
The Associated Hosts widget on the NVMe-oF screen shows a list of hosts associated with the subsystem selected on the table.
All hosts are allowed is selected by default, and allows all clients to connect to the subsystem if a host is not specified.
To add connection security, limit the hosts allowed to connect to the subsystem. Select All Hosts are allowed to clear the checkbox and show the option to add a host.
To add a host, click Add to open the Add Host screen.
Obtain the NQN number from the host system and enter or copy/paste it into the NQN field.
TrueNAS uses this to determine if the host(s) can access the subsystem namespace.
To require authentication and add secret keys to further secure communication between the TrueNAS subsystem and the host system, select Require Host Authentication.
This shows the additional setting options.
Accept the default in Hash or click the edit edit edit icon and select a hash option from the dropdown list.
Options are SHA-256, SHA384, and SHA-512.
Obtain the DH-CHAP key from the host you are allowing to connect to the subsystem, and enter or copy/paste it in the Key For Host To Present field.
Alternatively, TrueNAS can create a key for the host system if you click Generate Key directly under the field.
Copy this key from TrueNAS, and paste it into the host system as the key it presents to TrueNAS to authenticate the connection.
To use bidirectional authentication, click Generate Key directly below the Key For TrueNAS To Present (Optional).
It populates the field with a secret key.
Copy this key from TrueNAS, and paste it into the host system to validate the TrueNAS connection.
For additional authentication security, select Also use Diffie-Hellman key exchange for additional security.
Click Save, then close the screen.
Hosts added to the subsystem show in the Associated Hosts widget with options to edit, delete, or remove them from the host.
Removing a Host
Click the Removes this host from the subsystem icon to remove the host from the subsystem.
This does not delete it from TrueNAS; the removed host shows on the Add dropdown list if you want to add the host to the subsystem again.
Editing a Host
To edit a host, click Add, then select Manage Hosts. The Hosts window opens.
The Hosts window shows a table listing the host NQN, if it requires authentication, and the number of subsystems that use it.
Click the edit edit icon to the right of the host row to open the Edit Host screen.
The Edit Host screen shows the fields associated with the subsystem and allows you to change the host settings.
Make the desired change, then click Save.
Delete Host Dialog
To delete a host from the subsystem, click Add, then select Manage Hosts. The Hosts window opens.
click the delete delete icon to the right of the host.
The Delete Host confirmation dialog opens, showing the hosts associated with the subsystem.
Click Delete Anyway to delete the host from the subsystem(s) specified in the dialog.
Data Protection
The Data Protection section allows users to set up multiple redundant tasks that will protect and/or backup data in case of drive failure.
Scrub Tasks can provide early disk failure alerts by identifying data integrity problems and detecting various indicators of drive reliability.
TrueCloud Backup, Cloud Sync, Periodic Snapshot, Rsync, and Replication Tasks, provide backup storage for data and allow users to revert the system to a previous configuration or point in time.
Contents
Managing TrueCloud Backup Tasks: Provides instructions on setting up a TrueCloud backup task and configuring a Storj iX account to work with TrueNAS.
Cloud Sync Tasks: Tutorials for configuring and managing data backups to from TrueNAS to various 3rd party Cloud Service Providers.
Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.
Advanced Replication Tasks: Provides instructions on configuring advanced ZFS snapshot replication tasks in TrueNAS.
Managing TrueCloud Backup Tasks
TrueNAS can send, receive, or synchronize data with the cloud storage providers available in TrueNAS.
TrueCloud backup tasks allow for single-time transfers or recurring transfers on a schedule.
They are an effective method to back up data to a remote location.
This article provides instructions on configuring a TrueCloud backup task using Storj and covers setting up the Storj iX account and TrueNAS credential.
To take advantage of the lower-cost benefits of the TrueCloud backup service, you must create your Storj iX account using the link provided on the Add Cloud Credentials screen.
You must also create and authorize the storage buckets on Storj for TrueNAS to use.
iXsystems is not responsible for charges incurred using a third-party vendor with the TrueCloud backup feature.
TrueCloud Backup Task Requirements
You must configure all system storage (pool and datasets or zvols) and have them ready to receive or send data.
Adding the Storj cloud credential in TrueNAS includes following the link to create the Storj iX account, creating a new bucket, and obtaining the S3 authentication credentials needed to complete the process in TrueNAS.
Go to Credentials > Backup Credentials and click Add on the Cloud Credentials widget.
The Cloud Credentials screen opens with Storj displayed as the default provider in the Provider field.
You must use this link to create your Storj account to take advantage of the benefits of the Storj iX pricing!
Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, and click the button at the bottom of the screen.
The Storj main dashboard opens.
Select the permissions you want to allow this access key.
Choose Full Access to allow permanent full permissions to all buckets and data then click Create Access or select Advanced then click Next to customize access configuration.
b. Select the buckets to allow access to.
Click All Buckets or click Select Buckets and use the Buckets dropdown to select one or more bucket(s).
Click Next.
c. Select an expiration date if you want to set the duration or length of time to allow this credential to exist.
You can select a preset period, click Set Custom Expiration Date to use the calendar to set the duration, or select No expiration.
Click Next to open the Access Encryption window.
Not all Storj buckets are TrueNAS compatible.
To create a TrueNAS-compatible bucket, either log in to Storj using the ix Storj affiliate link before creating the bucket in the Storj UI, or use the TrueNAS UI to create the bucket using the Add New option.
To create a Storj bucket from the TrueNAS UI:
Go to Data Protection.
Click Add on either the TrueCloud Backup Tasks or Cloud Sync Tasks widget.
Select the stored Storj cloud credential from the Provider > Credentials dropdown.
Do this as part of setting up a task or use the wizard to create the bucket without saving a configured task.
Click Verify Credential for verification, then click Next to go to the What and When screen.
Enter or browse to select the local Source Path to the directories or files you want sent to the cloud for backup.
Click the arrow to the left of the name to expand it, then click on the name to select it.
Select the Storj credential on the Credentials dropdown list.
You can select Add New to create the Storj credential if you skipped the instructions above.
Select the Storj bucket from the Bucket dropdown list.
If you have not previously created a TrueNAS compatible Storj bucket, select Add New and follow the procedure in Creating a TrueNAS Storj Bucket.
Click the arrow icon for the Folder field to expand the dropdown list and select the desired folder in the Storj bucket, or enter a folder path.
Enter /name, where name is a folder that does not exist, to create a new folder in the Storj bucket.
Enter a name for the task under Task Settings.
Enter the number of snapshot copies to retain in Keep Last.
Enter a password for the backup repository.
Record this password in a secure location.
You need the password to recreate the task using the same bucket/folder, such as in a new TrueNAS install or system, or to restore data from the existing snapshots in another TrueNAS system.
Set the task schedule for when to run this task.
Click Save.
TrueNAS adds the task to the TrueCloud Backup Tasks widget with the state N/A until the task runs on schedule.
To test the task, click the vertical ellipses more_vert on the task and select Run Job to start the task apart from the scheduled time.
Select Use Snapshot to create and use a snapshot to back up or synchronize the operation between TrueNAS and the TrueCloud backup solution. This snapshot is automatically removed after the operation completes.
Advanced users can write scripts that run immediately before or after the TrueCloud backup task.
Enter environment variables in either the Pre-script or Post-script fields.
The Post-script field only runs when the TrueCloud backup task succeeds.
See TrueCloud Backup Tasks Screens for information on available environment variables.
Use Exclude to enter a list of files and directories to exclude from sync.
Press Enter to separate entries.
See TrueCloud Backup Tasks Screens for syntax examples.
Use Transfer Settings to prevent excess resource consumption by setting the pack size and read concurrency.
Managing TrueCloud Tasks
To edit an existing TrueCloud backup task, click the vertical ellipses more_vert on the task and select Edit to open the Edit TrueCloud Backup Task screen. After making changes, click Save.
To run a scheduled task before the defined time, click the vertical ellipses more_vert on the task and select Run Job to start the task immediately.
To delete a task, click the vertical ellipses more_vert on the task and select delete Delete for the task to delete.
Select Include Everything to restore all data, or exclude some data using Include from subfolder, Select paths to exclude, or Exclude by pattern.
See TrueCloud Backup Tasks Screens for more information.
Set the local Target to the target dataset of the backup task.
Click Save to restore data from the snapshot.
Removing TrueCloud Snapshots
To delete an existing snapshot, locate it on the Snapshots widget.
Click the vertical ellipses more_vert on the snapshot and select delete Delete to delete the snapshot.
A Delete Snapshot dialog opens.
This section has tutorials for configuring and managing data backups to from TrueNAS to various 3rd party cloud service providers.
This article provides instructions on adding a cloud sync task, configuring environment variables, running an unscheduled sync task, creating a copy of a task with a reversed transfer mode, and troubleshooting common issues with some cloud storage providers.
TrueNAS can send, receive, or synchronize data with a cloud storage provider.
Cloud sync tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS:
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
Using the cloud means data can go to a third-party commercial vendor not directly affiliated with iXsystems.
You should fully understand vendor pricing policies and services before using them for cloud sync tasks.
iXsystems is not responsible for any charges incurred using third-party vendors with the cloud sync feature.
Cloud Sync Task Requirements
You must have:
All system storage configured and ready to receive or send data.
A cloud storage provider account and location (like an Amazon S3 bucket).
You can create cloud storage account credentials using Credentials > Backup Credentials > Cloud Credentials before adding the sync task or add it when configuring the cloud sync task using Add on the Data Protection > Cloud Sync Task widget to open the Cloudsync Task Wizard.
See the Cloud Credentials article for instructions on adding a backup cloud credential.
Creating a Cloud Sync Task
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.
Select an existing backup credential from the Credential dropdown list.
If not already added as a cloud credential, click Add New to open the Cloud Credentials screen to add the credential.
Click Save to close the screen and return to the wizard.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the option from Direction and in Transfer Mode.
Select the location where to pull from or push data to in the Folder field.
Select the dataset location in Directory/Files. Browse to the dataset to use on TrueNAS for data storage.
Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select or enter the required settings that include where files are stored. Cloud provider settings change based on the credential selected.
If shown, select the bucket on the Bucket dropdown list.
Select the time to run the task from the Schedule options.
Click Save to add the task.
Use Dry Run to test the configuration before clicking Save or select the option on the Cloud Sync Task widget after you click Save.
TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule.
Encrypting Cloud Sync Tasks
The option to encrypt data transferred to or from a cloud storage provider is available in the Advanced Options settings.
Select Remote Encryption to use rclone crypt encryption during pull and push transfers.
With Pull selected as the Transfer Direction, the Remote Encryption decrypts files stored on the remote system before the transfer.
This requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.
With Push selected as the Transfer Direction, data is encrypted before it is transferred and stored on the remote system.
This also requires entering the same password to encrypt data in both Encryption Password and Encryption Salt.
We do not recommend enabling Filename Encryption for any cloud sync tasks that did not previously have it enabled.
Users with existing cloud sync tasks that have this setting enabled must leave it enabled on those tasks to be able to restore those existing backups.
Do not enable file name encryption on new cloud sync tasks!
When selecting Filename Encryption transfers encrypt and decrypt file names with the rclone Standard file name encryption mode.
The original directory structure of the files is preserved.
When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, use sub-paths, and copy single files.
When enabled, file names are encrypted, file names are limited to 143 characters, the directory structure is visible, and files with identical names have identical uploaded names.
File names can use sub-paths, single-copy files, and shortcuts to shorten the directory recursion.
Troubleshooting Transfer Mode Problems
Sync keeps all the files identical between the two storage locations.
If the sync encounters an error, it does not delete files in the destination.
Syncing to a Backblaze B2 bucket does not delete files from the bucket, even after deleting those files locally.
Instead, files are tagged with a version number or moved to a hidden state.
To automatically delete old or unwanted files from the bucket, adjust the Backblaze B2 Lifecycle Rules.
A directory, deleted in BackBlaze B2 and notated with an asterisk, do not display in the TrueNAS UI.
These folders are essentially empty directories and Backblaze API restricts them so they do not display.
Amazon S3 Issues
Sync cannot delete files stored in Amazon S3 Glacier or S3 Glacier Deep Archive.
First restore these files by another means, like the Amazon S3 console.
Using Scripting and Environment Variables
Advanced users can write scripts that run immediately before or after the cloud sync task.
Use either the Advanced Options screen accessed from the Cloudsync Task Wizard or Edit Cloud Sync Task screen, scroll down to the Advanced Options to locate and then enter environment variables in either the Pre-script or Post-script fields.
The Post-script field only runs when the cloud sync task succeeds.
Running an Unscheduled Cloud Sync Task
Saved tasks activate based on the schedule set for the task.
Click Run Now on the Cloud Sync Task widget to run the sync task before the saved scheduled time.
You can also expand the task on the Cloud Sync Tasks screen and click Run Now on the task details screen.
An in-progress cloud sync must finish before another can begin.
Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.
To view logs about a running task, or its most recent run, click on the State oval.
Using Cloud Sync Task Restore
To create a new cloud sync task that uses the same options but reverses the data transfer, click the vertical ellipses more_vert on an existing cloud sync task on the Data Protection page and select historyRestore.
The Restore Cloud Sync Task window opens.
Enter a name in Description for this reversed task.
Select the Transfer Mode and then define the path for a storage location on TrueNAS for the transferred data.
Click Restore.
TrueNAS saves the restored cloud sync as another entry in Data protection > Cloud Sync Tasks.
If you set the restore destination to the source dataset, TrueNAS may alter ownership of the restored files to root.
If root did not create the original files and you need them to have a different owner, you can recursively reset their ACL permissions through the GUI.
Cloud Sync Tasks Contents
Backing Up Google Drive to TrueNAS: Provides instructions on adding Google Drive cloud credentials using the Add Cloud Credentials and Add Cloud Sync Task screens, and on working with Google-created content.
Google Drive and G Suite are widely used tools for creating and sharing documents, spreadsheets, and presentations with team members.
While cloud-based tools have inherent backups and replications included by the cloud provider, certain users might require additional backup or archive capabilities.
For example, companies using G Suite for important work might be required to keep records for years, potentially beyond the scope of the G Suite subscription.
TrueNAS offers the ability to easily back up Google Drive by using the built-in cloud sync.
Setting up Google Drive Credentials
You can add Google Drive credentials using the Add Cloud Credentials screen accessed from the Credentials > Backup Credentials > Cloud Credentials screen, or you can add them when you create a cloud sync task using the Add Cloud Sync Task screen accessed from the Data Protection > Cloud Sycn Task screen.
Adding Google Drive Credentials Using Cloud Credentials
To set up a cloud credential, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
Enter a credential name.
Select Google Drive on the Provider dropdown list. The Google Drive authentication settings display on the screen.
Enter the Google Drive authentication settings.
a. Click Log In To Provider. The Google Authentication window opens.
b. Click Proceed to open the Choose an Account window.
c. Select the email account to use. Google displays the Sign In window. Enter the password and click Next to enter the password. Click Next again.
Google might display a Verify it’s you window. Enter a phone number where Google can text an verification code, or you can click Try another way.
d. Click Allow on the TrueNAS wants to access your Google Account window. TrueNAS populates Access Token with the token Google provides.
Click Verify Credentials and wait for TrueNAS to display the verification dialog with verified status. Close the dialog.
Click Save.
The Cloud Credentials widget displays the new credentials. These are also available for cloud sync tasks to use.
Adding A Google Drive Cloud Sync Task
You must add the cloud credential on the Backup Credentials screen before you create the cloud sync task.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloudsync Task Wizard opens.
Select Google Drive on the Credential dropdown list, then enter your credentials.
Click Next.
Select the direction for the sync task.
PULL brings files from the cloud storage provider to the location specified in Directory/Files (this is the location on TrueNAS).
PUSH sends files from the location in Directory/Files to the cloud storage provider location you specify in Folder.
Select the transfer method from the Transfer Mode dropdown list.
Sync keeps files identical on both TrueNAS and the remote cloud provider server. If the sync encounters an error, destination server files are not deleted.
Copy duplicates files on both the TrueNAS and remote cloud provider server.
Move transfer the files to the destination server and then deleted the copy on server that transferred the files. It also overwrites files with the same names on the destination.
Enter or browse to the dataset or folder directory.
Click the arrow_right arrow to the left of folder/ under the Directory/Files and Folder fields.
Select the TrueNAS dataset path in Directory/Files and the Google Drive path in Folder.
If PUSH is the selected Direction, this is where on TrueNAS the files you want to copy, sync or move transfer to the provider.
If Direction is set to PULL this is the location where on TrueNAS you want to copy, sync or move files to.
Click the arrow_right to the left of folder/ to collapse the folder tree.
Select the preset from the Schedule dropdown that defines when the task runs.
For a specific schedule, select Custom and use the Advanced Scheduler.
Clearing the Enable checkbox makes the configuration available without allowing the specified schedule to run the task.
To manually activate a saved task, go to Data Protection > Cloud Sync Tasks, click for the cloud sync task you want to run. Click CONTINUE or CANCEL for the Run Now operation.
(Optional) Click Advanced Options to set any advanced option you want or need for your use case or to define environment variables.
Scroll down to and enter the variables or scripts in either the Pre-script or Post-script fields.
These fields are for advanced users.
Click Dry Run to test your settings before you click Save.
TrueNAS connects to the cloud storage provider and simulates a file transfer but does not send or receive data.
The new task displays on the Cloud Sync Tasks widget with the status of PENDING until it runs.
If the task completes without issue the status becomes SUCCESS.
See Using Scripting and Environment Variables for more information on environment variables.
Working with Google Created Content
One caveat is that Google Docs and other files created with Google tools have their own proprietary set of permissions and their read/write characteristics unknown to the system over a standard file share. Files are unreadable as a result.
To allow Google-created files to become readable, allow link sharing to access the files before the backup. Doing so ensures that other users can open the files with read access, make changes, and then save them as another file if further edits are needed. Note that this is only necessary if the file was created using Google Docs, Google Sheets, or Google Slides; other files should not require modification of their share settings.
TrueNAS is perfect for storing content, including cloud-based content, for the long term. Not only is it simple to sync and backup from the cloud, but users can rest assured that their data is safe, with snapshots, copy-on-write, and built-in replication functionality.
Adding a Google Photos Cloud Sync Task
On March 31, 2025, Google changed the Google Photos API to allow external applications to access and manage only the media and albums they create.
Cloud sync tasks continue to upload photos to albums created by the TrueNAS sync client, but reading from your full photo library or from shared albums does not work as expected.
Some operations return permission errors.
Tokens issued before March 31, 2025 do not provide full-library access under the new API rules.
Generate new credentials if you need to continue uploading into albums created by the sync client.
Review existing Google Photos cloud sync tasks and configure them to use albums created by the TrueNAS source.
A complete backup of a Google Photos library through the API is not possible.
Google Photos cloud sync tasks in TrueNAS use the rclone backend for the Google Photos API to authenticate credentials and transfer data.
Configuring a Google Photos cloud sync task is a multi-part procedure where you:
A Google Photos cloud sync task can either push local files to Google Photos or (limited) pull files from Google Photos to a local TrueNAS dataset.
Select the direction that fits how you want to manage your media files.
Pull is restricted by the Google Photos API and only accesses albums created by the TrueNAS sync client.
Pulling your full library or from shared albums is not possible.
Push uploads local files into albums created by the TrueNAS sync client.
Use push to manage media in your local dataset and back it up to Google Photos.
Next, select the data transfer mode that fits how you want to manage file retention between the source and destination.
There are three options:
SYNC - Matches files on the destination to the source.
Deletes files from the destination if they do not exist on the source.
Only affects albums created by the sync client.
COPY - Duplicates each source file into the destination.
Overwrites files with the same name.
Only affects albums created by the sync client.
MOVE - Transfers files from the source to the destination and deletes them from the source.
Overwrites files with the same name.
Only affects albums created by the sync client.
Choosing a Target Folder
After choosing the direction and mode for your cloud sync task, select the remote Google Photos folder that rclone targets. Each folder option has specific file management and structure requirements due to API restrictions. Cloud sync tasks cannot target the root folder (/).
Folder
Recommended
Direction
Description
/album
Yes
Push or Pull
Use this folder for push tasks or to organize media into albums. Only albums created by the TrueNAS cloud sync client are accessible. Pull returns only items in these albums; push uploads work as expected. All local files must be in child directories (albums) under the dataset.
/media/all
No
Pull
API restrictions prevent reading your full Google Photos library. Only items in app-created albums are accessible. Do not use this option for full-library sync.
/upload
No
Push
Temporary upload location. Files pushed here are not sorted into albums, metadata can be lost, and repeated sync tasks can produce duplicates or unstable filenames. Use only for temporary transfers.
Selecting the Dataset and Organizing Files
Select a TrueNAS local dataset or create a new one to use as the source or destination.
Creating a Dataset
To create a basic dataset, go to Datasets.
Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Select the Dataset Preset option you want to use. Options are:
Generic for non-SMB share datasets such as iSCSI and NFS share datasets.
Also use for datasets for containers, virtual machines, and other datasets not associated with application storage.
Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
SMB for datasets optimized for SMB shares.
Apps for datasets optimized for application storage.
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset.
When no ACL exists to inherit, TrueNAS calculates one that grants full control to the owner@, group@, members of the builtin_administrators group, and domain administrators.
TrueNAS grants modify control to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
ACL Settings for Dataset Presets
ACL Type
ACL Mode
Case Sensitivity
Enable atime
Generic
POSIX
n/a
Sensitive
Inherit
SMB
NFSv4
Restricted
Insensitive
Inherit
Apps
NFSv4
Passthrough
Sensitive
Off
Multiprotocol
NFSv4
Passthrough
Sensitive
Off
If creating an SMB or multi-protocol (SMB and NFS) share, the dataset name value auto-populates the share name field with the dataset name.
If configuring a pool to deploy applications, the system automatically creates the ix-apps dataset for Docker storage, but we recommend creating separate datasets for application data storage.
If you want to store data by application, create the dataset(s) first, then deploy your application.
When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options.
For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always.
Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
The Case Sensitivity setting in Advanced Options is not editable after you save the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
For push tasks, organize files in the local dataset so they map to albums created by the TrueNAS cloud sync client. For pull tasks, the Google Photos API only provides access to items in albums created by the sync client.
Full-library pulls or shared albums are not accessible.
Configure your dataset accordingly based on your chosen direction, mode, and target folder.
Creating the API Credentials
Tokens generated before March 31, 2025 do not provide full access to your Google Photos library under the new API rules. When creating credentials, ensure that your OAuth client and token are intended for use with albums created by the TrueNAS cloud sync client.
Only these app-created albums can be accessed for push or pull tasks.
On the Google API dashboard, click the dropdown menu to the right of the Google Cloud logo and select your project.
If you do not have a project, click NEW PROJECT and enter a value in Project name, Organization, and Location.
Click Create.
Enter photos library api in the search bar, then select Photos Library API and click ENABLE.
This enables the API for your project
Access remains limited to albums created by the TrueNAS cloud sync client.
Can I leave the app in testing mode?
You can leave the app in testing mode, but testing app credentials expire after seven days.
Cloud sync tasks fail when testing mode credentials expire.
Create Credentials
Click Credentials on the left menu, then click + CREATE CREDENTIALS and select OAuth client ID.
Download rclone for your client OS and open it in a command line utility following the rclone installation instructions.
The example photos in this article use Powershell in Windows OS.
Enter rclone config, then enter n to create a new remote.
Enter a name for the new remote, then enter the number from the list corresponding to Google Photos.
Enter the client id and secret you saved when you created the Google Photos API credentials, then enter false or press Enter to allow the Google Photos backend to request full access.
Note: After March 31, 2025, full-library access is no longer possible under the Google Photos API.
Even if rclone requests full access, it only sees albums created by the TrueNAS cloud sync client.
Enter y to authenticate rclone using the web browser.
A browser window opens to authorize rclone access.
Click Allow.
In the command line, enter y to confirm rclone uploads media items with full resolution and complete the configuration.
Only albums created by the TrueNAS cloud sync client are accessible.
Copy and save the type, client_id, client_secret, and token, then enter y to save the new remote.
Select Google Photos as the Provider and enter a name.
Paste the Google Photos API client ID and client secret in the OAuth Client ID and OAuth Client Secret fields.
Paste your rclone token into the Token field.
Note: Due to API restrictions, these credentials only provide access to albums created by the TrueNAS cloud sync client
Full-library or shared-album access is not possible.
Click Verify Credential to ensure the credentials are valid, then click Save.
Creating the Cloud Sync Task
Go to Data Protection > Cloud Sync Tasks and click Add. The Cloud Sync Task Wizard opens.
Select the Google Photos backup credentials from the Credentials dropdown list.
Click Verify Credential to ensure the credentials are valid then click Next.
Select the Direction as PUSH or PULL and select the Transfer Mode as SYNC, COPY, or MOVE.
Select the Google Photos location to back up data to or from in Folder.
Browse to and select the album folder or enter /album.
Note: Pull tasks only access albums created by the TrueNAS cloud sync client.
Full-library pulls or shared albums are not accessible.
Select the local dataset in Directory/Files.
This is the dataset sent to Google Photos for push tasks or the write destination for pull tasks.
Push tasks containing media files saved to the local dataset root level fail with the error: Failed to sync: can’t upload files here.
Save files to child directories, not to the root level of the TrueNAS dataset.
Directories under the local dataset correspond to albums created by the TrueNAS cloud sync client in Google Photos.
Enter a Description for the cloud sync task.
Select the time to run the task from the Schedule options.
Click Save to add the task.
TrueNAS adds the task to the Cloud Sync Task widget with the status Pending, until the task runs on schedule.
Click Dry Run to test the task by connecting to Google Photos and simulating transferring a file.
During a dry run, TrueNAS sends or receives no data.
A dry run can report successful even for a task that fails to transfer data due to misconfiguration
Click the vertical ellipses more_vert on the task and select Run Job to start the cloud sync task immediately.
Troubleshooting
If a Google Photos cloud sync task fails, go to Data Protection and click the FAILED status in State on the Cloud Sync Tasks widget.
Review the logged error messages.
Common error messages for failed Google Photos tasks include:
Failed to copy: can't upload files here
Problem: A push task attempts to upload files to the root level / folder or the /upload folder.
Solution: Reconfigure the push task to target the /album folder and organize your files into child directories (albums).
Directories under the local dataset correspond to albums the TrueNAS cloud sync client creates in Google Photos.
Only albums the sync client creates are accessible to cloud sync tasks.
Pulling from the root directory is not allowed. Please, select a specific directory
Problem: A pull or push task targets the root level / folder.
Solution: Change the target folder to /album.
Pull tasks transfer only media that exist in albums created by the TrueNAS cloud sync client.
Full-library pulls and shared albums are not accessible via the API.
Do not rely on /media/all for a full export.
Failed to copy: directory not found
Problem: A pull task targets the /upload folder.
Solution: The /upload folder functions as a temporary upload queue.
rclone cannot pull from /upload.
Change the target folder to /album and organize files accordingly.
Remember that only albums created by the TrueNAS cloud sync client are accessible for pull tasks.
If a pull task runs but some or all files never appear in the local dataset, those files are not in albums created by the TrueNAS cloud sync client and the API does not expose them to the sync client.
To get originals from Google Photos you can:
Export your account via Google Takeout (download the archive and import the files into TrueNAS).
Download desired photos directly from Google Photos and copy them into your TrueNAS dataset.
If you want the sync client to manage media going forward, create and sync albums via TrueNAS.
Those albums then remain accessible to the TrueNAS cloud sync client.
Configuring Rsync Tasks
Rsync provides fast incremental data transfer to synchronize files between a TrueNAS system and a remote system.
The Push function copies data from TrueNAS to a remote system.
The Pull function copies data from a remote system to the TrueNAS local host system and stores it in the dataset defined in the Path field.
There are two ways to connect to a remote system and run an rsync task:
Module mode requires adding an rsync app to the remote system, configuring a module on that system, and then entering it in the rsync task in TrueNAS.
SSH mode has two connection options:
SSH private key stored in the user’s home directory
SSH connection for the keychain
Setting options change based on the SSH connection option selected.
Set up a home directory for the remote system administrator on the remote system.
Note the path to where home directories are stored to enter on the local host TrueNAS.
If the remote system is also a TrueNAS, go to Credentials, select Users to see the list of users.
Select the administration user and click Edit.
If creating a new administration user for rsync functions, click Add.
See Managing Users for more information.
Take note of the path to the home directory to use in setting up the connection.
Add an SSH connection for the remote server on the local TrueNAS host system.
Adding a remote TrueNAS system
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
TrueNAS allows configuring multiple admin users on the system. All admin users configured in the TrueNAS system show in the rsync task User dropdown list.
Adding an Rsync Task Using SSH
Enabled SSH on both the local host TrueNAS, and the remote destination system.
You can use the SSS connection created in Setting Up an SSH Connection or create a new connection while configuring the rsync task.
Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Enter or browse to the dataset or folder to sync with the remote server.
Use the arrow_right to the left of the /mnt folder and each folder listed on the tree to expand and browse through, then click on the name to populate the path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select the administration user for the local host TrueNAS system from the User dropdown. This is the user account to perform the rsync task.
The user must have read/write permissions for the local dataset.
Set the Direction for the rsync task.
Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.
Set the Rsync Mode to SSH, and then select the connection method from the Connect using dropdown list.
Settings fields for the selected connection type show.
If selecting SSH private key stored in the user home directory, the public key for the SSH connection must be alread be saved in the home directory for the admin user.
If selecting SSH connection from the keychain, choose either the existing SSH credential from the SSH Connection dropdown list or select Add New to open the New SSH Connection configuration screen. See Using an SSH Connection below for more information.
If the connection fails, the system lets you know what is wrong so you can correct the issue with the connection.
Enter the full path to the dataset on the remote server in Remote Path. The maximum path length is 255 characters.
To confirm the remote server is reachable and the path exists, leave Validate Remote Path selected.
Select a schedule for when to run this task and any other options you want to use.
If you need a custom schedule, select Custom to open the advanced scheduler window.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Leave Enabled selected. Clear the checkbox to disable the task without deleting the configuration.
Click Save. The system verifies the SSH connection and adds the task to the Rsync Tasks widget.
To run the rsync task at any time, select it on the Rsync Tasks widget, click on the vertical ellipses more_vert for the task, and select the Run Now.
Using an SSH Connection
The TrueNAS UI allows users to select an existing SSH connection or to create a new connection while configuring the task.
The New SSH Connection screen opened using the Add New option in the rsync task and accessed while on the Backup Credentials screen are essentially the same and show the same setting options.
To set up a new SSH connection before adding an rsync task, go to Credentials > Backup Credentials and click Add on the SSH Connections widget.
See Adding SSH Credentials for more information on adding SSH Connections and key pairs.
To add a new connection while configuring the rsync task on the Add Rsync Task screen, set the mode to SSH, select SSH connection for the keychain, and then select Add New on the SSH Connection dropdown list. The New SSH Connection screen opens.
Adding an SSH Connection to a TrueNAS System
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Adding an SSH Connection to a Non-TrueNAS System
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select Manual from the Setup Method dropdown list.
a. Enter a host name or host IP address for the remote non-TrueNAS system as a valid URL.
An IP address example is https://10.231.3.76.
This is a required field.
b. Enter the port number of the remote system to use for the SSH connection.
c. Enter a user name for logging into the remote system in Username.
d. Select the private key from the SSH key pair that you use to transfer the public key on the remote NAS from the Private Key dropdown.
e. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate the Remote Host Key field.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection widget.
To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.
Next, set up a home directory for the system administrator on the remote system if one does not already exist.
If the remote system is a TrueNAS, edit the user to add the public key. In TrueNAS, go to Users, click Edit, and paste the key into the pubic key field.
After adding the SSH connection, go to System > Services to turn on the SSH service.
We don’t recommend leaving the SSH service turned on when not in use for security hardening.
Turn it on before the rsync task is scheduled to run, then off again after the task completes to keep your system secured.
(Optional) To automatically start or restart the SSH service after a system restart, select this option.
Enable the SSH service on the remote system according to the configuration process for a non-TrueNAS system.
Setting Up an Rsync Task Using Module Mode
Before you create an rsync task in module mode, you must define at least one module per rsyncd.conf(5) on the remote rsync server.
The Rsync Daemon application is available in situations where configuring TrueNAS as an rsync server with an rsync module is necessary.
After configuring the remote server with rsync and a module, configure the rsync task in TrueNAS.
Setting Up an Rsync Module
If the non-TruNAS remote server includes an rsync service, make sure it is turned on. To configure a module on the remote server:
Create a dataset.
Write down the host and path to the data on the remote system you plan to sync with.
Create an rsync module.
If the remote system is not a TrueNAS and has an rsync app installed, create a module according to the configuration process for that app and system.
If the remote system is not a TrueNAS, install an rsync app, such as Rsyncd, and configure it per the instructions for the app and your remote non-TrueNAS system.
If the remote system is another TrueNAS, install an rsync app.
Debian-based TrueNAS systems include the Rsync Daemon app in the Community app catalog.
Install the app and use it to configure a module.
Configuring a module in the TrueNAS RsyncD app
To create the module, you need the IP address or host name of your TrueNAS (host) server.
The host server is configured with the rsync task that transfers your data to the remote server.
When the remote system is a Debian-based TrueNAS system, go to Apps > Discover Apps and search for the Rsync Daemon app.
Click on the widget, and then click Install to open the installation wizard.
To add a module, click Add to the right of Rsync Modules, then:
Assign a name. This name is added in the Add Rsync Task screen on your TrueNAS system when you set up a task using Module in the Rsync Mode field.
(Optional) Enter a comment to help you remember the purpose of this module or where it is used.
Select the host path for the rsyncd app.
You can use Create Dataset to add a new dataset, and repeat to add a new child dataset if not selecting an existing dataset.
Set the level of access by selecting the option on the Access Mode dropdown list.
(Optional) Add IP addresses to the Host Allow or Host Deny options if you want to narrow access to this module.
Take note of the name of the module and the host path to it or use in later when you add the rsync task in your TrueNAS system.
Complete the rest of the app configuration to suit your use case, and click Install.
The app shows in the TrueNAS UI on the Applications screen as Running when fully deployed.
Adding an Rsync Task Using Module Mode
To configure the rsync task using module mode, you need:
The name of the module
The IP address or host name for the remote server
The path to the dataset
Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Enter or browse to and select the dataset or folder to sync with the remote server.
Clicking on the dataset name populates the path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select the admin account to perform the rsync task on the User dropdown list.
The user must have permissions to run an rsync on the remote server and read/write permission for the local dataset.
Set the Direction for the rsync task.
Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.
Set the Rsync Mode to Module.
The module settings fields show.
Enter the remote host name or IP in Remote Host.
Set the schedule for when to run this task, and any other options you want to use.
If you need a custom schedule, select Custom to open the advanced scheduler window.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Leave the Enabled selected to enable the task.
Clear the checkbox to disable the task without deleting the configuration.
Click Save.
You can run the rsync task by clicking then the Run Nowplay_arrow icon for the rsync task on the Rsync Task widget.
Adding Periodic Snapshot Tasks
Periodic snapshot tasks allow you to schedule creating read-only versions of pools and datasets at a given point in time. You can also access VMWare snapshot integration and TrueNAS storage snapshots from the Periodic Snapshot Tasks widget.
How should I use snapshots?
Snapshots do not make copies of the data so creating one is quick and if little data changed, they take very little space.
It is common to take frequent snapshots as soon as every 15 minutes, even for large and active pools.
A snapshot where no files changed takes no storage space, but as files changes happen, the snapshot size changes to reflect the size of the changes.
In the same way as all pool data, after deleting the last reference to the data you recover the space.
Snapshots keep a history of files, providing a way to recover an older copy or even a deleted file.
For this reason, many administrators take snapshots often, store them for a period of time, and store them on another system, typically using the Replication Tasks function.
Such a strategy allows the administrator to roll the system back to a specific point in time.
If there is a catastrophic loss, an off-site snapshot can restore data up to the time of the last snapshot.
Creating a Periodic Snapshot Task
Create the required datasets or zvols before creating a snapshot task.
Go to Data Protection > Periodic Snapshot Tasks and click Add.
First, choose the dataset (or zvol) to schedule as a regular backup with snapshots, and how long to store the snapshots.
Next, define the task Schedule.
If you need a specific schedule, choose Custom and use the Advanced Scheduler section below.
Configure the remaining options for your use case.
For help with naming schema and lifetime settings refer to the sections below.
Click Save to save this task and add it to the list in Data Protection > Periodic Snapshot Tasks.
You can find any snapshots taken using this task in Storage > Snapshots.
To check the log for a saved snapshot schedule, go to Data Protection > Periodic Snapshot Tasks and click on the task. The Edit Periodic Snapshot Tasks screen displays where you can modify any settings for the task.
Using the Advanced Scheduler
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Using Naming Schemas
The Naming Schema determines how automated snapshot names generate.
A valid schema requires the %Y (year), %m (month), %d (day), %H (hour), and %M (minute) time strings, but you can add more identifiers to the schema too, using any identifiers from the Python strptime function.
For Periodic Snapshot Tasks used to set up a replication task with the Replication Task function:
You can use custom naming schema for full backup replication tasks. If you are going to use the snapshot for an incremental replication task, use the default naming schema.
This uses some letters differently from POSIX (Unix) time functions.
For example, including %z (time zone) ensures that snapshots do not have naming conflicts when daylight time starts and ends, and %S (second) adds finer time granularity.
When referencing snapshots from a Windows computer, avoid using characters like colon (:) that are invalid in a Windows file path.
Some applications limit filename or path length, and there might be limitations related to spaces and other characters.
Always consider future uses and ensure the name given to a periodic snapshot is acceptable.
Setting Snapshot Lifetimes
A snapshot lifetime value defines how long the snapshot schedule ignores that snapshot when it looks for obsolete snapshots to remove.
For example, defining a lifetime of two weeks on a snapshot created after a weekly snapshot schedule runs can result in that snapshot actually being deleted three weeks later.
This is because the snapshot has a timestamp and defined lifetime that preserves the snapshot until the next time the scheduled snapshot task runs.
TrueNAS also preserves snapshots when at least one periodic task requires it.
For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for 3 years.
Each has an hourly snapshot taken.
After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task.
These snapshots get destroyed at the end of 3 years.
Creating VMWare Snapshots
Use this procedure to create ZFS snapshots when using TrueNAS as a VMWare datastore.
You must have a paid edition of VMWare ESXi to use the TrueNAS VMWare Snapshots feature.
ESXi free has a locked (read-only) API that prevents using TrueNAS VMWare Snapshots.
This tutorial uses ESXi version 8.
When creating a ZFS snapshot of the connected dataset, VMWare automatically takes a snapshot of any running virtual machines on the associated datastore.
VMware snapshots can integrate VMware Tools, making it possible to quiesce VM snapshots, sync filesystems, take shadow copy snapshots, and more.
Quiescing snapshots is the process of bringing VM data into a consistent state, suitable for creating automatic backups.
Quiesced snapshots can be file-system consistent, where all pending data or file-system changes complete, or application consistent, where applications complete all tasks and flush buffers, prior to creating the snapshot.See Manage Snapshots from VMWare for more information.
VM snapshots are included as part of the connected Virtual Machine File System (VMFS) datastore and stored as a point-in-time within the scheduled or manual TrueNAS ZFS snapshot of the data or zvol backing that VMWare datastore.
The temporary VMware snapshots are automatically deleted on the VMWare side, but still exist in the ZFS snapshot and are available as stable restore points.
TrueNAS Enterprise
TrueNAS Enterprise customers with TrueNAS 12.0 and newer and TrueNAS 22.12.4 (Bluefin) and newer deployed can access the iXsystems TrueNAS vCenter plugin.
This activates management options for TrueNAS hardware attached to vCenter Server and enables limited management of TrueNAS systems from a single interface.
Please contact TrueNAS Enterprise Support to learn more and schedule a time to deploy or upgrade the plugin.
Contacting TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Before using TrueNAS to create VMWare snapshots, configure TrueNAS to present a VMFS datastore or NFS export to your ESXi host(s) (this tutorial uses iSCSI) and then create and start your VM(s) in ESXi.
Virtual machines must be running for TrueNAS to include them in VMWare snapshots, because powered-off virtual machines are already in a consistent state
Go to Datasets and click Add Zvol to create a dedicated zvol for VMWare. This tutorial uses virtual/vmware/zvol-01.
Create an iSCSI share.
Go to Shares and click Wizard on the Block (iSCSI) Shares Targets widget.
a. Enter a name for the share. For example, vmware. Select Device for Extent Type and select the zvol from the Device dropdown.
Leave Sharing Platform set to VMware and Target set to Create New, then click Next.
b. Set Portal to Create New.
You can leave Discovery Authentication Method set to NONE, or select CHAP or Mutual CHAP and enter a Discovery Authentication Group ID.
Click Add next to IP Address and select either 0.0.0.0 for IPv4 or :: for IPv6 to listen on all ports.
c. Leave Initiators blank and click Save.
In the VMWare ESXi Host Client, go to Storage, select Adapters, and then click Software iSCSI to configure the iSCSI connection.
c. Click Rescan to discover the iSCSI initiator.
ESXi automatically adds static targets for discovered initiators.
Click Software iSCSI again to confirm.
d. Go to Devices and click Rescan to discover the shared storage. ESXi adds the TrueNAS iSCSI disk to the list of devices.
Go to Datastores and click New Datastore to create a new VMFS datastore using the TrueNAS device.
Then go to Virtual Machines and create your new virtual machine(s), using the new datastore for storage.
Creating a VMWare Snapshot
To configure TrueNAS to create VMWare snapshots, go to Data Protection and click the VMware Snapshot Integration button in the Periodic Snapshot Tasks widget to open the VMWare Snapshots screen.
Note that you can organize information in the columns of the table(s) below by clicking on each column title. This allows you to toggle the information between a descending an ascending order.
You must follow the exact sequence to add the VMware snapshot or the ZFS Filesystem and Datastore fields do not populate with options available on your system.
If you click in ZFS Filestore* or Datastores before you click Fetch Datastores the creation process fails, the two fields do not populate with the information from the VMWare host, and you must exit the add form or click Cancel and start again.
Enter the IP address or host name for your VMWare system in Hostname.
Enter the user credentials on the VMware host with ‘Create Snapshot’ and ‘Remove Snapshot’ permissions in VMware.
See Virtual Machine Snapshot Management Privileges from VMware for more information.
Click Fetch Datastores. This connects TrueNAS to the VMWare host and populates the ZFS Filesystem and Datastore dropdown fields.
Make sure the correct TrueNAS ZFS dataset or zvol matching the VMware datastore is populated.
Select the TrueNAS dataset from the ZFS Filesystem dropdown list of options.
Select the VMFS datastore from the Datastore dropdown list of options.
Click Save.
The saved snapshot configuration appears on the VMware Snapshots screen.
State indicates the current status of the VMware connection as PENDING, SUCCESS, or ERROR.
Create a new periodic snapshot task for the zvol or a parent dataset.
If there is an existing snapshot task for the zvol or a parent dataset, VMWare snapshots are automatically integrated with any snapshots created after the VMWare snapshot is configured.
Expand the configured task on the Periodic Snapshot Tasks screen and ensure that VMware Sync is true.
Reverting to a ZFS Snapshot in VMWare ESXi
To revert a VM using a ZFS snapshot, first clone the snapshot as a new dataset in TrueNAS, present the cloned dataset to ESXi as a new LUN, resignature the snapshot to create a new datastore, then stop the old VM and re-register the existing machine from the new datastore.
Clone the snapshot to a new dataset.
a. Go to Data Protection and click Snapshots on the Periodic Snapshot Tasks widget and locate the snapshot you want to recover and click on that row to expand details.
b. Click Clone to New Dataset.
Enter a name for the new dataset or accept the one provided then click Clone.
Share the cloned zvol to VMWare using NFS or iSCSI (this tutorial uses iSCSI).
a. Go to Shares and click Block (iSCSI) Shares Targets to access the iSCSI screen.
b. Click Extents and then click Add to open the Add Extent screen.
c. Enter a name for the new extent, select Device from the Extent Type dropdown, and select the cloned zvol from the Device dropdown.
Edit other settings according to your use case and then click Save.
d. Click Associated Targets and then click Add to open the Add Associated Target screen.
e. Select the existing VMWare target from the Target dropdown.
Enter a new LUN ID number or leave it blank to automatically assign the next available number.
Select the new extent from the Extent dropdown and then click Save.
Go to Storage > Adapters and click Rescan to discover the new LUN.
Then go to the Devices tab and click Rescan again to discover VMFS filesystems on the LUN.
At this point, ESXi discovers the cloned device snapshot, but is unable to mount it because the original device is still online.
Resignature the snapshot so that it can be mounted.
a. Access the ESXi host shell using SSH or a local console connection to resignature the snapshot
b. Go back to Storage > Devices in the ESXi Host Client UI and click Refresh.
The mounted snapshot appears in the list of devices.
Select the VM(s) you want to revert and click Next.
e. Review selections on the Ready to complete screen/ If correct, click Finish.
Start the new VM(s) and verify functionality, then delete or archive the previous VM(s).
Copy or migrate the VMware virtual machine to the original, non-snapshot datastore.
Replication Tasks
TrueNAS replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their TrueNAS system as a way to back up stored data.
When properly configured and scheduled, replication takes regular snapshots of storage pools or datasets and saves them in the destination location either on the same system or a different system.
Setting Up a Simple Replication Task Overview
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The sections below provide overviews on what to do before you begin configuring a replication task.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
Contents
Setting Up a Local Replication Task: Provides instructions on adding a replication task using different pools or datasets on the same TrueNAS system.
A local replication creates a ZFS snapshot and saves it to another location on the same TrueNAS system using different pools, datasets, or zvols.
This allows users with only one system to take quick data backups or snapshots of their data when they have only one system.
If you have only one pool, create a dataset in that pool to store the replication snapshots. You can use a zvol for this purpose.
If configuring local replication on a system with more than one pool, create a dataset for the replicated snapshots on one of those pools.
While we recommend regularly scheduled replications to a remote location as the optimal backup scenario, local replication is useful when a remote backup location is available or when a disk is in immediate danger of failure.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused.
Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume.
Do not assign capacity that exceeds what is required for TrueNAS to operate properly. For more information, see TrueNAS Hardware Guide for CPU, memory and storage capacity information.
Setting up replication tasks as an admin user has a few differences from setting up replication tasks when logged in as root.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
To configure the local replication task, follow the instructions in the section below.
Configuring a Local Replication Task
Use the Replication Task Wizard to create and copy ZFS snapshots to another system, which streamlines creating simple replication tasks.
After creating the replication task, TrueNAS automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list.
This loads the configuration settings for that task into the wizard, where you can make changes such as assigning it a different destination, setting a new schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task originally loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify that the destination dataset where you plan to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
After completing the basic preparation steps in the section above, go to Data Protection > Replication and click Add to open the replication wizard.
To configure advanced settings, click Advanced Replication Creation to open the Add Replication Task screen before you enter any settings in the wizard.
Refer to the Advanced Replication Tasks for configuration instructions using the Add Replication Task screen.
On the What and Where replication wizard screen:
Select an existing replication task from the Load Previous Replication Task dropdown.
If one does not exist, leave this set to the default, which is the double dashes.
Select the source and destination locations. You can select these in any order.
Local replication sends or receives data from one storage location to another on the same (local) system.
Remote replication sends data to or receives data from a storage location on a different (remote) TruNAS system.
To set up a local replication in the replication wizard, set both Source Location and Destination Location to On this System.
To set up a push remote replication in the replication wizard, set the Source Location to On this System and set Destination Location to On a Different System.
To set up a pull remote replication in the replication wizard, set the Source location to On a Different System and the Destination Location to On this System.
Setting either source or destination to On a Different System automatically sets the other to On This System. You cannot set both to On a Different System.
Click on Source Location or Destination Location to show additional setting options and the file browser. Additional settings shown are based on the selection.
Configure the settings for local replication after selecting On This System in either Source Location or Destination Location.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
a. Use the file browser for Source Location to browse to the location of the dataset with the data to replicate.
Clicking on the dataset(s) populates the Source path.
When setting up the Source, you can select multiple sources or manually type the names into the Source field.
b. Use the file browser for Destination Location to browse to the location of the pool or dataset to receive the replicated snapshots.
Clicking on the dataset populates Destination path.
When setting up the Destination, the Destination path allows adding a directory/dataset by entering /name, where /name is the name of a directory or dataset. The source path does not allow adding a new dataset/directory.
You can use zvols as a local replication destination. Add a name to the end of the path to create a new dataset in that location.
c. (Optional) Enter a name for the snapshot in Task Name.
TrueNAS populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
(Optional) Select Recursive to replicate all snapshots contained within the parent dataset and any child datasets.
(Optional) Accept the default name in Task Name, or enter a name of your choosing.
TrueNAS populates this field with a default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to show the scheduling options.
Select the schedule and snapshot retention lifetime.
LeaveReplication Schedule set to Run On a Schedule and select the option in the Schedule dropdown.
Select Run Once to set up a replication task you run one time.
Select the Destination Snapshot Lifetime option to specify how long TrueNAS should store copied snapshots in the destination dataset before TrueNAS deletes it.
Same as Source is selected by default.
Select Never Delete to keep all snapshots until you delete them manually.
Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click Save.
The task shows on the Replication Task widget with the status as PENDING.
Select Run Now if you want to run the task immediately.
Click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset.
Click Show extra columns to add more information columns to the table, such as the date created, which can help you locate a specific snapshot or enter part of or the full name in the search field to narrow the list of snapshots.
Remote replication backs up data stored on an originating TrueNAS system to a second remote destination TrueNAS system.
TrueNAS allows scheduling a one-time or regularly scheduled ZFS snapshot of data stored in pools, datasets, or zvols, and saves them in another system.
With the implementation of the administration user and role-based permissions, setting up replication tasks as an admin user has a few differences from those set up when logged in as the root user.
Setting up remote replication when logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
To configure the remote replication task, follow the instructions in the section below.
Creating a Remote Replication Task
Use the Replication Task Wizard to create and copy ZFS snapshots to another system, which streamlines creating simple replication tasks.
After creating the replication task, TrueNAS automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list.
This loads the configuration settings for that task into the wizard, where you can make changes such as assigning it a different destination, setting a new schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task originally loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify that the destination dataset where you plan to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
After completing the basic preparation steps in the section above, go to Data Protection > Replication and click Add to open the replication wizard.
To configure advanced settings, click Advanced Replication Creation to open the Add Replication Task screen before you enter any settings in the wizard.
Refer to the Advanced Replication Tasks for configuration instructions using the Add Replication Task screen.
On the What and Where replication wizard screen:
Select an existing replication task from the Load Previous Replication Task dropdown.
If one does not exist, leave this set to the default, which is the double dashes.
Select the source and destination locations. You can select these in any order.
Local replication sends or receives data from one storage location to another on the same (local) system.
Remote replication sends data to or receives data from a storage location on a different (remote) TruNAS system.
To set up a local replication in the replication wizard, set both Source Location and Destination Location to On this System.
To set up a push remote replication in the replication wizard, set the Source Location to On this System and set Destination Location to On a Different System.
To set up a pull remote replication in the replication wizard, set the Source location to On a Different System and the Destination Location to On this System.
Setting either source or destination to On a Different System automatically sets the other to On This System. You cannot set both to On a Different System.
Click on Source Location or Destination Location to show additional setting options and the file browser. Additional settings shown are based on the selection.
Configure the settings for remote replication after selecting On a Different System in either Source Location or Destination Location.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
a. Select an existing SSH connection from the dropdown list or select Add New to open the New SSH Connection screen.
If you created the SSH connection in the section above, select it.
When adding a new connection in the wizard, if TrueNAS detects other configuration issues, such as the user not correctly set up, an error indicating what the issue is shows in the wizard.
Exit the replication wizard to correct issues, then return to the wizard to begin the task configuration again.
After completing the replication wizard task creation, where you added a new SSH connection in the wizard, return to the remote system user configuration to add the new public key for the SSH connection to the admin user configuration.
b. Use the file browser to browse and select the parent dataset with the data to replicate. Clicking on the dataset(s) populates the path.
When setting up the Source, you can select multiple sources or manually type the names into the Source field.
When setting up the Destination, the Destination path allows adding a directory/dataset by entering /name, where rname is the name of a directory or dataset. The source path does not allow adding a new dataset/directory.
You cannot use zvols as a remote replication destination. Add a name to the end of the path to create a new dataset in that location.
c. Select Use Sudo for ZFS Commands.
A dialog opens prompting you to add this capability. Selecting this removes the need to issue the cli zfs allow command in Shell on the remote system.
Click Use Sudo for ZFS Commands. If the dialog closes before clicking this option, you can select this option on the wizard screen.
(Optional) Select Replicate Custom Snapshots, then leave the default value in Naming Schema.
If you know how and want to enter the schema, enter it in Naming Schema.
A snapshot naming schema identifies the snapshots to replicate, and might be required by the remote system.
A naming schema is a string of strftime(3) %Y, %m, %d, %H, and %M variables that name custom snapshots you want to replicate.
Separate entries by pressing Enter. The number of snapshots matching the pattern entered shows on a dropdown list.
Selecting Matching regular expression does not automatically destroy snapshots, whereas selecting Matching naming schema does.
When using a regular expression, the snapshots on the destination host are not automatically destroyed when they are destroyed on the source host due to the snapshot lifetime.
Snapshots on the destination host display as “Will not be destroyed automatically” and do not display with a retention period.
Use naming schema for these.
(Optional) Select Recursive to replicate all snapshots contained within the parent dataset and any child datasets.
(Optional) Accept the default name in Task Name, or enter a name of your choosing.
TrueNAS populates this field with a default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge.
To make it easier to find the snapshot, give it a name that is easy to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to show the scheduling options.
Select the schedule and snapshot retention lifetime.
LeaveReplication Schedule set to Run On a Schedule and select the option in the Schedule dropdown.
Select Run Once to set up a replication task you run one time.
Select the Destination Snapshot Lifetime option to specify how long TrueNAS should store copied snapshots in the destination dataset before TrueNAS deletes it.
Same as Source is selected by default.
Select Never Delete to keep all snapshots until you delete them manually.
Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click Save.
The task shows on the Replication Task widget with the status as PENDING.
Select Run Now if you want to run the task immediately.
Click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset.
Click Show extra columns to add more information columns to the table, such as the date created, which can help you locate a specific snapshot or enter part of or the full name in the search field to narrow the list of snapshots.
Select the Setup Method from the dropdown list. Leave this set to Semi-Automatic for a connection to another TrueNAS system.
Enter the remote TrueNAS host name or IP address as a URL in TrueNAS URL.
Enter the administration user (i.e., root or admin) that logs into the remote system with the web UI in Admin Username.
Enter the password in Admin Password.
If using a TrueNAS 13.0-U6.x system as the remote server, the remote user is always root.
When using an earlier TrueNAS 22.12.1 system or if you installed TrueNAS as the root user and then created an admin user after initial installation, you must verify that the admin user is correctly configured.
Enter the administration user (i.e., root or admin) for the remote system SSH session.
If you clear root as the the user and type any other name the Enable passwordless sudo for ZFS commands option displays.
This option does nothing, so leave it cleared.
Select Generate New from the Private Key dropdown list.
(Optional) Enter a new value in seconds for the Connection Timeout if you want to change the defaults.
Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.
After creating a new SSH connection, go to Credentials > Backup Credentials > SSH Connections, click Edit to copy the public key, then edit the remote user configuration by pasting this in the Public SSH Key field.
Using SSH Transfer Security
We always recommend using encryption for SSH transfer security.
In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer.
However, the data is completely unprotected from eavesdropping.
Choosing No Encryption for the task is less secure but faster.
This method uses common port settings but you can override these when using the Advanced Replication Creation options or by editing the task after creating it in the wizard.
TrueNAS advanced replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets, or zvols on their TrueNAS system as a way to back up stored data.
When properly configured and scheduled, local or remote replication using the Advanced Replication Creation option takes regular snapshots of storage pools or datasets and saves them in the destination location on the same or another system.
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The Advanced Replication Creation option opens the Add Replication Task screen.
This screen provides access to the same settings found in the replication wizard, but has more options to specify:
Full file system replication
Stream compression
Replication speed
Attempts to replicate data before the task fails
Block size for data sent
Log level verbosity
You can also:
Change encrypted replication to allow an unencrypted dataset as the destination
Create replication from scratch
Include or exclude replication properties
Replicate specific snapshots that match a defined creation time.
Prevent the snapshot retention policy from removing source system snapshots that failed
With the implementation of the local administrator user to replace the root login, there are a few differences between setting up replication tasks as an admin user than with setting up replication tasks when logged in as root.
Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Setting Up a Replication Task Overview
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote.
It also covers the related steps you should take prior to configuring a replication task.
Setting Up a Simple Replication Task Overview
Replication from one pool or dataset to another pool or dataset on the TrueNAS system is called local replication.
Replication from the TrueNAS system to another TrueNAS or other backup server is called remote replication.
Both local and remote replication can involve encrypted pools or datasets.
The sections below provide overviews on what to do before you begin configuring a replication task.
Before You Begin Local Replication
Local replication does not require the admin user to have SSH access, a home directory, or sudo command permissions.
Setting options change based on the source and destination selections. Replicating to or from a local source does not require an SSH connection.
Set up the data storage for replicated snapshots. Go to Datasets to add a dataset to store the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source file browser in the replication wizard or the Add Replication Task configuration screen. Use the file browser to select the existing dataset on the system where you want to store replicated data.
The Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system, but you cannot create a directory for a dataset selected in the Source file browser.
Create a periodic snapshot task of the storage locations to back up.
TrueNAS typically creates a periodic snapshot task right before it performs the replication task if one is not already created for the task.
You might need to refresh the screen cache to see the task listed in the Periodic Snapshot Task widget.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard.
If you want to configure a replication task using advanced setting options on the Add Replication Task screen, click Advanced Replication Creation before entering settings in the replication wizard.
Settings do not carry over from the wizard to the advanced task creation screen, and TrueNAS shows the dialog where you must confirm you want to leave the wizard screen before it opens.
Immediately switching to the advanced screen does not show the confirmation dialog, and you do not have to enter your settings again.
Before You Begin Remote Replication
Remote replication requires that the admin user on the remote system has SSH access, the SSH connection public key added, a home directory, and sudo command permission. The SSH service must be on when running the periodic snapshot and replication tasks.
Setting options change based on the source and destination selections.
When setting up remote replication:
Set up the data storage for replicated snapshots. On the remote system, go to Datasets to add a dataset for the replicated data (snapshots).
TrueNAS does not allow you to create a new dataset using the Source or Destination file browsers in the replication wizard or the Add Replication Task configuration screen.
After selecting the existing dataset where you want to store replicated data, the Destination file browser allows you to specify (create) a directory in an existing dataset on a local or remote system. You cannot create a directory for a dataset selected in the Source file browser.
Add a home directory for the admin user on the local and the remote systems.
The Home Directory path on the Add User or Edit User screen must be set to something other than /var/empty.
Click on the Home Directory setting to show the options.
Select Create Home Directory, then use the file browser to select an existing dataset or use Create Dataset after selecting the parent dataset to create a new dataset for home directories.
See Managing Users for more information on home directories, SSH access, and sudo commands.
Set up an SSH connection in TrueNAS before creating a remote replication task.
You can go to Credentials > Backup Credentials > SSH Connection and click Add to create an SSH connection, or select Generate New on the SSH Connection dropdown in the Replication Task Wizard to create an SSH connection to the remote system.
To configure an SSH connection, you need the IP address or host name for the remote system, and the administrator username and credentials.
The administrator user on the remote system must have SSH access and the SSH service enabled so the local TrueNAS system can authenticate and communicate with the remote system.
You can configure the SSH connection while configuring the replication task, but using the Credentials > Backup Credentials > SSH Connection option to add a new connection between the local and remote system allows you to properly configure the administration user associated with the task before you add the replication task.
If not properly configured, TrueNAS shows error messages stating the issue preventing you from continuing.
Using the Add SSH Connection screen creates the connection and keypair.
You can obtain the public key from the keypair screen to copy/paste into the admin user on both the local and remote systems before you open the replication wizard.
Update the admin user settings to to allow SSH access, add the public key for the SSH credential for the remote system, and allow sudo commands.
Go to Credentials > Backup Credentials > SSH Credential.
Add a new credential to the remote system if one does not exist, and then edit it to see the public key.
Copy the public key to add to the admin user on the remote system. You can add the credential on the local or remote system.
On the remote system, go to Credentials > Users, select the admin user, and click Edit.
Verify the account configuration has SSH Access selected.
If not, select it, and then paste the public key for the SSH connection in the Public SSH Key field.
Click on Sudo Commands and select Allow all sudo commands with no password to enable it.
Save changes.
Check the SSH Service settings. Go to System > Services > SSH and click the edit icon.
Select Allow Password Authentication to enable this function. Save the change.
Incorrect SSH service settings can impact the ability of the admin user to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Enable Start Automatically if you want the SSH service to start after a system restart, and then start or restart the service.
Configure your SSH connection before you begin configuring the replication task through the Add Replication Task screen.
If you have an existing SSH connection with the remote system the option displays on the SSH Connection dropdown list.
Turn on SSH service. Go to System > Services screen, verify the SSH service configuration, then enable it.
Creating a Simplified Advanced Replication Task
To access advanced replication settings, click Advanced Replication Creation at the bottom of the first replication wizard screen.
The Add Replication Task configuration screen opens.
Give the task a name.
Unlike the wizard, the Name does not automatically populate with the source/destination task name after you set the source and destination for the task.
Each task name must be unique, and we recommend naming it in a way that makes it easy to remember what the task is doing.
Select the direction of the task. Pull pulls data from a remote system to the local system. Push sends data from the local system to the remote.
Select the transfer method for this replication from the Transport dropdown list.
Select LOCAL to replicate data to another location on the same system.
Select SSH is the standard option for sending or receiving data from a remote system.
When selected, also select an SSH connection from the SSH Connection dropdown list.
Select SSH+Netcat is a faster option for replication when it occurs within a completely secure network.
SSH+Netcat requires defining NETCAT ports and addresses to use for the NETCAT connection.
With SSH-based replications, select the SSH Connection with the remote system from which you want to receive snapshots or send snapshots to.
To create a new connection to use for replication from a destination to this local system, select newpullssh.
Select Use Sudo for Zfs Commands to control whether the user for SSH/SSH+NETCAT replication has passwordless sudo enabled to execute zfs commands on the remote host.
If not selected, you must enter zfs allow on the remote system to to grant non-user permissions to perform ZFS tasks.
Specify the source and destination paths. Destination paths allow adding /name to the end of the path to create a new dataset in that location.
Click the arrow to the left of each folder or dataset name to expand the options and browse to the dataset, then click on the dataset to populate the Source.
Choose a preconfigured periodic snapshot task as the source of snapshots to replicate.
Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories.
A remote destination requires you to specify an SSH connection before you can enter or select the path.
If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and configure it to allow SSH connections.
Define how long to keep snapshots in the destination.
Remote sources require defining a snapshot naming schema to identify the snapshots to replicate.
Local sources are replicated by snapshots that were generated from a periodic snapshot task and/or from a defined naming schema that matches manually created snapshots.
DO NOT use zvols as remote destinations.
Select a previously configured periodic snapshot task for this replication task in Periodic Snapshot Tasks.
The replication task selected must have the same values in Recursive and Exclude Child Datasets as the chosen periodic snapshot task.
Selecting a periodic snapshot schedule removes the Schedule field.
If a periodic snapshot task does not exist, before creating the advanced replication task, configure a periodic snapshot task, then return to the Add Replication Task screen to configure the replication Task.
Select Replicate Specific Snapshots to define specific snapshots from the periodic task to use for the replication.
This displays the schedule options for the snapshot task. Enter the schedule.
The only periodically generated snapshots included in the replication task are those that match your defined schedule.
Select the naming schema or regular expression option to use for this snapshot.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema custom-%Y-%m-%d_%H-%M finds and replicates snapshots like custom-2020-03-25_09-15.
Enter multiple schemas by pressing Enter to separate each schema.
Set the replication schedule to use and define when the replication task runs.
Leave Run Automatically selected to use the snapshot task specified and start the replication immediately after the related periodic snapshot task completes.
Select Schedule to display scheduling options for this replication task, and to run the task according to its own schedule.
Selecting Schedule allows scheduling the replication to run at a separate time.
Choose a time frame that gives the replication task enough time to finish and is during a time of day when network traffic for both source and destination systems is minimal.
Use the custom scheduler (recommended) when you need to fine-tune an exact time or day for the replication.
Advanced Scheduler
Choosing a Presets option populates in the rest of the fields.
To customize a schedule, enter crontab values for the Minutes/Hours/Days.
These fields accept standard cron values.
The simplest option is to enter a single number in the field.
The task runs when the time value matches that number.
For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (,).
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (/) designates a step value.
For example, entering * in Days runs the task every day of the month. Entering */2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs.
Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days.
For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview displays when the current settings mean the task runs.
Examples of CRON syntax
Syntax
Meaning
Examples
*
Every item.
* (minutes) = every minute of the hour. * (days) = every day.
*/N
Every Nth item.
*/15 (minutes) = every 15th minute of the hour. */3 (days) = every 3rd day. */3 (months) = every 3rd month.
Comma and hyphen/dash
Each stated item (comma) Each item in a range (hyphen/dash).
1,31 (minutes) = on the 1st and 31st minute of the hour. 1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour. mon-fri (days) = every Monday to Friday inclusive (every weekday). mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
Desired schedule
Values to enter
3 times a day (at midnight, 08:00 and 16:00)
months=*; days=*; hours=0/8 or 0,8,16; minutes=0 (Meaning: every day of every month, when hours=0/8/16 and minutes=0)
Every Monday/Wednesday/Friday, at 8.30 pm
months=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 am
Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday
Note that this requires two tasks to achieve: (1) months=*; days=mon-fri; hours=8-18; minutes=*/15 (2) months=*; days=mon-fri; hours=19; minutes=0 We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Click Save.
Setting a Replication Compression Level
Options for compressing data, adding a bandwidth limit, or other data stream customizations are available.
Stream Compression options are only available when using SSH.
Before enabling Compressed WRITE Records, verify that the destination system also supports compressed write records.
Setting Block Size
Allow Blocks Larger than 128KB is a one-way toggle.
Replication tasks using large block replication only continue to work as long as this option remains enabled.
Setting Full File System Replication
By default, the replication task uses snapshots to quickly transfer data to the receiving system.
Selecting Full Filesystem Replication means the task completely replicates the chosen Source, including all dataset properties, snapshots, child datasets, and clones.
When using this option, we recommend allocating additional time for the replication task to run.
Replicating Dataset Properties
Leave Full Filesystem Replication unselected and select Include Dataset Properties to include just the dataset properties in the snapshots to replicate.
Leave this option unselected on an encrypted dataset to replicate the data to another unencrypted dataset.
Replicating Child Datasets
Select Recursive to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
Defining Replication Properties
Enter newly defined properties in Properties Override to replace existing dataset properties with the newly defined properties in the replicated files.
List any existing dataset properties to remove from the replicated files in Properties Exclude.
Saving Pending Snapshots
When a replication task is having difficulty completing, it is a good idea to select Save Pending Snapshots.
This prevents the source TrueNAS from automatically deleting any snapshots that failed to replicate to the destination system.
Changing Destination Dataset from Read-Only
By default, the destination dataset is set to be read-only after the replication completes.
You can change the Destination Dataset Read-only Policy to only start replication when the destination is read-only (set to REQUIRE) or to disable it by setting it to IGNORE.
Adding Transfer Encryption
The Encryption option adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system.
Selecting Encryption adds the additional setting options HEX key or PASSPHRASE.
You can store the encryption key either in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination and Source Snapshots
Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots.
TrueNAS also does a full replication of the source snapshots as if the replication task had not run, which can lead to excessive bandwidth consumption.
This can be a very destructive option.
Make sure that any snapshots deleted from the destination are obsolete or otherwise backed up in a different location.
Defining Snapshot Retention
Defining the Snapshot Retention Policy is generally recommended to prevent cluttering the system with obsolete snapshots.
Choosing Same as Source keeps the snapshots on the destination system for the same amount of time as the defined Snapshot Lifetime from the source system periodic snapshot task.
TrueNAS always preserves the latest snapshot so replication can resume later.
If you delete a dataset or zvol on the source, you must manually delete the replicated dataset or zvol and the most recent snapshot on the destination.
You can use Custom to define your own lifetime for snapshots on the destination system.
Replicating Snapshots Matching a Schedule
Selecting Only Replicate Snapshots Matching Schedule restricts the replication to only those snapshots created at the same time as the replication schedule.
TrueNAS replication allows users to create replicated snapshots of data stored in encrypted pools, datasets or zvols as a way to back up stored data to a remote system.
You can use encrypted datasets in a local replication.
You can set up a replication task for a dataset encrypted with a passphrase or a hex encryption key, but you must unlock the dataset before the task runs or the task fails.
With the implementation of the Local Administrator user and role-based permissions, when setting up remote replication tasks when logged in as an admin user, requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule.
Users also have the option to run a scheduled job on demand.
Remote replication with datasets also require an SSH connection in TrueNAS. You can use an existing SSH connection if it has the same user credentials you want to use for the new replication task.
Creating a Remote Replication Task for an Encrypted Dataset
To streamline creating simple replication tasks, use the Replication Task Wizard to create and copy ZFS snapshots to another system.
The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make changes such as assigning it a different destination, selecting other options like encryption, schedule, or retention lifetime, etc.
Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard.
This saves some time when creating multiple replication tasks between the same two systems.
Unlock the source dataset and export the encryption key to a text editor such as Notepad.
Go to Datasets select the source dataset, locate the ZFS Encryption widget and unlock the dataset if locked.
Export the key and paste it in any text editor such as Notepad. If you set up encryption to use a passphrase, you do not need to export a key.
After the replication task runs and creates the snapshot on the destination, you must unlock the dataset to access the data.
Click the from the replication task options to download a key file that unlocks the destination dataset.
Replicating to an Unencrypted Destination Dataset
TrueNAS does not support preserving encrypted dataset properties when trying to re-encrypt an already encrypted source dataset.
To replicate an encrypted dataset to an unencrypted dataset on the remote destination system, follow the instructions above to configure the task, then to clear the dataset properties for the replication task:
Select the task on the Replication Task widget. The Edit Replication Task screen opens.
Scroll down to and select Include Dataset Properties to clear the checkbox.
This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.
Using Additional Encryption Options
When you replicate an encrypted pool or dataset, you have one level of encryption applied at the data storage level.
Use the passphrase or key created or exported from the dataset or pool to unlock the dataset on the destination server.
To add a second layer of encryption at the replication task level, select Encryption on the Replication Task Wizard or on the Add Replication Task screen, then select the type of encryption you want to apply.
Select either Hex (base-16 numeral format) or Passphrase (alphanumeric format) from the Encryption Key Format dropdown list to open settings for that type of encryption.
Selecting Hex displays Generate Encryption Key preselected. Select the checkbox to clear it and display the Encryption Key field where you can import a custom hex key.
Selecting Passphrase displays the Passphrase field where you enter your alphanumeric passphrase.
Select Store Encryption key in Sending TrueNAS database to store the encryption key in the sending TrueNAS database or leave unselected to choose a temporary location for the encryption key that decrypts replicated data.
Unlocking a Replication Encrypted Dataset or Zvol
Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase
TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.
Method 1: Construct JSON Manifest.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension .json.
On the remote system, unlock the dataset(s) using properly constructed json files.
Method 2: Replicate Encrypted Dataset/zvol Without Properties.
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Method 3: Replicate Key Encrypted Dataset/zvol.
Go to Datasets on the system you are replicating from.
Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset.
Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
Network
The System > Network menu option has several screens that enable configuring network interfaces and general system-level network settings.
The tutorials in this section guide with the various screens and configuration forms contained within this menu item.
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Configuring IPv6: Provides instructions configuring a network interface and other network settings for IPv6, and configuring an SMB or NFS share for IPv6.
Configuring Static Routes: Provides instructions on configuring a static route using the TrueNAS web UI.
Setting Up IPMI: Guides you through setting up Intelligent Platform Management Interface (IPMI) on TrueNAS.
Accessing NAS from VMs and Containers: Provides instructions on how to create a bridge interface for virtual machines or applications and provides Linux and Windows examples.
Interface Configurations
TrueNAS supports configuring different types of network interfaces such as a standard interface, network bridge, LAGG, and VLAN interfaces to use as part of the various backup, sharing, and virtualization features in TrueNAS.
The tutorials in this section guide you through each of the various network interface configurations.
Why should I use different interface types?
A LAGG (Link Aggregation) optimizes multi-user performance, balances network traffic, and provides network failover protection.
In a failover, it prevents a network outage by dynamically reassigning traffic to another interface when a physical link, like a cable or NIC, fails.
A network bridge enables communication between two networks and provides a way for them to work as a single network.
Bridges can serve IP addresses to multiple VMs on one interface, which allows your VMs to be on the same network as the host.
A VLAN (virtual LAN) segments a single physical network into multiple logical networks, allowing network traffic isolation and security boundaries without requiring separate physical hardware.
VLANs provide separate traffic management for storage (iSCSI/NFS), VMs, and multi-tenant environments while improving security, reducing broadcast domains, and enabling multiple networks on a single NIC.
The Network screen shows network settings for interfaces, global network settings, adding static routes, and IPMI connections.
This article describes adding new or changing existing network interfaces.
For information on configuring IPv6 addresses, see Configuring IPv6.
You must know the DNS name server and default gateway addresses for your IP address.
Static IP or DHCP-Assigned?
By default, TrueNAS configures the primary network interface for Dynamic Host Configuration Protocol (DHCP) IP address management during installation.
However, some administrators might choose to assign a static IP address to the primary network interface.
This choice can be made if TrueNAS is deployed on a system that does not allow DHCP for security, stability, or other reasons.
In all deployments, only one interface can be set up for DHCP, which is typically the primary network interface configured during the installation process.
Any additional interfaces must be manually configured with one or more static IP addresses.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Adding an Interface
TrueNAS uses DHCP to assign an IP address to the primary network interface during installation to provide access to the web UI.
DHCP provides the IP address for only one network interface.
After initially installing TrueNAS, you can change the DHCP-assigned IP address to a static IP address by:
Logging into the UI using the DHCP-assigned IP address, and going to the Network screen and editing the interface
We recommend using the UI to make network changes as it has safeguards in place to prevent you from losing access to the system due to incorrectly configured interfaces.
To add another network interface in the UI, go to System > Network and click Add on the Interfaces widget to open the Add Interface screen.
You must specify the type of interface to create.
Select the interface type from the Type dropdown options: Bridge, Link Aggregation (LAGG), or VLAN (virtual LAN).
The interface type cannot be changed after clicking Save.
To revert the interface to default network settings, select Reset Configuration on the more_vert for the interface.
This resets the interface from a static IP address to a DHCP-assigned address and resets the domain to the TrueNAS default local.
Enter a name for the interface using the format that corresponds to the type of interface you are adding. Naming differs between physical and virtual interfaces.
The name assigned to the primary physical network interface on your system is based on the systemd predictable naming scheme, and reflects the hardware type and location. The names vary based on your hardware configuration.
For example, eno1 for onboard NICs, ens3 for PCIe slot NICs, and you might see eno1np0, which is an onboard NIC with more than one port on the NIC.
When selecting a virtual interface type, enter a name based on the type.
For example, bondX, vlanX, or brX and where X is a number.
To allow DHCP to assign the interface IP address, select Get IP address Automatically from DHCP.
To use a fixed (static) IP address, select the Define Static IP Addresses, and then click Add to the right of Static IP Addresses to show the IP address and netmask (CIDR) fields. Enter the assigned IP address and select the netmask from the dropdown list.
Click Add for each IP address you want to associate with the interface.
If adding an IPv6 IP address, refer to Configuring IPv6 for details on this type of network configuration.
Click Save when you are certain of your configuration. You cannot change the interface type or name after clicking Save!
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Editing an Interface
To change an existing interface, click on the more_vert icon at the right of the interface, and then click Edit to open the Edit Interface screen.
The Edit Interface and Add Interface screen settings are identical, but the Type and Name fields are not editable for an existing interface.
If you created the wrong type of virtual interface (i.e., a bridge, vlan, lagg), delete the interface and add a new interface with the correct type.
When changing from a DHCP-provided IP address to a static IP, first verify your current default gateway and name servers work with the new IP address.
You must add the new default gateway and DNS name servers that work with the new IP address to the global configuration.
If you need to change these settings, do this before you change the interface so you can test the interface change.
Click Save after making all changes.
Test the change as described above in Testing Network Interface Changes.
Resetting an Interface Configuration
Resetting the configuration for a network interface can result in lost access to the TrueNAS UI and losing the connection to TrueNAS!
Clicking Reset Configuration resets the domain name back to the default value, and changes the static IP address to DHCP-assigned.
When saved, changes cause lost access to the UI. You might need command line knowledge, and either IPMI or physical access to the TrueNAS system to fix misconfigured network settings.
If using IPMI or a physical connect to the system, you can change network and interface settings through the Console Setup menu.
The TrueNAS UI does not offer a way to delete the interface. Do not delete the primary network interface in the CLI!
Click on the more_vert dropdown list for the interface, then select Reset Configuration.
The current IP address resets to a DHCP-assigned IP address and the domain name reverts to the default setting.
Confirm validates the reset activity and activates the Reset button.
Reset clears the configuration for that interface.
After making the changes and clicking Save, the test change options show on the Network screen.
Follow the procedure above to test your changes and validate you still have access to the UI and the TrueNAS system.
Changing from DHCP to a Static IP Address
TrueNAS allows assigning static IP addresses to an interface when not using a DHCP-assigned address.
Static IP addresses set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access.
You can add an additional IP address for a network interface configured with another primary IP address.
Verify the default gateway and nameservers for the DHCP-assigned address and new static IP address are the same before making a change.
If not the same, edit the global network settings before changing the interface so you can properly test the change.
Changing the Global Network Settings
Go to System > Network:
Check the name servers and default router information in the Global Information widget.
If the current settings are not on the same network, click Settings and modify each setting as needed to allow the static IP to communicate over the network.
Enter the IP addresses for the DNS name servers in the Primary, Secondary, and the optional Tertiary fields.
For home users, enter 8.8.8.8 for a DNS name server address so you can communicate with external networks.
Enter the IP address for the default gateway in the appropriate field.
If the static network is IPv4 enter the gateway in IPv4 Default Gateway, if the static network is IPv6 use IPv6 Default Gateway.
Click Save.
If in an IPMI session, you can use the Console Setup menu to change settings.
Enter 2 to configure general network settings like the default gateway and name servers.
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (LAGG) or network bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
To use the UI to change an interface from DHCP to a static IP address, go to System > Network:
Verify the default gateway and name servers work with the new static IP address.
If not, click the link above and follow the instructions to update the global network settings.
Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Click Add to the right of Static IP Addresses to show the IP address and netmask (CIDR) fields.
Click Add for each static IP address you want to add to this interface.
Enter the IP address and select the netmask value for each static address you add.
Multiple interfaces cannot be members of the same subnet!
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet but you can combine multiple interfaces with a link aggregation (LAGG) or network bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Multiple NICs on One Subnet
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs shows as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
LACP provides additional bandwidth or redundancy for critical networking situations, but it is limited because it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, configure one or more static IP aliases for a single NIC.
We recommend using LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.
If an error displays or the Save button remains inactive when setting the IP addresses on multiple interfaces, check the subnet and ensure the netmask (CIDR) numbers are different.
Click Save.
Click Test Changes when prompted. Follow the procedure above to test network changes.
Returning to a DHCP-Assigned IP Address
Only one interface can use DHCP to assign the IP address and that is likely the primary network interface.
If you do not have an existing network interface set to use DHCP you can convert an interface from static IP to DHCP.
To switch back to using DHCP:
Click on the more_vert icon for the interface, and then click Edit to open the Edit Interface screen.
Select Get IP Address Automatically from DHCP.
Click Save.
Verify the current default gateway and name servers work with the new DHCP-assigned IP address.
If yes, test the network change. Click on 60 above the Test Changes button to extend the number of seconds you have to test the network change.
If the current settings do not work with the new DHCP-assigned IP address, click the link in the Changing from DHCP to a static IP Address section, and follow the directions to change these settings.
If the test network operation fails or the system times out, your system returns to the network settings before you attempted the change.
Edit the global network settings and click save, then edit the interface and click save. Test the network changes again.
In general, a bridge refers to various methods of combining (aggregating) multiple network connections into a single aggregate network.
TrueNAS uses bridge(4) as the kernel bridge driver.
Bridge(8) is a command for configuring the bridge in Linux.
While the examples focus on the deprecated brctl(8) from the bridge-utilities package, we use ip(8) and bridge(8) from iproute2 instead.
Refer to the FAQ section that covers bridging topics more generally.
Network bridging does not inherently aggregate bandwidth like link aggregation (LAGG).
Bridging is often used for scenarios that require extending a network segment or combining different types of network traffic.
You can use bridging to integrate different types of networks (e.g., wireless and wired networks) or to segment traffic within the same network.
You can also use a bridge to allow a VM, container, or app configured on TrueNAS to communicate with the host system.
See Accessing NAS from Containers for more information.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a Bridge
To set up a bridge interface:
Go to Apps and the Containers screens to verify all apps and containers are stopped.
If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM.
Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Click the more_vert icon for the interface, to open the Edit Interface screen.
Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
a. Set Type to Bridge. Name automatically populates with the correct name.
You cannot change the Type field value or the name after clicking Save!
b. (Optional) Enter a short description for the bridge. This is optional but recommended if configuring multiple bridges on your system to help identify their use or location.
c. Select Define Static IP Addresses, then click Add to the right of Static IP Addresses.
Enter the IP address and select the netmask for the interface edited in step 4 above. Refer to the screenshot if you do not remember the IP address and netmask.
d. Select the interface name in Bridge Members. You only need to add the interface name edited in step 4 above.
Leave Enable Learning selected 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 editConfigure to view the current configuration of sharing services, including SMB and NFS.
Stop any services that have a bind IP address matching the bridge IP address.
Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.
Setting Up a Link Aggregation
In general, a link aggregation (LAGG) is a method of combining (aggregating) multiple network connections in parallel to provide additional bandwidth or redundancy for critical networking situations.
TrueNAS uses lagg(4) to manage LAGGs.
Before You Begin
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
If configuring an LACP link aggregation, configure a port-channel or link aggregation group on your network switch before creating the LAGG interface in TrueNAS.
The switch ports connected to your TrueNAS interfaces must be configured for LACP (IEEE 802.3ad) and active before TrueNAS can successfully negotiate the link aggregation.
Consult your switch documentation for specific configuration steps.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a Link Aggregation Interface
To set up a LAGG, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select Link Aggregation from the Type dropdown list. You cannot change the Type field value after you click Save.
In LACP mode, the interfaces negotiate with the network switch to form a group of ports that are all active at once.
The network switch must support LACP for this option to function.
a. Select the hash policy from the Transmit Hash Policy dropdown list. LAYER2+3 is the default selection.
b. Select the LACPDU Rate options are Slow or Fast.
SLOW (default) sets the heartbeat request to every second and the timeout to a three-consecutive heartbeat loss that is three seconds.
FAST sets the timeout rate at one per second, even after synchronization. FAST allows for rapid detection of faults.
FAILOVER
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 LAGG.LOADBALANCE
Select LOADBALANCE to accept traffic on any port of the LAGG group and balance the outgoing traffic on the active ports in the LAGG group.
LOADBALANCE is a static setup that does not monitor the link state or negotiate with the switch.
Select the Transmit Hash Policy option from the dropdown list. LAYER2+3 is the default selection.
Select the interfaces to use in the aggregation from the Link Aggregation Interface dropdown list.
(Optional) Click Add to the right of Static IP Addresses to show additional IP address fields for each additional IP address to add to this LAGG interface.
Click Save when finished.
Test the network change when prompted.
Setting Up a Network VLAN
A virtual LAN (VLAN) is a partitioned and isolated domain in a computer network at the data link layer (OSI layer 2).
Click here for more information on VLANs.
Before you begin, make sure you have an Ethernet card connected to a switch port and configured for your VLAN.
Ensure that you have also preconfigured the VLAN tag in the switched network.
Consult with your IT department to obtain this VLAN tag if you are not the network administrator for your systems.
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to the information below to restore communication with your server.
Lost communication might require an IPMI or physical connection to the system, and reconfiguring your network settings using the Console Setup menu.
To prepare before making changes:
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand before making network changes.
You only have 60 seconds to change and test new network settings before they revert to the current settings.
For example, back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.
Grab a screenshot of your current settings in the Global Configuration widget as a precautionary step.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Testing Network Interface Changes
TrueNAS protects your connection to the interface by displaying the Test Changes option on the Network screen after you make and save changes to the network interface.
TrueNAS shows the unapplied changes widget above the Interfaces widget after saving network changes.
Click the Test Changes button to test access to the UI after making a change and before making it a permanent change.
This safeguard is intended to prevent changes that can break access to the UI.
Revert Changes discards any changes made to the interface within the same 60-second period.
The test timer starts after you click Save on the Add Interface or Edit Interface screens.
After clicking Test Changes, wait a few moments to give the interface time to initialize, and then refresh the browser until you see the Save Changes button or follow the steps below to test in a new browser tab. Click Save Changes to make the changes permanent.
To test the change in a different browser tab:
Click Test Changes.
(Optional) Click on 60 and enter a new number to change the time allotted to test the network change before changes automatically revert.
Immediately open a new browser window. Do not close the existing login session tab.
Enter the new IP address in the browser URL field of the new browser window, and press Enter.
The TrueNAS login screen displays.
Enter your administrator login credentials to access the system.
Go to Network and click Save Changes to make the changes permanent.
If the timer expires before you save the changes, TrueNAS reverts to the settings before you made the change.
Return to the original browser session, to re-enter your interface changes, click Save, then repeat the steps above.
If you cannot access the UI, return to the original browser session and click Revert Changes on the Network screen.
Adding a VLAN Interface
To set up a VLAN interface, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select VLAN from the Type dropdown list. You cannot change the Type field value after clicking Apply.
Name populates with the default name vlan1. You cannot change the Name of the interface after clicking Save.
Leave Define Static IP Addresses selected under DHCP.
(Optional, but recommended) Enter any notes or reminders about this VLAN in Description.
Select the interface in the Parent Interface dropdown list. This is typically an Ethernet card connected to a switch port already configured for the VLAN.
Enter the numeric tag for the interface in the VLAN Tag field. This is typically preconfigured in the switched network.
Select the VLAN Class of Service from the Priority Code Point dropdown list.
(Optional) Click Add to the right of Aliases to show additional IP address fields for each additional IP address to add to this VLAN interface.
Click Save.
Test the network change when prompted.
Managing Network Configurations
Use the Network Configuration Settings widget shows existing general network settings like the default gateway and DNS servers, set services allowed to externally communicate, enter an HTTP proxy, or host name database.
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Do not configure network settings to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers.
This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started.
Can I configure these options elsewhere?
Users can configure many of the interface, DNS, and gateway options using the Console Setup menu.
Be sure to check both locations when troubleshooting network connectivity issues.
Adding Network Settings
Use the Network Configuration widget to add general network settings like the default gateway and DNS name servers to allow external communication.
Go to System > Network, and click Settings on the Network Configuration widget to open the Edit Global Configuration screen.
Enter the host name for your TrueNAS in Hostname. For example, replace the default value truenas with something like localnas.
If you plan to use Active Directory or SMB services, the hostname is also used as the NetBIOS name and must comply with NetBIOS naming restrictions: maximum 15 characters, cannot contain \ / : * ? " < > |, and cannot use Microsoft or RFC 852 reserved words (ANONYMOUS, AUTHENTICATED USER, BATCH, BUILTIN, DIALUP, DOMAIN, ENTERPRISE, INTERACTIVE, INTERNET, LOCAL, NETWORK, NULL, PROXY, RESTRICTED, SELF, SERVER, USERS, WORLD, GATEWAY, GW, TAC). TrueNAS 25.04 and later enforce these restrictions through validation.
Enter the system domain name in Domain. For example, replace the default local with example.com.
Enter the IP addresses for your DNS name servers in Primary, Secondary, and/or Tertiary.
For home users, enter 8.8.8.8 in the Primary field so your TrueNAS can communicate externally with the Internet.
Enter the IP address for your default gateway into the IPv4 Default Gateway if you are using IPv4 IP addresses.
Enter the IPv6 address in the IPv6 Default Gateway if you are using IPv6 addresses.
Select the desired Outbound Network option.
Selecting Allow All permits all services to communicate externally.
Selecting Deny All prevents services from communicating externally.
Selecting Allow Specific shows a dropdown list of services that you can choose to allow to communicate externally.
Services not selected cannot communicate externally.
Selecting Allow All Except shows the same dropdown list of services that you can choose to deny the ability to communicate externally.
Services not selected for this option are allowed external communication
Click Save. The Network Configuration widget on the Network screen shows the new settings.
Configuring IPv6
TrueNAS provides the option to configure network interfaces using either IPv4 or IPv6 addresses.
IPv4 networks cannot see or communicate with an IPv6 website or network unless a gateway or some other implementation is configured to allow it.
See Understanding IPv6 for more information.
Configuring IPv6 Addresses
After configuring your network infrastructure for IPv6, assign the IP addresses for your TrueNAS system.
Use the TrueNAS UI to configure your network settings.
If setting TrueNAS up for the first time after a clean install, use the Console Setup menu to enter IPv6 addresses.
Configuring an Interface Using the Console Setup Menu
If configuring your network settings using the Console Setup menu for the first time after installing TrueNAS, first configure the interface address.
Type 1, then press Enter.
Enter eno1 in name, then the IPv6 address in aliases.
Save, then select a to apply and p to make it persist. Type q to return to the Console Setup menu.
Next, configure the IPv6 gateway address, and the nameserver addresses. Type 2, then press Enter.
Enter the name server addresses provided by your IT department or Internet Service Provider (ISP), and then the gateways.
Save, then select a to apply and p to make it persist.
Adding an IPv6 Interface in the UI
Navigate to System > Network screen to enter your network settings.
Click on Add in the Interfaces to open the Add Interface screen.
Enter en8s0 as the name for the interface if it is the primary interface.
Clear the DHCP checkbox, then select Autoconfigure IPv6 if you want to create the IP address using SLAAC.
This automatically configures the IPv6 address.
You can only use this option one time to configure an IPv6 address for the system.
Enter the IPv6 address assigned to the NIC port if using a fixed IP address assignment.
Click Save
Test the change.
If adding the primary interface test the network connection by opening a new browser window.
Enter the IPv6 address inside square brackets in the URL address field, for example, [ipv6 address].
After the system comes up, save the changes to the network interface.
To access the UI after configuring an IPv6 address, enter the IPv6 address inside square brackets in the browser URL field.
You cannot access the UI with the assigned host name when the system is configured on an IPv6 network.
Configuring Dual Stacking
TrueNAS supports dual-stacking IPv4 and IPv6 addresses in the same interface.
An IPv4 network cannot see or communicate with an IPv6 network unless some gateway is configured to allow IPv6 communication.
Dual stacking these two protocols allows TrueNAS to see and communicate with an all IPv6 address or website.
You must have IPv6 configured in your networking infrastructure.
Add IPv6 to your network router to permit the incoming and outgoing traffic. This provides the required gateway to permit communication with this IP protocol.
Assign a static IPv6 address and netmask, the network gateway address, and name servers to configure in TrueNAS.
When configuring dual stacking, the order in which you configure the two network IP protocols does not matter.
If IPv4 networking is already configured in TrueNAS, to set up dual stacking of IPv6 in the UI, go to System > Network:
Add the IPv6 gateway information.
Click Settings on the Global Configuration widget to open the Edit Global Configuration screen.
Enter the IPv6 address for the gateway in IPv6 Default Gateway.
Click Save.
Add the IPv6 static IP address to the primary interface.
Select the primary interface, en8s0, then click Edit.
Click Add* to the right of Aliases to add another set of IP Address fields.
Enter the IPv6 address, then select the netmask.
Click Save
Test the network change.
To verify the IPv6 address, in a new browser window, enter the address inside square brackets. For example, [ffff:ff:59f8:100::12].
Log into the UI, and click Save Changes.
Log out of that browser session, return to your other UI session.
Both IPv4 and IPv6 addresses should show on the screen for the primary interface.
After installing TrueNAS and using the Console Setup menu to configure system networking and set up dual stacking, add the name servers and both IP protocol default gateways in general network settings (option 2 on the menu), then add both IP address, with netmasks as aliases, on the primary network interface (option 1 on the menu).
If using the Console Setup menu to set up IPv6 on an already IPv4-configured system, add the v6 default gateway in general network, then add the IPv6 IP address with netmask as an alias on the primary interface.
Connecting to the UI IPv6 Address
Unlike IPv4, you must enter the IPv6 address with a square bracket preceding and following the address.
You cannot enter the host name assigned to the TrueNAS system to access the UI.
For example, enter [ffff:ff:59f8:100::12] into the URL field of the browser window to access the UI.
Using IPv6 with Sharing Protocols
When configuring an SMB or NFS share, first configure the bind address in the share service.
Next, configure the share user, and add the share and dataset.
Finally, add the share owner to the dataset permissions.
Go to System > Services click Advanced Options then edit the share service.
For SMB, scroll down and select the IPv6 address as the Bind IP Address and click Save.
For NFS, also select the IPv6 address in Bind IP Addresses.
Select Allow non-root mount, then click Save.
Go to Credentials > Local User to create the share user.
Modify the ACL permissions.
Either click on Edit Filesystem ACL on the Shares screen or go to Datasets, select the dataset row, scroll down and click Edit on the Permissions widget.
Leave the dataset permissions @owner and @group set to root or change them to the admin user.
Next click Add New to create a new ACL entry for the share user(s).
See Setting Up Permissions for more information on adding new entries and modifying dataset permissions.
To mount or access the share in Windows, you must enter the share information using a particular syntax or it cannot find nor connect to the share.
The syntax requires you to replace each colon (:) in the IPv6 address with a dash (-).
Enter two forward slashes, followed by the IPv6 address with .ipv6-literal.net after it, then enter another forward slash, and finally the share name.
For example, \\ffff-ff-59f8-100–12.ipv6-literal.net\v6smbshare.
Configuring an SSH Connection
Both replication to a remote server and rsync tasks require configuring an SSH connection credential.
When both systems are using IPv6 addresses and the protocol to communicate, you must enclose the IPv6 address in square brackets when defining the remote system URL in the TrueNAS URL field on the New SSH Connection configuration screen.
Managing Network Settings (Enterprise HA)
TrueNAS Enterprise
The instructions in the article only apply to TrueNAS Enterprise (HA) systems.
Configuring Enterprise (HA) Network Settings
Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready, click Sync to Peer to haveTrueNAS apply settings to controller 2.
TrueNAS Enterprise (HA) systems use three static IP addresses for access to the UI:
VIP to provide UI access regardless of which controller is active.
If your system fails over from controller 1 to 2, then fails back over to controller 1 later you might not know which controller is active.
IP for controller 1. Do not use DHCP to assign the IP address! If enabled, DHCP assigns an IP to the primary network interface on non-HA systems.
Disable DHCP, and then manually enter the Controller 1 static IP address your network administrator assigned for this controller.
IP for Controller 2. Manually enter the second IP address assigned for this controller.
Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.
TrueNAS safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes.
This is to prevent users from breaking their network connection in TrueNAS.
To configure network settings on controller 1:
Disable the failover service.
Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to clear the checkmark, then select Default TruNAS Controller to enable it, and then click Save to disable failover.
Go to System > Network and click Settings to edit the global network settings.
Add the controller and virtual host names and update any other network settings.
Edit the primary network interface to add failover settings.
Click on the more_vert to the right of the the primary interface eno1, and select Edit to open the Edit Interface screen for this interface.
a. Turn DHCP off if it is on by selecting Define Static Ip Addresses. Click Add to show IP address fields for each interface.
Enter the IP address assigned to controller 1 in IP Address (TrueNAS Controller 1), the IP address assigned to controller 2 in IP Address (This Controller), and the IP address assigned as the virtual IP in Virtual IP Address (Failover Address).
If Define Static IP Addresses is already selected, verify the three static IP addresses assigned to the system show in the correct fields.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
b. Add the failover settings. Select 1 on the Failover Group dropdown list.
Click Test Changes after editing the interface settings. Open a new browser window and enter the VIP IP address to access the web UI.
Go to System > Network and click Save Changes to make the changes permanent.
You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Enable failover. Go to System > Advanced Settings, scroll down to the Failover widget, then click Configure.
Select Enable Automatic Failover to re-enable failover, then click save.
Turn failover back on.
Go to System > Failover and select Disable Failover to clear the checkmark and turn failover back on, then click Save.
The system might restart.
Monitor the status of controller 2 and wait until the controller is back up and running, then click Sync To Peer.
Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation.
The controller restarts, and TrueNAS syncs controller 2 with controller 1, which adds the network settings and pool to controller 2.
TrueNAS does not pre-define static routes by default, but TrueNAS administrators can manually add static routes if they want or need to enter routes to a router to send packets to a destination network.
Static routes are not aliases, they are fixed IP addresses assigned as alternative routes for network traffic sent to a specific destination (server, device) in the network.
You can use the Console Setup menu during installation or any time after the initial system configuration to add a static route through an SSH session or by connecting a monitor and keyboard to the system, but we recommend using the web UI to make changes to the network configuration.
We recommend using the TrueNAS web UI to make network changes because it includes safeguards that prevent breaking access to the UI or connections to TrueNAS that can result from incorrectly configured network settings.
If you need a static route to reach portions of the network:
Go to System > Network and click Add on the Static Routes widget.
Enter an IP address and netmask (CIDR) for the destination in the format A.B.C.D/E where E is the CIDR mask in Destination.
Enter the default gateway IP address for the destination address in Gateway.
(Optional) Enter a brief description for this static route, such as the part of the network it reaches.
Click Save.
Setting Up IPMI
IPMI requires a compatible motherboard with IPMI support.
Refer to your hardware documentation to determine compatibility.
Many TrueNAS systems include a built-in out-of-band management port, enabling system access even when the web interface is unavailable.
Intelligent Platform Management Interface (IPMI) allows users to check the log, access the BIOS setup, and boot the system without physical access.
IPMI also enables users to remotely access the system to assist with configuration or troubleshooting issues.
The IPMI widget on the Network screen shows the available IPMI channels and gives access to IPMI configuration and event logs.
On TrueNAS Enterprise High Availability (HA) systems, the IPMI configuration screen includes a Remote Controller section that allows you to select which controller to configure.
Select the controller you want to configure IPMI settings for or use the identify light feature on.
All IPMI configuration changes and the identify light feature apply only to the selected controller.
To configure a static IPv4 connection for IPMI, do not select DHCP.
Enter the IPv4 address for the IPMI web interface.
Enter the IPv4 address subnet mask in IPv4 Netmask, such as 255.255.240.0.
Enter the IPv4 connection default gateway.
If needed, enter the VLAN identifier of the IPMI interface in VLAN ID.
We recommend configuring IPMI on a separate VLAN that is isolated from the main TrueNAS network.
This allows for IPMI access even if the main network is down.
Click Save to update IPMI configuration.
After saving the configuration, access the IPMI interface using a web browser and the IP address specified in Network > IPMI or click to open the IPMI manager in a new browser tab.
The management interface prompts for login credentials.
IPMI utility appearance and available functions vary by hardware.
Refer to your IPMI device documentation to learn the default administrator account credentials.
After logging in to the management interface, change the default administrative user name.
We recommend setting a strong IPMI password.
Refer to your IPMI device documentation for password requirements.
Document your password in a secure location.
Alternately, enter a new password in IPMI Password Reset on the IPMI configuration screen.
IPMI Alerts
Click Show Events on the IPMI widget to show the IPMI Events log.
Use the Alert Settings Screen under the Hardware category to adjust IPMI alerts.
Configure the minimum warning level and frequency to display IPMI alerts in the TrueNAS UI.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Accessing NAS from VMs and Containers
If you want to access your TrueNAS directories from within a virtual machine or container hosted on the system, you have multiple options:
Allow TrueNAS to create an automatic bridge (default).
Manually create a bridge interface if you have only one physical interface.
Assign a NIC other than the primary one your TrueNAS server use if you have more than one physical interface.
This method makes communication more flexible but does not offer the potential speed benefits of a bridge.
Containers allow you to configure a MACVLAN NIC, which creates a virtual interface based on an existing physical one.
The assigned unique MAC address allows the instance to appear as a separate device on the network.
A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host.
MACVLAN sends traffic directly to the external network without passing through the host network stack.
The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.
Using Default Network Settings
Leave Use default network settings selected while creating a new instance to allow TrueNAS to automatically assign the default network bridge.
This is the simplest way to allow communication between containers and the TrueNAS host.
If your system only has a single physical interface, and you prefer to manually configure a network bridge, complete these steps.
Before making network interface changes:
Stop running apps.
Power off running virtual machines (VMs) and containers.
Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
Adding a Bridge
To set up a bridge interface:
Go to Apps and the Containers screens to verify all apps and containers are stopped.
If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM.
Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Click the more_vert icon for the interface, to open the Edit Interface screen.
Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
a. Set Type to Bridge. Name automatically populates with the correct name.
You cannot change the Type field value or the name after clicking Save!
b. (Optional) Enter a short description for the bridge. This is optional but recommended if configuring multiple bridges on your system to help identify their use or location.
c. Select Define Static IP Addresses, then click Add to the right of Static IP Addresses.
Enter the IP address and select the netmask for the interface edited in step 4 above. Refer to the screenshot if you do not remember the IP address and netmask.
d. Select the interface name in Bridge Members. You only need to add the interface name edited in step 4 above.
Leave Enable Learning selected 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 editConfigure to view the current configuration of sharing services, including SMB and NFS.
Stop any services that have a bind IP address matching the bridge IP address.
Restart the service(s) after network changes are tested and saved.
(Optional) Stop running apps. After network changes are tested and saved, restart apps.
After adding the bridge and to assign the bridge to a VM or container, go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget.
Click Add and select the new bridge interface from the dropdown list.
You can now access your TrueNAS storage from the container.
You might have to set up shares or users with home directories to access certain files.
Assigning a Secondary NIC: Multiple Physical Interfaces
If you have more than one NIC on your system, you can assign container traffic to a secondary NIC.
Configure the secondary interface as described in Managing Interfaces before attaching it to an instance.
If you are creating a new instance, use the Network settings to disable Use default network Settings and select the secondary NIC from Macvlan NICs.
TrueNAS Credential options are collected in this section of the UI and organized into a few different screens:
Users allows those with permissions to add, configure, and delete users on the system.
There are options to search for keywords in usernames, view or edit user characteristics, and a dropdown to select whether the screen shows built-in, local, and/or directory services users.
Groups allows those with permissions to add, configure, and delete user groups on the system.
There are options to search for keywords in group names, display or hide group characteristics, and toggle whether the screen shows built-in groups.
Directory Services contains options to edit directory domain and account settings, set up Idmapping, and configure access and authentication protocols.
Specific options include configuring Kerberos realms and key tables (keytab), as well as setting up LDAP validation.
Backup Credentials stores credentials for cloud backup services, SSH Connections, and SSH Keypairs.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
Certificates contains all the information for certificates, certificate signing requests, certificate authorities, and DNS-authenticators.
TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
2FA allows users to set up Two-Factor Authentication for their system.
Users can set up 2FA, then link the system to an authenticator app (such as Google Authenticator, LastPass Authenticator, etc.) on a mobile device.
Contents
Using Administrator Logins: Explains role-based administrator logins and functions. Provides instructions on configuring SSH and working with the admin and root user passwords.
Managing Users: Provides instructions on adding and managing administrator and user accounts.
Managing Groups: Provides instructions on adding and managing groups.
Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.
Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.
Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.
Backup Credentials: Backup credential tutorials for integrating TrueNAS with cloud storage providers by setting up SSH connections and keypairs.
Adding Cloud Credentials: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.
Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.
Certificates: Information about adding and managing certificates, CSRs, CAs, and ACME DNS-Authenticators in TrueNAS.
Managing Certificates: Provides information on adding or managing certificates in TrueNAS.
Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.
Configuring KMIP: Provides information on Key Management Interoperability Protocol (KMIP) in TrueNAS. Describes how to configure KMIP on TrueNAS Enterprise.
Using Administrator Logins
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
Administrator accounts have roles and privileges that are FIPS compliant and allow more control over access to TrueNAS functions.
TrueNAS has three predefined admin user account levels:
Full Admin - Assigned to the local administrator account created by the system when clean installing TrueNAS using an iso file.
Also assigned when manually creating an admin user if logged in as the root user account after upgrading from a pre-22.12.3 release of TrueNAS or migrating from FreeBSD- to Linux-based TrueNAS releases.
Sharing Admin - Assigned to users responsible for only managing shares (SMB, NFS, iSCSI).
This user can create shares and the datasets for shares, start/restart the share service, and modify the ACL for the share dataset.
Readonly Admin - Assigned to users that can monitor the system but not make changes to settings.
For more information on the different administrator scenarios users can encounter, read Logging In for the First Time.
Changing Administrator Account Passwords
Administrator passwords can be changed on the Edit User screen or, if currently logged in as that admin user, by clicking the Settingsaccount_circle icon on the top toolbar and clicking Change Password.
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.
Use the Privileges dropdown to select assign permissions as Local Administrator to allow full administrative access or select Read-Only Administrator or Sharing Administrator to limit permissions.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
Click Save.
After creating a new group, click groupMembers to open the Update Members screen and assign one or more administrative user accounts to the group.
Click Save.
Log out of the TrueNAS system and then log back in using the new user credentials to verify that the admin credentials work properly with your network configuration.
The root account group membership cannot be modified and is permanently assigned to the builtin_administrators group (gid 544).
This restriction prevents accidental removal of required privileges that could cause system functions like scheduled tasks, cloud sync operations, and cron jobs to fail.
To disable root account access to the TrueNAS UI while maintaining proper system functionality, use the Disable Password option in Credentials > Local Users instead of modifying group membership.
Allowing Sudo Commands
As a security hardening feature, administrator accounts in Linux-based TrueNAS releases (22.12.0 or newer) cannot execute certain root-level commands in a shell or SSH session by default.
If a user attempts to execute one of these commands without root-level access, TrueNAS returns a command not found error.
Administrative users who need to execute root-level commands to complete a task should temporarily enable sudo permissions for that user by going to Credentials and editing the user or group to allow some or all sudo commands.
For best security, enable only the required commands to perform the task and require password authentication, unless the task or app prevents it.
Disable sudo permissions when the task completes and you no longer need them.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password, and Allow all sudo commands with no password, on the Add Group and Edit Group screens, grant limited root-like permissions using the sudo command.
Use Allowed sudo commands or Allowed sudo commands with no password to list specific sudo commands to allow.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press Enter after each command.
To allow full access to sudo commands, select either Allow all sudo commands or Allow all sudo commands with no password.
If you allow sudo commands with password protection, TrueNAS prompts you for a password the first time you enter a sudo command, but not again in the same session.
Disable these settings after completing the task to return to a security-hardened system.
Do not allow sudo permissions for read-only administrators.
Disabling Root and Admin User Passwords
As a security measure, the root user is no longer the default account and TrueNAS disables the root password when you create the truenas_admin or admin user during installation.
Do not disable the default admin account, root, and any custom admin account passwords at the same time.
If all root and administrator account passwords become disabled at the same time and the web interface session times out, a one-time sign-in screen allows access to the system.
Enter and confirm a password to gain access to the UI.
After logging in, immediately go to Credentials > Users to enable the password for an administrator account before the session times out again.
TrueNAS does not save the temporary password as a new password or enable the admin or root passwords. It only provides one-time access to the UI.
Disabling a password for UI login also disables it for SSH access.
Accessing the System Through an SSH Session
To enable SSH access to the system as an admin user (or root user), you must first configure the SSH service.
Go to System > Services, then click Edit for the SSH service.
Enter the groups (truenas_admin, root, etc.) you want to enable for password authentication in the Password Login Groups field.
Enable Allow Password Authentication.
Click Save and restart the SSH service.
Now you must verify the user configuration options to allow SSH access.
Using the Root User in SSH
If you want to SSH into the system as the root:
Go to Credentials > Users and click the root user, then click Edit.
Make sure Disable Password is disabled. If the root user has Disable Password enabled, you cannot use it to gain SSH access to the system.
Click Save.
Allowing an Admin User to Enter Commands in SSH
To allow an admin user to issue commands in an SSH session:
Go to Credentials > Users, click the admin user, then click Edit.
Select SSH Access.
Enable SSH password login enabled under Authentication.
Click Save.
Disable this after completing the SSH session to return to a security-hardened system.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
Two-Factor Authentication (2FA) and Administrator Account Log In
To use two-factor authentication with an administrator account, configure and enable SSH service to allow SSH access, then configure two-factor authentication.
If you have the root user configured with a password and it is enabled, you can SSH into the system as the root user.
Disable the root user password and only use a local administrator account for more security.
Administrator Logins and TrueCommand
Administrator logins work with TrueCommand, but you need to set up the TrueNAS connection using an API key.
Managing Users
In TrueNAS, user accounts allow flexibility for accessing shared data.
Typically, administrators create users and assign them to groups.
Doing so makes tuning permissions for large numbers of users more efficient.
When the network uses a directory service, import the existing account information using the instructions in Directory Services.
Using Active Directory requires setting Windows user passwords in Windows.
TrueNAS hides all built-in users (except root) by default.
Click the down arrow in the Filter by Type dropdown field to see all user options, including Built-In, Local (default option), and Directory Services.
You can select any or all options to show all users configured in TrueNAS.
To filter the user table, click the header column name to sort in ascending/descending order. You can also use the advanced search option to select the search criteria you want to use for a user or type of user.
Creating an Administrator User Account
Root account logins are deprecated in TrueNAS Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS plans to permanently disable root account access in a future release.
The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations.
Earlier releases of TrueNAS with the admin account retain this account when upgrading to 24.10 through the UI.
To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin).
Configure appropriate administrative privileges for each admin account.
Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user.
If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete.
See Security Recommendations and Allowing Sudo Commands for more information.
After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s).
Go to Credentials > Users, click on the user, and select Edit.
Click the Disable Password toggle to disable the password, then click Save.
Assigning Administrative Group Privileges
TrueNAS 24.04 or newer supports administrator privileges for role-based administrator accounts.
Users can create new administrator accounts with limited privileges based on their needs.
Predefined administrator roles are read-only, share admin, and the default full access administrator account.
See Using Administrator Logins for more information.
Go to Credentials > Groups and select the row for primary group of the admin user to expand it.
Click editEdit.
Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.
Use the Privileges dropdown to select assign permissions as Local Administrator to allow full administrative access or select Read-Only Administrator or Sharing Administrator to limit permissions.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
Click Save.
After creating a new group, click groupMembers to open the Update Members screen and assign one or more administrative user accounts to the group.
Click Save.
Log out of the TrueNAS system and then log back in using the new user credentials to verify that the admin credentials work properly with your network configuration.
Creating User Accounts
SMB Access is the default user access type that allows using the account credentials to access data shared with SMB.
When creating a user, you must:
Enter a Full Name or description for the user, such as a first and last name.
Enter a Username.
Enter a Password.
Specify or accept the default user ID (UID)
TrueNAS requires other options based on the level of access and role assigned to the user.
The Shell option only shows for users with Shell Access or SSH Access selected.
To manually add a new user, click Credentials > Users, and then click Add to open the Add User screen.
Enter a username for the user. Names are case sensitive!
Set the level of access given to this user.
SMB Access is selected by default.
Select TrueNAS Access, then select 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.
Set up SSH authentication.
These options only show when you select the SSH Access 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.
Shell Access and SSH Access show the Shell and Sudo Command 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.
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list.
Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting or enter a new UID.
TrueNAS suggests a user ID starting at 3000, but you can change it if you wish.
We recommend using an ID of 3000 or greater for non-built-in users.(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
When creating a user, the default home directory path is set to /var/empty.
This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.
If set to this path TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory.
The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset.
After clicking on a dataset, the Create Dataset option activates.
Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
Why did this change in TrueNAS 24.04 (Dragonfish) and later?
TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist.
pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure.
This does not impact other PAM API calls, for example, pam_authenticate().
TrueNAS 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on TrueNAS versions before 24.04.
Starting in TrueNAS 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did.
This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To improve security, deny sudo permissions unless required for specific, recurring administrative tasks, or allow sudo permissions only when needed to perform a discrete task, and then deny again when finished.
Do not allow sudo permissions for read-only administrators.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password.
To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password.
To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
/usr/bin/ is the default location for commands.
Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.
Disabling a Password
To disable a password, select the user, click Edit, and then select Disable Password.
Note that Disable Password is not available when SMB Access is enabled.
Setting Disable Password hides the Password widget, and TrueNAS removes any existing password from the account.
TrueNAS restricts the account from password-based logins for services like SMB shares and SSH sessions.
To disable all password-based functionality for the account, select the Lock User option on the Access widget.
This toggles to Unlock User when locked.
Adding Home Directories
You can add a home directory to a new or an existing user account.
You can create a dataset to use for user home directories if one does not exist before you add or edit a user. You can also create one while adding or editing the user.
To add a home directory to an existing user, go to Credentials > Users, click on the user row, and then click Edit to open the Edit User screen.
Scroll down to the Home Directory option, click in the field to show the settings.
Select Create Home Directory, then enter or browse to select the path to the dataset for home directories in Home Directory. For example, change /var/empty/ to the path to a new dataset.For example, /tank/homedirs.
Accept the default permissions or clear the checkmark to select the level of permissions you want to apply.
We recommend leaving the default selections, Read/Write/Execute selected for the user home directory.
Click Save. TrueNAS creates a new home directory for the user.
Editing User Accounts
To edit an existing user account, go to Credentials > Users.
Click anywhere on the user row, then click Edit to open the Edit User configuration screen.
See Users Screen for details on all settings.
Setting Up and Using API Keys
To view API keys that are linked to different user accounts, go to the Settings icon on the top toolbar and select My API Keys.
You can also go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen.
If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.
The Users API Keys screen shows a table of all API keys linked to user accounts on your TrueNAS.
You can edit or delete your API keys in the User API Keys screen.
Click editEdit to open the Edit API Key screen.
Click deleteDelete to delete an API key.
Adding an API Key
To add an API key for a user, select the user row on the Users table, and then click Add API Key to open the Add API Key screen.
Enter a name for the key, select the user in the Username dropdown list field if not already populated with the correct username, and click Save.
To set the API key to expire, clear the checkmark in Non-expiring, then select the date using the calendar option in the field to set when this key expires.
After setting the date, click Save. The Access widget for this user shows the API Key icon and the View API Keys link.
Clearing Two-Factor Authentication for a User
Administrators can clear two-factor authentication (2FA) for a user from the Users screen. This is typically necessary when:
A user has lost access to their authenticator device (lost phone, broken device, etc.)
A user cannot generate valid 2FA codes due to device time synchronization issues
A user needs to switch to a different authenticator app or device
Troubleshooting 2FA-related login problems
Clearing 2FA should only be done when necessary, as it temporarily reduces account security. When Global 2FA is enabled, users are prompted to reconfigure 2FA on their next login.
To clear 2FA for a user:
Go to Credentials > Users.
Click on the user row to select the user whose 2FA needs to be cleared.
On the Access widget, click Clear Two-Factor Authentication.
Click Clear to confirm, or Cancel to abort the operation.
After clearing, the user can log in without 2FA codes. If Global 2FA is enabled on the system, the user is prompted to set up 2FA again on their next login.
User Self-Clearing vs Admin Clearing
Users can also remove their own 2FA configuration using the Settings menu:
User self-clearing: The logged-in user accesses Settings > Two-Factor Authentication and clicks Unset 2FA Secret. This allows users to manage their own 2FA settings.
Admin clearing: Administrators use Credentials > Users > Access Widget > Clear Two-Factor Authentication to clear 2FA for another user. This is specifically for helping users who cannot access their accounts.
For more information on 2FA configuration and management, see Managing Global 2FA.
Managing Groups
TrueNAS offers groups as an efficient way to manage permissions for many similar user accounts.
See Users for managing users.
The interface lets you manage UNIX-style groups.
If the network uses a directory service, import the existing account information using the instructions in Active Directory.
By default, TrueNAS hides the built-in groups in the system.
To see built-in groups, click the Show Built-In Groups toggle. The toggle turns blue and shows all built-in groups.
Click the Show Built-In Groups toggle again to show only non-built-in groups on the system.
Adding a New Group
To create a group, go to Credentials > Groups and click Add.
Enter a unique number for the group ID in GID. TrueNAS uses this to identify a Unix group.
Enter a number above 3000 for a group with user accounts or enter the default port number as the GID for a system service.
Enter a name for the group.
The group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?) greater or less than (<) (>), equal (=). The dollar sign ($) can be the last character in a group name.
If required, set the sudo permissions to assign.
For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task.
See Allowing Sudo Commands for more information.
To allow Samba permissions and authentication to use this group, select SMB Group.
Using the same group ID (GID) is not permitted as it can create confusion. The operating system treats it as the same group, even if a different name is assigned.
Select SMB Group to make this group available for permissions editors over SMB protocol, and add the share ACL editor.
This is not used for SMB authentication or when determining the user session token or internal permissions checks.
Click Save.
Managing Groups
Click anywhere on a row to expand that group and show the group management buttons.
To add a user account to the group, select the user and then click the right arrow .
To remove a user account from the group, select the user and then click the left arrow .
To select multiple users, press Ctrl and click on each entry.
Click Save.
Edit Group
To edit an existing group, go to Credentials > Groups, expand the group entry, and click editEdit to open the Edit Group configuration screen. See Groups Screens for details on all settings.
Managing Privileges
Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges ares:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/execute permissions) to the user.
Active Directory can provision groups in TrueNAS or you can add new groups that you assign to users in AD.
After adding a group, verify or edit the privilege(s) granted to the users in the group.
Adding a Privilege
To configure a new privilege, go to Credentials > Groups, click on Privileges to open the Privileges screen.
Click Add to define a new privilege. For example, if you want to create an group with the ability to only perform and manage backup, replication, or some other task.
You can create a new privilege to customize the functional access you want to grant.
On the New Privilege screen:
Enter a name for the new privilege. Names can include the dash (-) or underscore (_) special characters, and upper and lowercase alphanumeric characters.
Make the name descriptive of the privilege. For example, Replication Administrator, Backup Administrator, iSCSI Share Admin, etc.
You can create a privilege that can only manage iSCSI shares or one that can manage applications based on the selections made in the Roles field.
Click in the Local Groups field to see a list of groups on the system. To add another group, click in the field to select another group.
Click the x to the right of the group name to remove that group from the privilege.
Click the down arrow at the right of the Roles field to show the list of roles configured on the system. Select all roles to include.
Use the scroll bar at the right of the field to see all options.
Select Web Shell Access to allow access to the shell screen in the TrueNAS UI.
Click Save to create the new privilege.
Users assigned to the group show on the Users screen with the new privilege granted to the user in the Roles column, and the new group shows on the Groups screen with privilege listed in the Roles column.
Setting Up Directory Services
The TrueNAS Directory Services tutorials contain options to edit directory domain and account settings, set up ID mapping, and configure authentication and authorization services in TrueNAS.
About Directory Services
TrueNAS provides unified directory services configuration that supports connecting to Active Directory domains or LDAP servers through a single, streamlined interface. The directory services configuration screen allows you to set up authentication credentials, connection parameters, and advanced options in one location.
Only one directory service type can be configured and enabled at a time.
To view Idmap and Kerberos Services, click Show next to Advanced Settings.
Configuring IPA: Provides instructions on configuring and managing IPA configurations in TrueNAS.
Configuring LDAP: Provides instructions on configuring and managing LDAP configurations in TrueNAS.
Configuring Kerberos: Provides instructions on configuring and managing Kerberos realms and keytabs in TrueNAS.
Configuring Active Directory
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Configuring TrueNAS Active Directory Access
The Active Directory (AD) service shares resources in a Windows network.
AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.
When joined to an AD domain, you can use domain users and groups in local ACLs on files and directories.
You can also set up shares to act as a file server.
Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.
Users can configure AD services on Windows or Unix-like operating systems using Samba version 4.
Preparing to Configure AD in TrueNAS
Before configuring Active Directory (AD) in TrueNAS:
You need to know the hostname assigned to the TrueNAS system. The default value is truenas.
The Domain Account Name default is Administrator, or enter a name for TrueNAS to generate as the computer account upon domain join.
Enter the password for this account.
Verify name resolution.
Go to Network > Global Network Settings to verify your TrueNAS network DNS name servers are configured with the target domain controller address that you plan to add on the Active Directory screen.
Change the default hostname of the system from truenas to the name assigned to the TrueNAS system.
NetBIOS names (workgroup, domain, and computer names) are limited to 15 characters and cannot contain the following characters: \ / : * ? " < > |
Microsoft and RFC 852 define reserved words that should not be used as NetBIOS names. TrueNAS 25.04 and later enforce these restrictions through validation.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
If you encounter validation errors when joining Active Directory or configuring SMB services, verify that your NetBIOS Name, Workgroup, and Domain Name comply with these requirements.
Setting Time Synchronization
Active Directory relies on the time-sensitive Kerberos protocol.
TrueNAS adds the AD domain controller with the PDC Emulator FSMO Role as the preferred NTP server during the domain join process.
If your environment requires something different, go to System > Advanced Settings, click Add to open the NTP Servers screen, then add a new or edit a listed server.
Keep the local system time sync within five (5) minutes of the AD domain controller time in a default AD environment.
Use an external time source when configuring a virtualized domain controller.
TrueNAS generates alerts if the system time gets out of sync with the AD domain controller time.
TrueNAS has a few options to ensure both systems are synchronized. Either:
Go to System > General Settings, click Settings in the Localization widget, and set Timezone to the value that matches the location of the AD domain controller.
Set the system BIOS to either local time or universal time.
Connecting to the Active Directory Domain
Before you begin, modify the system DNS server settings.
Take a screenshot of your current settings to refer to if you need to revert to pre-AD settings for any reason.
Change the nameserver 1 setting to the IP address of the AD server and clear the other name server settings.
Make sure the domain name is set to something other than the default value truenas.
To connect TrueNAS to Active Directory:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select Active Directory from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the AD configuration.
Leave the Enable Account Cache checkbox selected to cache user and group information.
Caching makes directory users and groups available in UI dropdown menus.
Users with large domains should consider disabling account caching in order to reduce the load on domain controllers.
Leave the Enable DNS Updates checkbox selected to allow the directory service to update DNS records.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds).
Enter the Kerberos realm in Kerberos Realm. TrueNAS auto-populates this field after joining the domain.
Select Kerberos User from the Credential Type dropdown list. Required.
Enter the AD domain administrator username in Username. Required. Enter only the username (for example, Administrator), not the domain-prefixed format.
Enter the password for the administrator account in Password. Required.
Enter the required Active Directory Configuration settings:
Enter the TrueNAS hostname in TrueNAS Hostname. This value must match the Hostname setting on the Network > Global Configuration screen and cannot exceed 15 characters.
Enter the Active Directory domain name in Domain Name. For example, example.com or sales.example.com if configuring access to a child domain.
(Optional) Enter the site name in Site Name.
(Optional) Enter the organizational unit in Computer Account OU. This controls the location where the TrueNAS computer object is created when joining the Active Directory domain for the first time. The OU string includes the distinguished name (DN) of the Computer Account OU. For example, OU=Computers,DC=example,DC=com.
(Optional) Select the Use Default Domain checkbox to remove the domain name prefix from AD users and groups. This setting might be required for specific configurations such as Kerberos authentication with NFS for AD users. Using this setting can cause collisions with local user account names.
(Optional) Configure trusted domains:
Select the Enable Trusted Domains checkbox to allow clients to access TrueNAS if they are members of domains with a trust relationship.
Starting in TrueNAS 25.10, trusted domains are configured as part of the Active Directory configuration rather than as separate IDmap entries.
When selected, you can add trusted domain configurations. Each trusted domain requires an IDMAP Backend selection.
Configure IDMAP settings:
IDMAP (Identity Mapping) ensures that UIDs and GIDs assigned to Active Directory users and groups have consistent values domain-wide. By default, TrueNAS uses an algorithmic method based on the RID component of the user or group SID, which is suitable for most environments. Only administrators experienced with configuring ID mapping should customize IDMAP settings. Misconfiguration can lead to permissions incorrectly assigned to users or groups when data is transferred via ZFS replication or rsync, or when accessed via NFS or other protocols that directly access UIDs/GIDs on files.
TrueNAS creates the default Kerberos realm and principal, and the Computer Account OU value.
If you get a DNS server error, go to Network > Global Configuration, click Settings, and verify the DNS nameserver IP addresses are correctly configured with addresses that permit access to the Active Directory domain controller.
Correct any network configuration settings, then reconfigure the Active Directory settings.
TrueNAS offers advanced options for fine-tuning the AD configuration, but the preconfigured defaults are generally suitable.
I don't see any AD information!
TrueNAS can take a few minutes to populate the Active Directory information after configuration.
To check the AD join progress, open the assignmentTask Manager in the upper-right corner.
TrueNAS displays any errors during the join process in the Task Manager.
When the import completes, AD users and groups become available while configuring basic dataset permissions or an ACL with TrueNAS cache enabled (enabled by default).
Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab.
TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.
Understanding IDMAP Backends
When customizing IDMAP settings, you can select from several backend options. Each backend uses a different method to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs:
AD - Reads UID and GID mappings from an Active Directory server that uses pre-existing RFC2307 / SFU schema extensions.
AUTORID - Automatically allocates UID and GID ranges for each domain. Useful for environments with multiple trusted domains.
LDAP - Reads and writes UID / GID mapping tables from an external LDAP server.
NSS - Uses the Name Service Switch (NSS) to retrieve Unix user and group information from local or network sources.
RFC2307 - Reads ID mappings from RFC2307 attributes on a standalone LDAP server. This backend is read-only.
RID - Uses an algorithm to map UIDs and GIDs to SIDs. It determines the UID or GID by adding the RID value from the Windows Account SID to the base value in range_low.
TDB - Stores ID mappings in a local Trivial Database (TDB) file. Allocates new UIDs and GIDs as needed. Useful for standalone servers but not recommended for multi-server environments as mappings are not shared.
For most environments, the default RID backend provides consistent, reliable ID mapping without additional configuration.
Troubleshooting - Resyncing the Cache
If the cache becomes out of sync or fewer users than expected are available in the permissions editors, click Settings in the Active Directory widget, then click Rebuild Directory Service Cache to resync the cache.
The name in TrueNAS Hostname should match the name in Hostname on the Network > Global Configuration screen.
Disabling Active Directory
To disable your AD server connection without deleting your configuration or leaving the AD domain, click Settings in the Active Directory widget to open the Active Directory settings screen.
Clear the Enable Service checkbox and click Save to disable the AD service.
This returns you to the main Directory Services screen.
Click Configure Directory Services to open the Directory Services Configuration form with your existing configuration settings.
Select Enable Service again, and click Save to reactivate your connection to your AD server.
Leaving Active Directory
Users must cleanly leave an Active Directory for TrueNAS to delete the configuration.
To cleanly leave AD, click Leave Domain on the Active Directory settings screen to remove the AD object.
Remove the computer account and associated DNS records from the Active Directory.
If the AD server moves or shuts down without you using Leave Domain, TrueNAS does not remove the AD object, and you have to clean up the Active Directory.
Configuring IPA
TrueNAS supports IPA (Identity, Policy, and Audit) as a comprehensive identity management solution.
IPA integrates LDAP, Kerberos, NTP, and DNS services in a single package, providing centralized authentication and authorization for network resources.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Does IPA work with SMB?
IPA can work with SMB shares when properly configured.
IPA includes integrated Samba support and can provide user and group information for SMB authentication.
TrueNAS validates the full certificate chain when certificate validation is enabled.
TrueNAS does not support non-CA certificates when certificate validation is required.
Configuring IPA
Configure TrueNAS to use an IPA directory server:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select IPA from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the IPA configuration. Selected by default.
Select the Enable Account Cache checkbox to cache user and group information. Caching makes directory users and groups available in UI dropdown menus. Selected by default.
Select the Enable DNS Updates checkbox to allow the directory service to update DNS records. Selected by default.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds). Required.
Enter the domain name in Kerberos Realm. This is usually the uppercase version of the domain name, for example, EXAMPLE.COM.
Enter the IPA server hostname or IP address in Target Server. Required.
Enter the hostname for your TrueNAS system in TrueNAS Hostname. Required.
Enter the domain name in Domain. Required.
Enter the base distinguished name for the IPA directory in Base DN. Required. For example, dc=example,dc=com.
(Optional) Select the Validate Certificates checkbox to verify certificate authenticity when connecting to the IPA server. TrueNAS validates the full certificate chain when this option is selected.
Select Use Default SMB Domain Configuration to use default SMB domain settings. Selected by default.
To customize SMB domain settings, clear Use Default SMB Domain Configuration to reveal additional configuration options: Name, Domain Name, Range Low, Range High, and Domain SID.
Click Save.
Disabling IPA
Clear the Enable Service checkbox to disable the IPA directory server. This does not remove the configuration.
The main Directory Services screen returns to the default view showing the option to configure directory services.
Click Configure Directory Services to open the Directory Services Configuration form with the saved IPA configuration to enable IPA again. Select Enable Service again to reactivate your IPA directory server configuration.
Removing IPA from TrueNAS
Click Settings to open the IPA screen to remove the IPA configuration.
Clear all settings and click Save.
Configuring LDAP
TrueNAS has an Open LDAP client for accessing the information on an LDAP server.
An LDAP server provides directory services for finding network resources like users and their associated permissions.
You can have either Active Directory, LDAP, or IPA configured on TrueNAS but not multiple directory services simultaneously.
Does LDAP work with SMB?
LDAP authentication for SMB shares is disabled unless you configured and populated the LDAP directory with Samba attributes.
The most popular script for performing this task is smbldap-tools.
TrueNAS needs to be able to validate the full certificate chain (no self-signed certificates).
TrueNAS does not support non-CA certificates.
Configuring LDAP
To configure TrueNAS to use an LDAP directory server:
Go to Credentials > Directory Services and click Configure Directory Services to open the Directory Services Configuration form.
Select LDAP from the Configuration Type dropdown list.
Select the Enable Service checkbox to activate the LDAP configuration. Selected by default.
Select the Enable Account Cache checkbox to cache user and group information. Caching makes directory users and groups available in UI dropdown menus. Selected by default.
Select the Enable DNS Updates checkbox to allow the directory service to update DNS records. Selected by default.
Enter the number of seconds (1-40) before the directory service connection times out in Timeout (seconds). Required.
(Optional) Enter the Kerberos realm in Kerberos Realm. This is usually the uppercase version of the domain name, for example, EXAMPLE.COM.
Enter the Credential Configuration settings:
Select the credential type from the Credential Type dropdown list. Options are LDAP Anonymous, LDAP Plain, LDAP MTLS, Kerberos Principal, or Kerberos User. Required.
If you selected Kerberos User, enter the LDAP administrative account username and password in the respective Username and Password fields. Required.
If you selected LDAP Plain, enter the applicable credentials in the Bind DN and Bind Password fields. Required.
If you selected LDAP MTLS, select the desired Client Certificate from the dropdown menu. Required.
If you selected Kerberos Principal, select the desired Kerberos Principal from the dropdown menu. Required.
Enter the LDAP server URLs in Server URLs. Required. Separate multiple entries by pressing Enter. If using a cloud service LDAP server, do not include the full URL.
Enter the LDAP server base DN in Base DN. Required. This is the top level of the LDAP directory tree to use when searching for resources. For example, dc=example,dc=org.
(Optional) Select the Start TLS checkbox if needed for your environment.
(Optional) Select the Validate Certificates checkbox to verify certificate authenticity when connecting to the LDAP server.
Select the LDAP NSS schema from the Schema dropdown list. Required. Options are RFC2307 or RFC2307BIS.
(Optional) Configure auxiliary parameters:
Select Use Standard Auxiliary Parameters to use default auxiliary parameters. Selected by default.
To customize auxiliary parameters, clear Use Standard Auxiliary Parameters to reveal the Auxiliary Parameters text field where you can enter custom options for nslcd.conf.
(Optional) Configure search bases:
Select Use Standard Search Bases to use default search bases. Selected by default.
To customize search bases, clear Use Standard Search Bases to reveal additional configuration options: User Base DN, Group Base DN, and Netgroup Base DN.
(Optional) Configure attribute maps:
Select Use Standard Attribute Maps to use default attribute mappings. Selected by default.
To customize attribute maps, clear Use Standard Attribute Maps to reveal four subsections for customization:
LDAP Password Attributes - Enter custom password attribute mappings.
LDAP Shadow Attributes - Enter custom shadow attribute mappings.
LDAP Group Attributes - Enter custom group attribute mappings.
LDAP Net Group Attributes - Enter custom net group attribute mappings.
Click Save.
Disabling LDAP
To disable LDAP but not remove the configuration, clear the Enable Service checkbox. The main Directory Services screen returns to the default view showing the option to configure directory services.
To enable LDAP again, click Configure Directory Services to open the Directory Services Configuration form with your saved LDAP configuration. Select Enable Service again to reactivate your LDAP directory server configuration.
Removing LDAP from TrueNAS
To remove the LDAP configuration, click Settings on the LDAP widget to open the Directory Services Configuration screen.
Click Clear Config to open the confirmation dialog.
Click Confirm to remove the LDAP configuration. The main Directory Services screen returns to the default view showing the option to configure directory services.
Configuring Kerberos
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory, TrueNAS populates the realm fields and the keytab with what it discovers in AD.
You can configure LDAP to communicate with other LDAP severs using Kerberos, or NFS if it is properly configured, but TrueNAS does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos uses realms and keytabs to authenticate clients and servers.
A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client.
By default, TrueNAS creates a Kerberos realm for the local system.
A keytab (“key table”) is a file that stores encryption keys for authentication.
TrueNAS allows users to configure general Kerberos settings, as well as realms and keytabs.
Kerberos Realms
TrueNAS automatically generates a realm after you configure AD.
To configure Kerberos realms:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Realms widget to open the Add Kerberos Realm screen.
Enter the realm name in Realm. Required. Enter the name as a domain name, for example, example.com.
(Optional) Enter the Key Distribution Center name in KDC. The KDC acts as the third-party authentication service for Kerberos. If left blank, TrueNAS uses DNS discovery to locate the KDC. Separate multiple values by pressing Enter.
(Optional) Enter the primary KDC in Primary KDC. The Kerberos client uses this KDC when acquiring credentials if the current KDC fails with a bad password error. This is valuable for domains with hub-and-spoke topology.
(Optional) Enter the server that performs all database changes in Admin Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
(Optional) Enter the server that performs all password changes in Password Server. If left blank, TrueNAS uses DNS discovery. Separate multiple values by pressing Enter.
Click Save.
Kerberos Keytabs
TrueNAS automatically generates a keytab after you configure AD.
A Kerberos keytab is a file containing one or more Kerberos principals with their associated encryption keys. TrueNAS automatically generates a keytab during the Active Directory domain join process. The keytab principals are typically associated with the TrueNAS host computer account.
Keytabs allow authentication without requiring password storage. TrueNAS does not store the Active Directory or LDAP administrator account password in the system database after the keytab is created.
Adding a Keytab to TrueNAS
After generating the keytab:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Add in the Kerberos Keytabs widget to open the Add Kerberos Keytab screen.
Enter a name for the keytab in Name. If configured, TrueNAS populates this field with what it detects in Active Directory.
Browse to the keytab file in Kerberos Keytab and upload it.
Click Save.
Using a Keytab with Active Directory or LDAP
To configure AD to use a keytab, go to the Directory Services screen, click Settings in the Active Directory widget, and select the keytab using the Kerberos Principal dropdown list.
The keytab must correspond to the computer account created during the domain join process.
To configure LDAP to use a keytab principal, click Settings in the LDAP widget and select the keytab using the Kerberos Principal dropdown list.
Synchronizing Keytabs with Active Directory
When TrueNAS is joined to Active Directory, you can synchronize Kerberos keytabs with Active Directory to ensure keytab data remains current.
To synchronize keytabs:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Sync in the Kerberos Keytabs widget header to open the synchronization confirmation dialog.
Click Sync to synchronize the keytabs with Active Directory.
The Sync button only appears when the system is joined to Active Directory.
Kerberos Settings
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
The Kerberos Settings screen is available in Advanced Settings for configuring auxiliary parameters.
To access Kerberos Settings:
Go to Credentials > Directory Services and click Show in Advanced Settings, then click Continue on the warning dialog.
Click Settings in the Kerberos Settings widget to open the Kerberos Settings screen.
(Optional) Enter additional Kerberos application settings in Appdefaults Auxiliary Parameters. See the appdefaults section of krb.conf(5) for available settings and usage syntax.
(Optional) Enter additional Kerberos library settings in Libdefaults Auxiliary Parameters. See the libdefaults section of krb.conf(5) for available settings and usage syntax.
Click Save.
Backup Credentials
TrueNAS backup credentials store cloud backup services credentials, SSH connections, and SSH keypairs.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
Contents
Adding Cloud Credentials: Provides basic instructions on adding backup cloud credentials and more detailed instructions for some cloud storage providers.
Adding SSH Credentials: Provides information on adding SSH connections, generating SSH key pairs, and adding the SSH public key to the root user.
Adding Cloud Credentials
The Cloud Credentials screen, accessed from the Backup Credentials screen allows users to integrate TrueNAS with cloud storage providers.
These providers are supported for Cloud Sync tasks in TrueNAS:
*TrueCloud backup tasks streamline functionality for Storj iX cloud backups and restoration.
To maximize security, TrueNAS encrypts cloud credentials when saving them.
However, this means that to restore any cloud credentials from a TrueNAS configuration file, you must enable Export Password Secret Seed when generating that configuration backup.
Remember to protect any downloaded TrueNAS configuration files.
Authentication methods for each provider could differ based on the provider security requirements.
You can add credentials for many of the supported cloud storage providers from the information on the Cloud Credentials Screens.
This article provides instructions for the more involved providers.
Adding a Cloud Credential
We recommend you open another browser tab and log into the cloud storage provider account you intend to link with TrueNAS.
Some TrueNAS providers credentials require entering additional information generated while creating the provider account.
For example, the Storj iX account produces an access and secret key that must be entered in the Cloud Credential screen to create the credential.
Have the authentication information required by your cloud storage provider on hand to make the process easier.
Authentication information can include but is not limited to user credentials, access tokens, and access and security keys.
To add a cloud credential:
Select the cloud service from the Provider dropdown list. The provider required authentication option settings display.
Enter the required authentication credentials, such as access token, access key and/or secret keys, and user credentials for the account into the appropriate fields.
Click Verify Credentials to verify the entered credentials work.
Click Save.
Adding Storj Cloud Credentials
Storj iX is the default cloud storage provider in TrueNAS.
Go to Credentials > Backup Credentials and click Add on the Cloud Credentials widget.
The Cloud Credentials screen opens with Storj displayed as the default provider in the Provider field.
You must use this link to create your Storj account to take advantage of the benefits of the Storj iX pricing!
Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, and click the button at the bottom of the screen.
The Storj main dashboard opens.
The endpoint set in the Storj credential applies to all Cloud Sync Tasks that use that credential.
After creating your Storj account and obtaining your S3 credentials, optionally specify a custom Endpoint to use a specific Storj tier (such as Global or Select). Leave the Endpoint field blank to use the default Storj endpoint.
Creating the Storj iX Account
Setting Up S3 Access
After creating your Storj iX account, add S3 access credentials.
Click Access Keys to open the Access Keys dashboard, then click New Access Key.
Select the permissions you want to allow this access key.
Choose Full Access to allow permanent full permissions to all buckets and data then click Create Access or select Advanced then click Next to customize access configuration.
b. Select the buckets to allow access to.
Click All Buckets or click Select Buckets and use the Buckets dropdown to select one or more bucket(s).
Click Next.
c. Select an expiration date if you want to set the duration or length of time to allow this credential to exist.
You can select a preset period, click Set Custom Expiration Date to use the calendar to set the duration, or select No expiration.
Click Next to open the Access Encryption window.
You can either create a TrueNAS compatible Storj bucket while configuring cloud credentials or wait to do so while configuring a TrueCloud back up or Cloud Sync task.
Not all Storj buckets are TrueNAS compatible.
To create a TrueNAS-compatible bucket, either log in to Storj using the ix Storj affiliate link before creating the bucket in the Storj UI, or use the TrueNAS UI to create the bucket using the Add New option.
To create a Storj bucket from the TrueNAS UI:
Go to Data Protection.
Click Add on either the TrueCloud Backup Tasks or Cloud Sync Tasks widget.
Select the stored Storj cloud credential from the Provider > Credentials dropdown.
Do this as part of setting up a task or use the wizard to create the bucket without saving a configured task.
Click Verify Credential for verification, then click Next to go to the What and When screen.
Click Save.
TrueNAS creates the remote bucket on Storj and then returns to the Cloud Sync Task Wizard.
Adding Amazon S3 Cloud Credentials
When adding an Amazon S3 cloud credential, you can either use the default authentication settings or advanced settings if you want to include endpoint settings.
To add a cloud credential for Amazon S3, select Amazon S3 in Provider, enter a name and then:
Navigate to My account > Security Credentials > Access Keys to obtain the Amazon S3 secret access key ID.
Access keys are alphanumeric and between 5 and 20 characters.
If you cannot find or remember the secret access key, go to My Account > Security Credentials > Access Keys and create a new key pair.
Enter or copy/paste the access key into Access Key ID.
Enter or copy/paste the Amazon Web Services alphanumeric password that is between 8 and 40 characters into Secret Access Key
(Optional) Enter a value to define the maximum number of chunks for a multipart upload in Maximum Upload Ports.
Setting a maximum is necessary if a service does not support the 10,000-chunk AWS S3 specification.
(Optional) Select Advanced Settings to display the endpoint settings.
To use the default endpoint for the region and automatically fetch available buckets leave this field blank.
For more information refer to the AWS Documentation for a list of Simple Storage Service Website Endpoints.
To detect the correct public region for the selected bucket leave the field blank.
Entering a private region name allows interaction with Amazon buckets created in that region.
c. (Optional) Configure a custom endpoint URL.
d. (Optional) Select Disable Endpoint Region to prevent automatic detection of the bucket region.
Enable only if your AWS provider does not support regions.
d. (Optional) Select Use Signature Version 2 to force using signature version 2 with the custom endpoint URL.
Select only if your AWS provider does not support default version 4 signatures.
For more information on using this to sign API requests see Signature Version 2.
Click Verify Credentials to check your credentials for any issues.
Click Save
Adding Cloud Credentials that Authenticate with OAuth
Cloud storage providers using OAuth as an authentication method are Box, Dropbox, Google Drive, Google Photos, pCloud, and Yandex.
Some providers like Google Drive and pCloud use additional settings to authenticate credentials.
Open the Cloud Credentials screen, select the name of the cloud storage provider on the Provider dropdown list, enter a name for the credential, and then:
Enter the provider account email in OAuth Client ID and the password for that user account in OAuth Client Secret.
Click Log In To Provider. The Authentication window opens. Click Proceed to open the OAuth credential account sign-in window.
Yandex displays a cookies message you must accept before you can enter credentials.
Enter the provider account user name and password to verify the credentials.
(Optional) Enter the value for any additional authentication method.
For pCloud, enter the pCloud host name for the host you connect to in Hostname.
For Google Drive when connecting to Team Drive, enter the Google Drive top-level folder ID.
Enter the access token from the provider if not populated by the provider after OAuth authentication. Obtaining the access token varies by provider.
Provider
Access Token
Box
For more information on the user access token for Box click here. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
The authentication process creates the token for Google Drive and populates the Access Token field automatically. Access tokens expire periodically, so you must refresh them.
Google Photo
Does not use an access token.
pCloud
Create the pCloud access token here. These tokens can expire and require an extension.
Click Verify Credentials to make sure you can connect with the entered credentials.
Click Save.
Adding BackBlaze B2 Cloud Credentials
BackBlaze B2 uses an application key and key ID to authenticate credentials.
Open the Cloud Credentials screen, select BackBlaze B2 in Provider, enter a name and then:
Log into the BackBlaze account, go to the App Keys page, and add a new application key. Copy and paste this into Key ID.
Generate a new application key on the BackBlaze B2 website.
From the App Keys page, add a new application key. Copy the application Key string Application Key.
Click Verify Credentials.
Click Save.
Adding Google Cloud Storage Credentials
Google Cloud Storage uses a service account JSON file to authenticate credentials.
Open the Cloud Credentials screen, select Google Cloud Storage in Provider, enter a name and then:
Go to your Google Cloud Storage website to download this file to the TrueNAS server.
The Google Cloud Platform Console creates the file.
Click Choose File to browse the server to locate the downloaded JSON file and upload it. The file populates Preview JSON Service Account Key
For help uploading a Google Service Account credential file click here.
Click Verify Credentials.
Click Save.
Adding OpenStack Swift Cloud Credentials
OpenStack Swift authentication credentials change based on selections made in AuthVersion.
All options use the user name, API key or password, and authentication URL, and can use the optional endpoint settings.
For more information on OpenStack Swift settings, see rclone documentation.
Open the Cloud Credentials screen, select OpenStack Swift Cloud in Provider, enter a name for the credential and then:
(Optional) Select the version from the AuthVersion. For more information see rclone documentation.
Select the desired option based on your use case.
Set Auth(vx) to V1 or V2
d. Enter the ID in Tenant ID. Required for v2 and v3 and (optional) enter a Tenant Domain.
e. (Optional) Enter the alternative authentication token in Auth Token.
f. Enter a region name in Region Name
g. (Optional) Enter the URL in Storage URL.
h. (Required) Select the service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended.
Click Verify Credentials.
Click Save.
Adding Microsoft OneDrive Credentials
Microsoft OneDrive uses OAuth authentication to connect TrueNAS to your cloud account.
Open the Cloud Credentials screen, select Microsoft OneDrive in Provider, enter a name and then:
Click Log In To provider to open the Microsoft sign-in page in a new window. You can confirm the intended authorization in the new window.
Confirm the authorization to enter your Microsoft login information. After logging in to your account, Microsoft prompts you to give TrueNAS access to your Microsoft information.
Give TrueNAS access to your Microsoft account and close the pop-up window. Your Cloud Credentials wizard should now say Logged In To Provider and have populated OAuth Client ID, OAuth Client Secret, Access Token, and Drive Account Type fields.
(Optional) Select an entry from the Drives List drop-down menu. This will also populate the Drive ID field.
Choose a drive from your OneDrive account and enter the ID in this field. If you selected an entry for Drives List, this field should already be populated with a valid ID.
Click Save.
Using Automatic Authentication
Some providers can automatically populate the required authentication strings by logging in to the account.
To automatically configure the credential, click Login to Provider and enter your account user name and password.
We recommend verifying the credential before saving it.
Adding SSH Credentials
The SSH Connections and SSH Keypairs widgets on the Backup Credentials screen display a list of SSH connections and key pairs configured on the system.
Using these widgets, users can establish Secure Socket Shell (SSH) connections.
You must also configure and activate the SSH Service to allow SSH access.
These SSH credentials are used to manage SSH connections specifically for automated tasks such as replication, backups, cloud sync, or other system-to-system operations. You can generate, store, and manage SSH key pairs and define SSH connections that TrueNAS uses for these automated processes. The key pairs managed here are not tied to individual user but are instead used by the system for secure communication with other systems or services.
For individual user SSH access, configure SSH keys in the user account settings under Credentials > Users.
Creating an SSH Connection
To begin setting up an SSH connection, go to Credentials > Backup Credentials.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Configuring a Semi-Automatic SSH Connection
The procedure in this section covers the semi-automatic setup method for creating an SSH connection with another TrueNAS system.
Semi-automatic simplifies setting up an SSH connection with another TrueNAS system without logging in to that system to transfer SSH keys.
This requires an SSH key pair on the local system and administrator account credentials for the remote TrueNAS.
You must configure the remote system to allow root access with SSH.
You can generate the key pair as part of the semiautomatic configuration or a manually created one using SSH Keypairs.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select the Setup Method.
If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.
If connecting to a non-TrueNAS server select Manual from the dropdown list.
a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL.
If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets.
For example, https://[ffff:ff:59f1:123::12].
b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection.
You can leave Admin Username set to the default root user, then enter the user password in Admin Password.
c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.
d. Enter a Username, which is the user name on the remote system to log in via SSH.
e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection and the SSH Keypairs widgets.
To edit the SSH connection, select it, then click on edit open the SSH Connections configuration screen populated with the saved settings.
To download the private and public keypair, click the file_download for the new keypair on the SSH Keypairs widget.
To view and copy the public or private key, click the Edit option for the keypair to open the Edit Keypair screen.
Configuring a Manual SSH Connection
The instructions in this section cover how to set up an SSH connection to a non-TrueNAS system.
To manually set up an SSH connection, you must copy a public encryption key from the local system to the remote system.
A manual setup allows a secure connection without a password prompt.
Click Add on the SSH Connections widget to open the configuration screen:
Enter a name for the connection, then select Manual from the Setup Method dropdown list.
a. Enter a host name or host IP address for the remote non-TrueNAS system as a valid URL.
An IP address example is https://10.231.3.76.
This is a required field.
b. Enter the port number of the remote system to use for the SSH connection.
c. Enter a user name for logging into the remote system in Username.
d. Select the private key from the SSH key pair that you use to transfer the public key on the remote NAS from the Private Key dropdown.
e. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate the Remote Host Key field.
(Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.
Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The new SSH connection displays on the SSH Connection widget.
To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.
Adding a Public SSH Key to an Admin User Account
This procedure covers adding a public SSH key to the admin account on the TrueNAS system and generating a new SSH Keypair to add to the remote system (TrueNAS or other).
Copy the SSH public key text or download it to a text file:
Log in to the TrueNAS system that generated the SSH key pair and go to Credentials > Backup Credentials.
Click on the name of the key pair on the SSH Keypairs widget to open the key pair for the SSH connection.
Copy the text of the public SSH key or download the public key as a text file.
Add the public key to the admin account on the system where you want to register the public key.
Log in to the TrueNAS system where you want to register the public key and go to Credentials > Users.
Edit the admin account. Select the user, and click Edit to open the Edit User screen.
If the remote NAS is not a TrueNAS system, refer to the documentation for that system and find its instructions on adding a public SSH key.
Generating SSH Keypairs
TrueNAS generates and stores RSA-encrypted SSH public and private key pairs on the SSH Keypairs widget found on the Credentials > Backup Credentials screen.
Key pairs are generally used when configuring SSH Connections or SFTP Cloud Credentials.
TrueNAS does not support encrypted key pairs or key pairs with passphrases.
TrueNAS automatically generates key pairs as needed when creating new SSH Connections or Replication tasks.
To manually create a new key pair:
Click Add on the SSH Keypairs widget.
Click Generate New on the SSH Keypairs screen.
Give the new key pair a unique name and click Save.
The key pair displays on the SSH Keypairs widget.
Click the vertical ellipsis more_vert at the bottom of the SSH Keypairs configuration screen to download these strings as text files for later use.
Certificates
Use the Credentials > Certificates screen to manage certificates, certificate signing requests (CSRs), and DNS authenticators with the Certificates, Certificate Signing Requests (CSRs), and ACME DNS-Authenticators widgets.
Each TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import custom certificates for authentication and validation while sharing data.
Contents
Managing Certificates: Provides information on adding or managing certificates in TrueNAS.
Creating ACME Certificates: Provides information on generating ACME certificates in TrueNAS using Let's Encrypt.
Managing Certificates
The Certificates screen shows information for certificates, certificate signing requests (CSRs), and ACME DNS-authenticators configured on the system, and provides the ability to import or edit them.
TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
The TrueNAS Connect service automatically creates a default truenas_connect_ certificate after registering your TrueNAS system in the TrueNAS Connect service.
The certificate shows in the Certificates widget on the Credentials > Certificates screen.
This certificate provides secure SSL access between the TrueNAS server and the TrueNAS Connect service.
If not listed on the Certificates screen, choose the truenas_default certificate.
For apps where certificates are used, you should see and be able to select the TNC certificate and get a full secure connection for the apps.
Adding Certificates
By default, TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import and edit existing certificates.
To add a certificate to TrueNAS, click Import on the Certificates widget to open the Import Certificates screen.
First, enter a name as a certificate identifier. A name can include the dash (-) or underscore (_) special characters.
Select Add To Trusted Store if you want to add the imported certificate to the trusted store in TrueNAS.
Copy/paste the certificate into the Certificate field, and the private key part of the certificate into the Private Key field.
Enter or copy/paste the password associated with the private key into the Password and Confirm Password fields.
Click Import to add the certificate to TrueNAS.
Editing a Certificate
TrueNAS allows you to rename a certificate or to add it to the TrueNAS trusted store.
Click on the more_vert icon, then select Edit on the dropdown list. The Edit Certificate screen for that certificate opens.
Enter a new name for the certificate.
Select Add To Trusted Store to add the certificate to the TrueNAS trusted store.
Click Save.
Downloading the Certificate or Public Key
Click on the more_vert icon, then select Edit or Download on the dropdown list.
On the Edit Certificate screen for the selected certificate, click View/Download Certificate
to open a window with the certificate string.
Click View/Download Key to open a window with the certificate private key.
To copy the certificate or private key to the clipboard, click on the assignment clipboard icon.
Click Download to put a copy of the certificate or private key on your server.
Keep the certificates and private keys in a secure area where you can back them up.
Managing Certificate Signing Requests
The Certificate Signing Requests widget allows users to configure a message the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
Adding a CSR
If you plan to create an ACME certificate, before adding a CSR, make sure the certificate authority provider account (i.e., Cloudflare, DigitalOcean, etc.) is correctly configured with all domains entered in this CSR.
When adding an ACME certificate for a CSR, it is created based on the settings in the selected CSR.
When adding an ACME certificate for a CSR, it is created based on the settings in the selected CSR.
For example, if using a Cloudflare DNS authenticator, in the Cloudflare account, register the domain(s) entered in the Subject Alternative Name field on the Certificate Subject screen in the Add CSR wizard.
If the CSR and provider accounts are not properly configured, a dialog with an error indicating the configuration problem opens.
You can only edit the name of the CSR after clicking Save.
If you make a mistake or want to change any setting, delete the CSR and create a new one with the desired or correct settings.
To add a CSR:
Enter a name and select the CSR type.
The Add CSR wizard allows creating a certificate signing request (CSR) or importing a certificate for a CSR.
Users can select a predefined certificate extension from the Profiles dropdown list.
Select or enter the certificate options for the CSR. TrueNAS shows default settings in each field.
Key Type shows the option matching the selection made in Profiles in step 1.
Accept the default values or choose the number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.
Click Next.
Enter the Certificate Subject settings. When entering values, enter short values for the geographic information, where possible.
For example, enter TN instead of Tennessee for the State. Enter all required values (indicated by the asterisk).
If specifying a value in Common Name, it can be the full domain assigned to the TrueNAS system or just the example.net portion of the domain name.
Include this in the Subject Alternative Name field.
You can enter any other system fully-qualified hostname (FQDN) and domains for multi-domain support.
When specifying an IP address in Subject Alternative Name do not enter the IP address of the system.
This results in an error if you try to create an ACME certificate for the CSR.
(Optional) Enter any extra constraints if needed for your scenario. The Extra Constraints step contains certificate extension options.
Basic Constraints limits the path length for a certificate chain.
Authority Key Identifier identifies the public key corresponding to the private key used to sign a certificate.
Key Usage defines the purpose of the public key contained in a certificate.
Extended Key Usage further refines key usage extensions.
Review the certificate options.
Click Back until reaching the screen with the setting option you want to change, make the change, and then click Next to advance to the Confirm Options step.
Click Save to add the CSR.
Importing a CSR
When importing a certificate into TrueNAS for the CSR, enter a name, and then select Import Certificate Signing Request in Type. Click Next.
Enter or copy/paste the certificate string into Signing Request, then enter or copy/paste the private key into Private Key.
Enter the password for the private key in Password and Confirm Password. Click Next, review the information, and then click Save.
Creating an ACME Certificate
TrueNAS provides a way to add a certificate for an ACNE DNS authenticator added to the system.
After adding the DNS authenticator, create a CSR for it.
Click on the more_vert for the CSR on the Certificate Signing Requests widget, then click on Create ACME Certificate to open the Create ACME Certificate screen.
You must configure a DNS authenticator to create an ACME certificate!
The ACME certificate is created based on the settings in the selected CSR.
You must have the domains added to the account providing the DNS authenticator.
For example, if using Cloudflare to create the DNS authenticator, the Cloudflare account must have the domain(s) entered in the Subject Alternative Name field in the Add CSR wizard on the Certificate Subject screen.
If not properly configured, a dialog with an error indicating the configuration problem opens.
Enter a name in Identifier. The underscore (_) and dash (-) are allowed characters in the name.
Select Terms of Service.
Enter a number that specifies the time (in days) before the certificate expires in Renew Certificate Days.
Select the URI of the ACME server directory from the ACME Server Directory URI dropdown list.
The Domains area shows domains for each entry made in the Subject Alternative Name field on the Certificate Subject screen of the Add CSR wizard.
Select the option from the dropdown list for each domain shown. This sets the authenticator to validate the domain.
Click Save.
The new ACME certificate shows on the Certificates and the Certificate Signing Requests widgets.
Adding ACME DNS Authenticators
Automatic Certificate Management Environment (ACME) DNS authenticators allow users to automate certificate issuing and renewal.
The user must verify ownership of the domain before TrueNAS allows certificate automation.
ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.
The system requires an ACME DNS Authenticator and CSR to configure ACME certificate automation to proceed.
Adding a DNS Authenticator
Before you begin this procedure, log in to your DNS authenticator provider service to obtain an API global key or an API token, whichever your service provider requires.
When configuring an ACME DNS authenticator in TrueNAS using Cloudflare as the provider, you need the global API key but not the API token.
This procedure uses Cloudflare as the example.
To add an authenticator:
Click Add on the ACME DNS-Authenticator widget to open the Add DNS Authenticator screen.
Select the authenticator you want to configure. Cloudflare shows by default.
Supported authenticator options are Cloudflare, DigitalOcean, Amazon Route 53, OVHcloud, and shell.
Authenticator selection changes the configuration fields.
When selecting cloudflare as the authenticator, enter the Cloudflare account email address associated API key and the DNS domain.
For Cloudflare, copy/paste the global API key from Cloudflare into the API Key field.
If using an API token, do not enter the Cloudflare account email address.
When selecting digitalocean as the authenticator, enter your DigitalOcean Token.
When selecting route53 as the authenticator, enter your Route53 Access key ID and secret access key.
When selecting OVH as the authenticator, enter your OVH application key, application secret, consumer key, and endpoint.
Click Save to add the authenticator.
The DNS authenticator shows on the ACME DNS-Authenticator widget. To make changes, click on the more_vert for the authenticator, and then on Edit.
After adding the authenticator, you can configure a certificate signing request (CSR) for this authentictor and create an ACME certificate.
For more information, see Managing Certificate Signing Requests.
Adding an Authenticator with a Shell Script
The shell authenticator option is intended for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.
If you select shell as the authenticator, you must enter the path to an authenticator script, the running user, a certificate timeout, and a domain propagation delay.
Advanced users can select this option to pass an authenticator script, such as acme.sh, to the shell and add an external DNS authenticator.
This requires an ACME authenticator script saved to the system.
Creating ACME Certificates
TrueNAS allows users to automatically generate custom domain certificates using Let’s Encrypt.
Requirements
An email address for your TrueNAS admin user.
A custom domain that uses Cloudflare, DigitalOcean, Amazon Route 53, or OVHcloud.
A DNS server that does not cache for your TrueNAS system.
Create an ACME DNS-Authenticator
Go to Credentials > Certificates and click ADD in the ACME DNS-Authenticators widget.
Enter the required fields depending on your provider, then click Save.
For Cloudflare, enter either your Cloudflare Email and API Key, or enter an API Token.
If you create an API Token, make sure to give the token the permission Zone.DNS:Edit, as it’s required by certbot.
For DigitalOcean, enter your Digitalocean Token.
For Route53, enter your Access Key ID and Secret Access Key. The associated IAM user must have permission to perform the Route53 actions ListHostedZones, ChangeResourceRecordSets, and GetChange.
For OVH, enter your OVH Application Key, OVH Application Secret, OVH Consumer Key, and OVH Endpoint.
Create a Certificate Signing Request (CSR)
Next, click ADD in the Certificate Signing Requests widget.
You can use default settings except for the Common Name and Subject Alternate Names fields.
Enter your primary domain name in the Common Name field, then enter additional domains you wish to secure in the Subject Alternate Names field.
For example, if your primary domain is domain1.com, entering www.domain1.com secures both addresses.
Create ACME Certificate
Click the icon next to the new CSR.
Fill out the ACME Certificate form. Under Domains, select the ACME DNS Authenticator you created for both domains, then click Save.
You can create testing and staging certificates for your domain.
Set the GUI SSL Certificate
Go to System > General Settings and click Settings in the GUI widget.
Select the new ACME certificate you created from the GUI SSL Certificate dropdown, then click Save.
Select the Confirm checkbox, then press Continue to restart TrueNAS and apply the changes.
Configuring KMIP
TrueNAS Enterprise
KMIP is only available for TrueNAS Enterprise licensed systems.
Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.
The Key Management Interoperability Protocol (KMIP) is an extensible client/server communication protocol for storing and maintaining keys, certificates, and secret objects.
KMIP on TrueNAS Enterprise integrates the system within an existing centralized key management infrastructure and uses a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
With KMIP, keys created on a single server are then retrieved by TrueNAS.
KMIP supports keys wrapped within keys, symmetric, and asymmetric keys.
KMIP enables clients to ask a server to encrypt or decrypt data without the client ever having direct access to a key.
You can also use KMIP to sign certificates.
Requirements
To simplify the TrueNAS connection process:
Have a KMIP server available with certificate authorities and certificates you can import into TrueNAS.
Have the KMIP server configuration open in a separate browser tab or copy the KMIP server certificate string and private key string to later paste into the TrueNAS web interface.
Connecting TrueNAS to a KMIP Server
To connect TrueNAS to a KMIP server, import a Certificate from the KMIP server, then configure the KMIP options.
How do I import these?
Log into the TrueNAS web interface and go to Credentials > Certificate.
Click Import on the Certificate widget.
Enter a memorable name for the certificate, then paste the KMIP server certificate and private key strings into the related TrueNAS fields.
Leave Passphrase empty.
Click Save.
For security reasons, we strongly recommend protecting the certificate values.
Enter the central key server host name or IP address in Server and, if not using the default port 5696, enter a number for an open connection port on the central key server in Port.
Select the certificate imported from the central key server in Certificate.
To ensure the certificate chain is correct, click on Validate Connection. Click Save.
When the certificate chain verifies, choose the encryption values, SED global password, or ZFS data pool encryption keys to move to the central key server.
Select Enabled to begin moving the passwords and keys immediately after clicking Save.
Refresh the KMIP screen to show the current KMIP Key Status.
To cancel a pending key synchronization, select Force Clear and click Save.
Containers
Virtual Machines and Containers in TrueNAS 25.10
TrueNAS 25.04 introduced support for Containers (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in TrueNAS CORE.
In TrueNAS 25.04.2 and later, virtual machines are created and appear on the Virtual Machines screen.
Legacy VMs created in 25.04.0 or 25.04.1 using the Instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the Containers screen.
Legacy VMs on the Containers screen do not autostart in 25.10 or later.
Users with existing VMs on the Containers screen should consider migrating associated zvols to the Virtual Machines screen at this time to ensure compatibility with future TrueNAS releases.
For information on migrating your zvol storage volume to a new VM created in 25.10 or later, see Migrating Containers VMs.
Containers (Linux system containers) are an experimental feature intended for community testing only.
Functionality could change significantly between releases, and containers might not upgrade reliably.
Use this feature for testing purposes only—do not rely on it for production workloads.
Long-term stability is planned for future TrueNAS Community Edition releases.
Make all configuration changes using the TrueNAS UI.
Operations using the command line are not supported and might not persist on upgrade.
For assistance or to discuss this feature with other TrueNAS users, visit our community forums. To report bugs, submit an issue on TrueNAS Jira.
Containers allow users to configure linux containers in TrueNAS.
Linux containers, powered by LXC, offer a lightweight, isolated environment that shares the host system kernel while maintaining its own file system, processes, and network settings.
Containers start quickly, use fewer system resources than virtual machines (VMs), and scale efficiently, making them ideal for deploying and managing scalable applications with minimal overhead.
What system resources do containers require?
Containers are lightweight and share the host kernel, requiring fewer resources than virtual machines.
However, proper resource allocation ensures optimal performance and system stability.
You can leave CPU and memory settings blank to allow containers access to all available host resources, or configure specific limits based on your needs.
Key considerations for container deployment:
Storage Pool: Containers require a storage pool for volume creation and image storage.
SSD drives provide optimal performance.
CPU: No virtualization extensions required.
Multiple containers run efficiently on fewer resources than equivalent VMs.
Memory: More efficient than VMs with no guest OS overhead.
Memory allocated to containers reduces available memory for TrueNAS ZFS caching.
Setting Up the Containers Service
You must choose a pool before you can deploy a container.
The Containers screen header displays a Pool is not selected status before a pool for containers is selected.
See Choosing the Containers Pool below for more information about pool selection.
Click Global Settings on the Configuration menu to open the Global Settings screen, showing global options that apply to all containers.
Use these options to configure the storage pool for containers and network settings.
You must set a pool before you can add any containers.
Select Enabled to enable container storage.
Use the Pool dropdown to select one or more pools and click Save.
We recommend users keep the container use case in mind when choosing a containers pool.
Select a pool with enough storage space for all the containers you intend to host.
For stability and performance, we recommend using SSD/NVMe storage for the containers pool due to their faster speed and resilience for repeated read/writes.
Select additional pools to allow containers to access shared resources.
To select a different pool for containers to use, use the Pool dropdown to select a different pool.
Deselect Enabled to deactivate the pool and disable the containers service.
Configuring the Default Network
Use the Default Network settings on the Global Settings screen to define how containers connect to the network.
These settings apply to all new containers, unless configured otherwise.
Select Automatic from the Bridge dropdown list to use the default network bridge for communication between containers and the TrueNAS host.
To specify an existing bridge, select one from the dropdown list.
See Accessing NAS from VMs and Containers for details. When Bridge is set to Automatic, the IPv4 Network and IPv6 Network settings display.
Enter an IPv4 address and subnet (e.g., 192.168.1.0/24) in IPv4 Network to assign a specific network for containers.
Leave this field empty to allow TrueNAS to assign the default address.
Enter an IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) in IPv6 Network or leave this field empty to allow TrueNAS to assign the default address.
Adjust these settings as needed to match your network environment and ensure proper connectivity for containers.
Managing Volumes
Click Manage Volumes on the Configuration menu to open the Volumes screen, which lists all the volumes currently configured for the containers service.
Click Create Volume to open the Create New Volume dialog to configure a new volume.
Click Import Zvols to open the Import Zvol dialog to import an existing Zvol as a volume.
Click Import Zvols on the Volumes screen to open the Import Zvol dialog.
Importing a zvol as a volume allows its lifecycle to be managed, including backups, restores, and snapshots.
This allows portability between systems using standard tools.
Enter the path or browse to select an existing Zvol in Select Zvols.
Select Clone to clone and promote a temporary snapshot of the zvol into a custom storage volume.
This option retains the original zvol while creating an identical copy as a container volume.
Select Move to relocate the existing zvol to the ix-virt dataset as a volume.
Deleting Volumes
Click Configuration > Manage Volumes to access the Volumes screen.
Click delete on a volume row to delete that volume.
The Delete volume dialog displays.
Select Confirm and then click Continue to delete the volume.
TrueNAS disables the delete icon for active images to prevent accidental deletion.
Managing Container Permissions
Containers run as isolated environments from the host system. To give container processes access to host files and datasets, you must map user and group IDs (UIDs and GIDs) between the host and the container.
Click Map User/Group IDs from the Configuration dropdown to open the Map User and Group IDs screen. This screen allows you to configure how user and group IDs (UIDs and GIDs) appear inside containers.
By default, user and group accounts within a container are assigned UIDs and GIDs from a private range starting at 2147000001. This mapping ensures security isolation for containers.
You can override these mappings to meet specific access requirements.
Select Users or Groups to view mappings for individual user or group accounts.
Existing mappings appear in a table that lists the user or group name, host ID, and container ID. Click delete Delete on a row to remove a mapping.
To add a new mapping:
Type an account name to search or select it from the dropdown.
Enable Map to the same UID/GID in the container to use the same ID from the host in containers. This makes the selected user or group ID appear the same inside and outside the container.
Disable Map to the same UID/GID in the container to assign a different container ID. Enter the container UID or GID you want to use—for example, 1000.
Only local users and groups are supported for ID mapping in containers. Domain accounts from Active Directory or other directory services are not supported.
Click Set to create the mapping. Changes apply immediately, though restarting the container can be required for them to take effect.
Mapped IDs control access to mounted host datasets. For example, if you map a host user with UID 3000 to UID 1000 inside the container:
Assign permissions on the host dataset to UID 3000.
Inside the container, perform actions as UID 1000.
This setup grants user 1000 in the container the same access to the dataset as user 3000 has on the host. Assigning dataset permissions to a host user is not enough to grant container permissions to all users—you must also map that user and ensure the correct user and UID is used inside the container.
Incorrect or missing mappings can cause permission errors when containers access host paths.
Granting Root Access to Host Paths
To safely allow container root processes to access host datasets, TrueNAS provides a built-in unprivileged root user for containers truenas_container_unpriv_root.
This user has UID 2147000001 and is used automatically to represent the container root on the host.
No manual ID mapping is required.
To grant container root access to host data:
Assign permissions on the host dataset to the truenas_container_unpriv_root user.
Access the dataset from inside the container as root.
When the container root accesses the path, it uses the host permissions of truenas_container_unpriv_root.
This approach provides secure, controlled access for container root processes without exposing host root privileges.
Creating Containers
Click Create New Container to open the Create Container configuration wizard.
Enter values for CPU Configuration and Memory Size or leave blank to allow the container access to all host CPU and memory resources.
To configure resource allocation:
a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.
Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores.
For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node.
For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.
b. Allocate RAM in Memory Size.
This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB).
If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
(Optional) Configure environment variables to run on boot or execute.
a. Click Add in the Disks section to display a set of fields to mount a disk.
b. To create a new dataset, enter a path or browse to select a parent dataset from the dropdown list of datasets on the system.
Then click Create Dataset, enter a name for the new dataset in the Create Dataset window, and click Create.
To use an existing volume, enter a path or browse to select an existing dataset from the Source dropdown list.
c. Enter the file system Destination path to mount the disk in the container, for example /media or /var/lib/data.
d. Click Add again to mount additional storage volumes.
(Optional) Configure proxy settings to forward network connections between the host and the container.
This routes traffic from a specific address on the host to an address inside the container, or vice versa, allowing the container to connect externally through the host.
a. Click Add in the Proxies section to display a set of proxy configuration settings.
b. Select the protocol option from the Host Protocol dropdown list to set the connection protocol for the TrueNAS host as TCP or UDP.
c. Enter a port in Host Port to define the TrueNAS port to map to the container port on the container, for example 3600.
d. Select the connection protocol for the container in Instance Protocol.
Options are TCP or UDP.
e. Enter the port number within the container in Instance Port, for example 80, to map to the host port.
Configure the Network section settings to define how the container connects to the host and external networks.
Options include the default network bridge, an existing bridge interface, or a MACVLAN.
Use default network settings: Enable to connect the instance to the host using the automatic bridge defined in Global Settings. Disable to show the Bridged NICs (if available) and Macvlan NICs settings.
To configure non-default network settings, select one or more interface options:
Bridged NICs: Use to connect an existing bridge interface to the instance.
Macvlan NICs: Use to create a virtual network interface based on an existing interface.
A MACVLAN assigns a unique MAC address to the virtual interface so the instance appears as a separate device on the network.
A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host.
MACVLAN sends traffic directly to the external network without passing through the host network stack.
The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.
(Optional) Configure USB devices to attach available devices to the container by selecting one or more in USB Devices.
This allows the device to function as if physically connected.
(Optional) Configure GPU devices in the GPU Devices section to attach available GPU devices, enabling the container to utilize hardware acceleration for graphics or computation tasks.
TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPUs from NVIDIA, Intel, and AMD.
As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see Installing NVIDIA Drivers.
Click Create to deploy the container.
Managing Containers
Created containers appear in a table on the Containers screen.
The table lists each configured container, displaying its name, type, current status, and options to restart or stop it.
Stopped containers show the option to start the container.
Select the checkbox to the left of Name (select all) or select one or more container rows to access the Bulk Actions dropdown.
Enter the name of a container in the Search field above the Containers table to locate a configured container.
Click restart_alt to restart or stop_circle to stop a running container.
Choosing to stop a container shows a choice to stop immediately or after a small delay.
Click play_circle to start a stopped container.
Select a container row in the table to populate the Details for Container widgets with information and management options for the selected container.
Using Bulk Actions
Apply actions to one or more selected containers on your system using Bulk Actions.
Click Edit to open the Edit Container: Container screen.
The Edit Container: Container screen settings are a subset of those found on the Create Container screen.
It includes the general Container Configuration and CPU and Memory settings for containers.
Additionally, containers include Environment settings.
a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.
Set to an integer to expose that number of full vCPU cores to the instance.
Set to a range or comma-separated list to pin vCPUs to specific physical cores.
For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node.
For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.
b. Allocate RAM in Memory Size.
This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB).
If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.
Editing Environment Settings
These settings configure optional environment variables for the container.
Click Add to open a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices to attach.
Select a device to attach to a container.
To attach a PCI passthrough device, click Add Device under PCI Passthrough on the device list to open the Add PCI Passthrough Device.
PCI passthrough assigns a physical PCI device, such as a network card or controller, directly to a VM, allowing it to function as if physically attached.
The Add PCI Passthrough Device screen lists the available physical PCI devices that can be attached to a container.
Use Search Devices or the Type dropdown to filter available devices.
The selected PCI device(s) must not be in use by the host or share an IOMMU group with any device the host requires.
Click Select to attach the selected device.
Managing Disks
Use the Disks widget to view the storage devices attached to the container, along with their associated paths.
Click Add to open the Add Disk screen for adding new disks to the container.
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select to either Edit or Delete the disk mount.
For VMs, use the Disks widget to manage the root disk size and I/O Bus.
The root disk stores the OS and serves as the boot disk for the VM.
Click Change to open the Change Root Disk Setup dialog.
Adding or Editing Disks
Click Add to open the Add Disk screen for adding new disks to the container.
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select Edit to edit the disk mount.
Enter or browse to select the host Source path for the disk.
For a new dataset, enter or browse to select the parent path.
Enter the Destination path to mount the disk in the container.
Click Save to apply changes.
Deleting Disk Mounts
Click the more_vert icon to the right of an existing disk to open the actions menu.
Select Delete to delete the disk mount.
The Delete Item dialog asks for confirmation to delete the selected disk mount.
Click Confirm to activate the Continue button.
Click Continue to start the delete operation.
Managing Proxies
Use the Proxies widget to view the network proxy settings configured for the container.
It allows you to manage these settings, including adding, editing, or removing proxies.
Proxies allow you to forward network connections between the host and the container.
Click Confirm to activate the Continue button.
Click Continue to start the delete operation.
Accessing Containers
After selecting the container row in the table to populate the Details for Container widgets, locate the Tools widget.
You can open a shell session directly from this widget.
Click Shell to open a Container Shell session for command-line interaction with the container.
Virtual Machines
TrueNAS has built-in virtualization capabilities that allow running multiple operating systems on a single system, maximizing hardware utilization, and consolidating workloads.
A virtual machine (VM) is a software-based computer that runs inside your TrueNAS system, and appears as a separate physical machine to the operating system installed within it.
VMs use virtualized hardware components, including, network interfaces, storage volumes, graphics adapters, and other devices, providing complete isolation between different operating systems and applications.
VMs offer stronger isolation than containers but require more system resources, making them ideal for running full operating systems, legacy applications, or services that need dedicated environments.
What system resources do VMs require?
TrueNAS assigns a portion of system RAM and a new zvol to each VM.
While a VM is running, these resources are not available to the host computer or other VMs.
Virtualization requires:
x86 machine running a recent Linux kernel
Intel processor with VT (Virtualization Technology) extensions, OR
AMD processor with SVM extensions (AMD-V)
Users cannot create VMs unless the host system supports these features.
Users with multiple GPUs who wish to pass a GPU to a VM must first isolate a GPU for VM use.
One GPU is always required by TrueNAS.
Creating a Virtual Machine
Before creating a VM:
Obtain an installer .iso or image file for the OS you intend to install
Create a zvol on a storage pool that is available for both the virtual disk and the OS install file.
If the VM needs to access local NAS storage, you must create a network bridge to allow communication.
See Accessing TrueNAS Storage from a VM below for more information.
Using the Create Virtual Machine Wizard
To create a new VM, go to Virtual Machines and click Add to open the Create Virtual Machine wizard.
If you have not yet added a virtual machine to your system, clicking Add Virtual Machines opens the same wizard.
Configure the Operating System settings.
a. Select the operating system for the VM from the Guest Operating System dropdown list.
Compare the recommended specifications for the guest operating system with your available host system resources when allocating virtual CPUs, cores, threads, and memory size.
b. Enter a name for the VM.
c. (Optional) Enter a description for the VM. This can be any short text string describing how the VM is used or which operating system is configured.
d. (Optional) Change the default settings in System Clock and Boot Method to suit your use case.
Select UTC as the VM system time from the System Clock dropdown if you do not want to use the default Local setting.
Select UEFI from the Boot Method dropdown, unless using an older OS that requires Legacy BIOS.
e. (Optional) Select Enable Secure Boot to enable cryptographic verification of boot loaders, operating system kernels, and drivers during VM startup.
This security feature prevents unauthorized or malicious code from running during the boot process by checking digital signatures against trusted certificates.
Secure Boot is required for Windows 11 and some Linux distributions, and can be optional or unsupported for older operating systems.
Secure boot is only available from the VM creation wizard.
f. (Optional) Select Enable Trusted Platform Module (TPM) to provide a virtual TPM 2.0 device for the VM.
TPM provides hardware-based security functions, including secure key storage, cryptographic operations, and platform attestation.
This is required for Windows 11 and enhances security for other operating systems that support TPM.
g. (Optional) Select Start on Boot to start the VM after the system is restarted or boots up.
h. (Optional) Select Enable Display (VNC) to enable a Virtual Network Computing (VNC) remote connection for the VM.
Enable Display (VNC) shows the Bind and Password fields.
i. Select the IP address or option to use in Bind. Shows if you select Enable Display.
The Bind and Password fields display. If it is selected, to change the default IP address to use a specific address as the display network interface; otherwise, leave it set to 0.0.0.0.
The Bind list populates with any existing logical interfaces, such as static routes, configured on the system.
You cannot edit the Bind setting after saving the VM settings.
j. Enter a password to secure access to the virtual display in Password. The Password field shows if you select Enable Display.
The login screen for the display shows a credential entry field for this password.
When the Guest Operating System is set to Windows, Virtual CPUs shows the default value of 2.
The VM operating system might have operational or licensing restrictions on the number of CPUs.
Do not allocate too much memory to a VM. Activating a VM with all available memory allocated to it can slow the host system or prevent other VMs from starting.
Leave CPU Mode set to Custom if you want to select a CPU model.
Use Memory Size and Minimum Memory Size to specify how much RAM to dedicate to this VM.
To dedicate a fixed amount of RAM, enter a value (minimum 256 MiB) in the Memory Size field and leave Minimum Memory Size empty.
To allow for memory usage flexibility (sometimes called ballooning), define a specific value in the Minimum Memory Size field and a larger value in Memory Size.
The VM uses the Minimum Memory Size for normal operations but can dynamically allocate up to the defined Memory Size value in situations where the VM requires additional memory.
Reviewing available memory from within the VM typically shows the Minimum Memory Size.
When you select Import Image, browse to and select the source disk image file in Image Source.
The system automatically detects the image format (QCOW2, QED, RAW, VDI, VHDX, or VMDK).
Select the destination dataset in Zvol Location where the system creates the converted zvol.
Select either AHCI or VirtIO from the Select Disk Type dropdown list. We recommend using AHCI for Windows VMs.
When creating a new disk image, select the location for the new zvol from the Zvol Location dropdown list and enter a value in Size (Examples: 500KiB, 500M, and 2TB) to indicate the amount of space to allocate for the new zvol.
Select the network interface type from the Adapter Type dropdown list. Select Intel e82585 (e1000) as it offers a higher level of compatibility with most operating systems.
Select VirtIO if the guest operating system supports para-virtualized network drivers.
The VirtIO network interface requires a guest OS that supports VirtIO para-virtualized network drivers.
Select the network interface card to use from the Attach NIC dropdown list.
If the VM needs to access local NAS storage, attach a network bridge interface.
Click Next.
Configure Installation Media settings to upload the operating system you selected in step 1.
You can create the VM without an OS installed, then edit the VM to add it later.
To add the installation media, type the path or browse to select the location of the image file, and then select it.
To upload an iso, click Upload New Image File. Enter the path or browse to select the location of the file.
TrueNAS does not have a list of approved GPUs at this time, but TrueNAS does support various NVIDIA, Intel, and AMD GPUs.
Confirm your VM settings, then click Save.
Adding and Removing Devices
Using the Create Virtual Machine wizard configures at least one disk and NIC, and optionally a CD-ROM and display as part of the process, but you can add more devices to suit your use case.
Go to Virtual Machines, then click anywhere on a VM entry to expand it and show the options for the VM.
An active VM displays options for settings_ethernetDisplay and keyboard_arrow_rightSerial Shell connections.
When a display device is configured, remote clients can connect to VM display sessions.
If the display connection screen appears distorted, try adjusting the display device resolution.
Use the Running toggle or click stopStop to follow a standard procedure to do a clean shutdown of the running VM.
Click power_settings_newPower Off to halt and deactivate the VM, which is similar to unplugging a computer.
If the VM does not have a guest OS installed, the VM Running toggle and stopStop button might not function as expected.
The Running toggle and stopStop buttons send an ACPI power down command to the VM operating system, but since an OS is not installed, these commands time out.
Use the Power Off button instead.
Deleting a Virtual Machine
To delete a VM, first stop it if it is running, then click deleteDelete on the expanded VM details screen.
The Delete Virtual Machine dialog opens with options to control what data is removed.
Delete Virtual Machine Data removes the zvols and data associated with the VM. When selected, the dialog displays a list of disk and raw file devices to delete.
Deleting a VM with Delete Virtual Machine Data selected results in permanent data loss if the data is not backed up.
Do not select this option if you want to keep the VM zvols intact for use with another VM or for data recovery.
Force Delete ignores the VM status during the delete operation. Only select this if the VM is in an undefined state and cannot be stopped normally.
Enter the VM name in the confirmation field to enable the Delete button, then click Delete to remove the VM.
Installing an OS
After configuring the VM in TrueNAS and an OS .iso file is attached, start the VM and begin installing the operating system.
Some operating systems can require specific settings to function properly in a virtual machine.
For example, plain Debian can require advanced partitioning when installing the OS.
Refer to the documentation for your chosen operating system for tips and configuration instructions.
Installing Debian OS Example
Upload the Debian .iso to the TrueNAS system and attach it to the VM as a CD-ROM device.
This example uses Debian 12 and basic configuration recommendations.
Modify settings as needed to suit your use case.
Click Virtual Machines, then ADD to use the VM wizard.
Configure settings as needed.
Select the physical interface to associate with the VM.
Installation Media
The installation ISO is uploaded to local storage.
If the ISO is not uploaded, select Upload an installer image file.
Select a dataset to store the ISO, click Choose file, then click Upload. Wait for the upload to
complete.
GPU
Leave the default values.
Confirm Options
Verify the information is correct and then click Save.
After creating the VM, start it. 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.
Log in to another client on the network and ping the IP address of your new VM.
Confirm the ping is successful.
Accessing TrueNAS Storage From a VM
By default, VMs are unable to communicate directly with the host NAS.
If you want to access your TrueNAS SCALE directories from a VM, for example, to connect to a TrueNAS data share, you have multiple options.
If your system has more than one physical interface, you can assign your VMs to a NIC other than the primary one your TrueNAS server uses.
This method makes communication more flexible but does not offer the potential speed of a bridge.
If your system has only one physical interface, create a bridge interface for the VM to use.
Stop all existing apps, VMs, and services using the current interface, edit the interface and VMs, create the bridge, and add the bridge to the VM device.
See Accessing NAS from VM for more information.
Migrating Containers VMs
The storage volumes (zvols) for virtual machines created using the Instances screen in TrueNAS 25.04.0 or 25.04.1 (renamed the Containers screen in 25.04.2 and later) can migrate to new VMs created using the Virtual Machines screen in 25.04.2 and later.
The process involves:
Identifying the hidden storage volumes (zvols) associated with the Instance VMs.
Determining which zvol contains the actual VM data by checking the volume size.
Renaming (and moving) the zvols to a new dataset where they can be seen and used by a new VM.
(Highly Recommended) Configuring zvol properties to match those of natively-created VM zvols.
Creating a new VM and selecting the migrated zvol as the storage volume.
Before You Begin
Before beginning the process:
Identify the zvol names associated with the Instance (Container) VM.
Take a recursive snapshot or back up the pool configured for Instance VMs.
Using ZFS commands to rename and move an existing zvol can damage data stored in the volume.
Having a backup is a critical step to restoring data if something goes wrong in the process.
Verify the VM is operational and the network is functioning as expected. One way to do this is to verify it has Internet access.
Then stop the VM before you upgrade to the next release.
Identify the dataset where you want to move the volume.
We do not recommend renaming or moving the volume more than once, as it increases the risk of possible data corruption or loss.
You do not need to log in as the root user if the logged-in admin user has permission to use sudo commands.
If not, go to Credentials > Users, edit the user to allow sudo commands, or verify the root user has an active password to switch to this user when entering commands in the Shell screen.
Migrating a Zvol for an Instance VM
This procedure applies to the zvol for an Instance or Container VM that has data you want to preserve and access from a new VM using the Virtual Machines screens in later releases.
Go to Instances (or Containers), click on Configuration, and then Manage Volumes to open the Volumes window.
The Volumes window lists all Instances VMs and associated storage volumes (zvols).
Record the volume name or take a screenshot of the information to refer to later when entering commands in the Shell screen. Zvol names are similar to the VM name but not identical.
Optionally, you can highlight all the listed information and copy/paste it into a text file, but this is not necessary.
While on the Instances screen, verify the VM is operational and the network is operating as expected.
One way to verify external network access is to check Internet access. Stop the VM before upgrading.
Repeat for each zvol that you plan to migrate into a new VM in later releases.
Go to Datasets, locate the pool associated with Instances (Containers), and take a recursive snapshot to back up all Instances VM zvols.
These zvols are in the hidden .ix-virt directory created in the pool Instances uses, selected when you configure the feature.
To verify the pool, you can go to Containers > Configure > Global Settings and look at the Pool setting.
Go to System > Update, and update to the next publicly available maintenance or major version release.
Follow the release migration paths outlined in the version release notes or the Software Releases article.
After updating to a 25.04.x release or later, VMs created using Instances screens show on the Containers screen, and are stopped.
Some VMs experience various issues like network connectivity, or are stopped and do not start.
Refer to the troubleshooting tips below for more information. 25.10 releases correct some issues encountered in 25.04.2.4 VMs that are migrated.
After upgrading to a release that shows the Virtual Machines screen and the Containers option:
Go to Containers to see which VMs are listed, then click Configuration, and then Manage Volumes to open the Volumes window.
Take a screenshot of the volumes listed, or copy/paste the volumes and VM information into a text file to use later in this procedure.
Zvol names are similar to the VM but not identical. Volume names are used in step 6 below.
Go to System > Shell. Exit to the Linux prompt for the system.
Note: This is where the logged-in admin user needs sudo permissions, or where the root user must have a password configured to enter the following commands to find, rename/move, and verify each Instance zvol is properly configured.
Experienced users can switch to the root user if the root user has a password assigned and enabled.
Enter the following commands at the Linux system prompt:
Storage conventions differ based on VM history:
Migrated VMs (from pre-Incus TrueNAS) use custom/default_* zvols for actual VM data
VMs created in 25.04.0 or 25.04.1 use .block zvols for actual VM data
Small .block files (56K) are stubs and should not be migrated
a. Locate the hidden zvols for the Instance VMs, by entering:
sudo zfs list -t volume -r -d 10 poolname
Where:
-d 10 shows datasets up to 10 levels deep
poolname is the name of the pool associated with the Instance VMs.
If you have multiple pools associated with the Instance VMs, repeat this command with the name of that pool to show hidden zvols in that pool.
The .ix-virt directory contains the zvols used in Instance VMs. Check the USED or REFER columns to identify the actual VM storage:
For migrated VMs: Use the custom/default_* zvol (typically several GB or more)
For VMs created in 25.04.0 or 25.04.1: Use the .block zvol that shows significant storage usage (not 56K stubs)
Ignore: Stub .block files showing only 56K, and zvols not in the .ix-virt directory
The output includes other zvols in the pool if your system has non-instance VMs configured in the pool name entered in the command.
Example Command Output
Example showing migrated VMs (custom/ zvols with actual data):
re-minir-102% sudo zfs list -t volume -r tank
NAME USED AVAIL REFER MOUNTPOINT
tank/.ix-virt/custom/default_vm2410linux-8cppg 40.6G 1.66T 40.6G - ← Migrate this (actual data)
tank/.ix-virt/custom/default_vm2410win-mvqznj 40.2G 1.66T 40.2G - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/vm2410linux.block 56K 1.66T 56K - ← Stub (ignore)
tank/.ix-virt/virtual-machines/vm2410win.block 56K 1.66T 56K - ← Stub (ignore)
tank/vms/previously-migrated 35.1G 1.70T 35.1G -
Example showing VMs created in 25.04.0/25.04.1 (.block zvols with actual data):
qe-realmini% sudo zfs list -t volume -r tank
NAME USED AVAIL REFER MOUNTPOINT
tank/.ix-virt/virtual-machines/TrueNAS.block 6.98G 2.55T 6.98G - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/fdsa.block 25.9M 2.55T 248M - ← Migrate this (actual data)
tank/.ix-virt/virtual-machines/debian.block 56K 2.55T 56K - ← Stub (ignore)
tank/.ix-virt/virtual-machines/mint.block 56K 2.55T 56K - ← Stub (ignore)
In the examples above:
Zvols with custom/default_* in the path showing significant storage (40+GB) are migrated VMs to migrate
Zvols with .block extension showing significant storage (6.98G, 25.9M) are native Incus VMs to migrate
Small .block files at 56K are stubs and should be ignored
After successfully migrating and confirming functionality of all VMs, the remaining stub .block files (56K) in .ix-virt/virtual-machines/ can optionally be deleted to clean up the hidden dataset.
b. Rename (and move) each volume in the .ix-virt directory to a new location where you can select it when configuring a new VM.
Repeat for each volume you want to migrate to a new VM. Do not rename or move stub .block files (56K).
default_debian1-urec9f or TrueNAS.block is the name of a hidden zvol in the examples, and the name given to the migrated zvol.
We do not recommend renaming the migrated zvol to minimize potential issues with the migration process.
For .block zvols, you can keep or remove the .block extension in the target name.
vms is the dataset in the examples as the location to store the migrated zvols for VMs. Change this to the location on your system.
This renames and moves it to the specified location, and returns to the system Linux prompt.
To verify the zvol moved, enter the sudo zfs list -t volume -r tank command again. The output should show the zvol in the new location.
c. (Highly Recommended) Set zvol properties to match those of natively-created VM zvols.
Enter the following command for each zvol you migrated:
For migrated VMs (custom/ zvols):
sudo zfs set volmode=default primarycache=all secondarycache=all tank/vms/default_debian1-urec9f
For VMs created in 25.04.0 or 25.04.1 (.block zvols):
sudo zfs set volmode=default primarycache=all secondarycache=all tank/vms/TrueNAS.block
Where:
tank is the pool name.
vms is the dataset where the zvol is stored.
default_debian1-urec9f or TrueNAS.block is the name of the zvol
This command sets the volume properties to match those used by zvols created through the Virtual Machines screen, ensuring optimal performance and behavior.
Containers VMs used different property settings that are not optimal for virtual machine workloads.
After completing the commands listed above for each zvol you want to migrate, go to Datasets and verify all volumes you migrated show on the screen.
Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated.
Go to Virtual Machines, click on Add to open the Create Virtual Machine wizard.
For more information or details on using the Create Virtual Machine wizard, see Creating a Virtual Machine.
a. Complete the first screen by entering a name for the new VM, select the operating system used by the Instances VM, enter a brief description, and then if using the Bind setting, enter a password. Click Next.
b. Configure the CPU and Memory settings, and then click Next.
c. On the Disks wizard screen, select Use existing disk image, click in Select Existing Zvol and select the volume moved from the Instances VM.
If you move multiple zvols, refer to the screenshot or text file with the VM/zvol list to select the correct zvol for this new VM.
d. Click Next until you get to the confirmation screen, then click Create to add the VM.
After adding the new VM, click on the row to expand it, and click Devices.
Click Edit for the Disk device, and enter 1000 in the Device Order field.
Setting the disk to 1000 makes the disk device the first in the boot order for the VM.
Setting the disk to first in boot order over a CD-ROM device with an OS on it, if added when creating the VM, prevents the volume from being overwritten by booting from that CD-ROM device.
Click Save.
Return to the Virtual Machines screen, expand the VM, then click Start to verify it opens as expected and has network access.
Using the Create Virtual Machine wizard configures at least one disk and NIC, and optionally a CD-ROM and display as part of the process, but you can add more devices to suit your use case.
Go to Virtual Machines, then click anywhere on a VM entry to expand it and show the options for the VM.
A virtual machine attempts to boot from devices according to the Device Order, starting with 1000, then ascending.
A CD-ROM device allows booting a VM from a CD-ROM image like an installation CD.
The CD image must be available in the system storage.
A Display device provides remote clients with a way to connect to VM display sessions.
Before You Begin
Before adding, editing, or deleting a VM device, stop the VM if it is running.
Click the Running toggle to stop a VM, or click on the VM row and use the Stop button.
Clicking the Running toggle for a stopped VM restarts it, or you can click on the VM row to expand it, and then click on the Restart button.
To access the devices for a VM, click on the VM row on the Virtual Machines screen to expand the VM, then click on Devices to open the Devices screen showing the devices for the selected VM.
Click Add to create a new device>
To edit an existing device, click on the more_vert at the right of each device row, click Edit to open the Edit Device screen.
Click Delete to open a delete confirmation dialog.
Editing a Device
After selecting the VM row on the Virtual Machines list and clicking on Devices to open the Devices screen, the devices configured for that selected VM show.
Devices added when you create the VM show by default. You can add additional or edit existing devices.
Click on the more_vert at the right of the device row.
Options for each device show. A disk device shows four options: Edit, Delete, Details, and Export to Image.
Other device types do not include the export option.
Click Edit* to open the Edit Device screen.
The screen settings change based on the device type selected.
For example, when editing a disk (example provided below), you can change the type of virtual hard disk, the storage volume to use, or change the boot order for the device.
Stop the VM on the Virtual Machines screen, click on Devices to open the Devices screen for that VM, and then click Edit.
The procedure below describes editing a disk device.
Steps below are optional. Change them based on your use case.
(Optional) Select the zvol created when setting up the VM on the Zvol dropdown list. The field populates with the path to the selected zvol.
(Optional) Select the type of hard disk emulation from the Mode dropdown list. The options are AHCI and VirtIO.
Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM has support for VirtIO disk devices.
(Optional) Specify the disk sector size in bytes in Disk Sector Size.
Leave set to Default if you want to leave the sector size unset and use the ZFS volume value.
Select either 512 or 4096 byte values from the dropdown list to specify a logical and physical sector size.
(Optional) Enter a number that reflects the boot order or priority level in Device Order.
Setting this value to 1000 puts the disk device in the boot order first position.
When first installing or changing an OS added to the CD-ROM device, the CD-ROM is assigned 1000 to boot up from and install an OS.
After installing the OS, change the boot order for the CD-ROM to a lower boot order so you do not keep booting into an installer and to run the OS in the VM.
The lower the number, the higher the priority in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen to return to the Virtual Machines screen. Click on the VM to expand it and restart it.
To edit display type or bind address after creating a VM
Go to Virtual Machines, locate the VM you want to modify, and click on it to expand it.
Click device_hubDevices to open the Devices screen associated with the VM.
Click the more_vert icon at the right of the display device and click on Edit to open the Edit Device screen for that display device.
Select the IP address or other option on the Bind dropdown.
You can assign a port number to your display device or use the default port number associated with the device.
You can add a second display device to have a VNC and SPICE display associated with the VM, but only one display device can be active at one time.
Adding a second display device assigns a different default port number to the second display device.
Deleting a Device
Deleting a device removes it from the list of available devices for the selected VM.
To delete a device:
Stop the VM if it is running, then click Devices to open the Devices screen showing the devices for the selected VM.
Click on the more_vert icon to the right of the device and then Delete to open the delete confirmation dialog for that display device.
The dialog shows the name or identifier for the selected device. The example below shows undefined 8 as the name.
Select Force Delete to force the system to delete the device (for example, device is a CD-ROM).
When deleting a disk, it forces the system to delete the zvol even if other devices or services are using it or are affiliated with the zvol device.
Click Delete Device.
Changing the Device Order
Changing the device order moves the device up or down in the boot order when the VM or system is restarted.
A VM attempts to boot from devices according to the Device Order, starting with 1000, then ascending.
After stopping the VM and clicking Devices to open the Devices screen:
Click on the more_vert at the right of the device row, then click on Edit to open the Edit Device screen.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence. 1000 is the first position in the boot order.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a CD-ROM Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select CD-ROM on the Device Type dropdown list.
Enter or browse to select the mount path to the CD-ROM device.
Click on the to the left of /mnt to expand or collapse the directory tree.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a NIC Device Type
After stopping the VM and clicking Devices to open the Devices screen:
Click Add to open the Add Device screen.
Select NIC on the Device Type dropdown list to show the network interface card settings.
Select the adapter type from the Adapter Type dropdown list.
Choose Intel e82585 (e1000) for maximum compatibility with most operating systems.
If the guest OS supports VirtIO paravirtualized network drivers, choose VirtIO for better performance.
Click Generate to have TrueNAS populate MAC Address with a new random MAC address to replace the default random address, or enter your own custom address.
Select a physical interface on your TrueNAS system from the NIC To Attach dropdown list.
(Optional) Select Trust Guest Filters to allow the virtual server to change its MAC address and join multicast groups.
This is required for the IPv6 Neighbor Discovery Protocol (NDP).
Setting this attribute has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address. Determine your network setup needs before setting this attribute.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Add a Disk Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select Disk from the Device Type dropdown list.
Select the path to the zvol created when setting up the VM on the Zvol dropdown list.
Select the hard disk emulation type from the Mode dropdown list.
Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM supports VirtIO disk devices.
Select the sector size in bytes in Disk Sector Size.
Leave set to Default or select either 512 or 4096 from the dropdown list.
Default uses the ZFS volume values.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Exporting a Disk to an Image
Use this function to convert a VM disk (zvol) to a portable disk image file.
Exported images can be imported into other VMs, transferred to different systems, or used as backups.
After stopping the VM and clicking Devices to open the Devices screen:
Click on the more_vert icon to the right of the disk device and then click Export to Image to open the Export Disk to Image window.
Browse to select the dataset/directory using the file browser. Click on the dataset/directory to select it and populate the mount path field.
Select the image format from the Image Format dropdown list.
Available formats include QCOW2 (QEMU Copy On Write), QED (QEMU Enhanced Disk), RAW (Raw Disk Image), VDI (VirtualBox Disk Image), VHDX (Hyper-V Virtual Hard Disk), and VMDK (VMware Virtual Machine Disk).
The system automatically adds the appropriate file extension to the name in Image Name.
Click Export. The system saves the disk as an image in the location you specified in Destination Directory.
Adding a PCI Passthrough Device
Depending upon the type of device installed in your system, you might see a warning: PCI device does not have a reset mechanism defined.
You may experience inconsistent or degraded behavior when starting or stopping the VM.
Determine if you want to proceed with this action in such an instance.
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select PCI Passthrough Device from the Device Type dropdown list.
Enter a value in PCI Passthrough Device using the format of bus#/slot#/fcn#.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a USB Passthrough Device
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select USB Passthrough Device from the Device Type dropdown list to configure the USB passthrough device.
Select the Controller Type from the dropdown list.
Select the hub controller type from the Device dropdown list.
If the type is not listed, select Specify custom, then enter the Vendor ID and Product ID.
Enter a new number that represents where in the boot sequence you want to place this device in Device Order.
The lower the number, the higher the device is in the boot sequence.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Adding a Display Device
Display devices have a 60-second inactivity timeout.
If the VM display session appears unresponsive, try refreshing the browser tab.
After stopping the VM and clicking Devices to open the Devices screen:
Click Add and select Display from the Device Type dropdown list to configure a new display device.
Select the Display Device option from the dropdown list.
TrueNAS allows a VM to have two different display devices: a VNC display device added through the VM creation wizard if the Enable Display (VNC) option is selected, and a second SPICE display device added to the VM using the Add Device screen with Device Type set to display.
If you created the VM without the display, the Display Type dropdown list shows the VNC and SPICE options.
Select the display type on the dropdown list. (VNC is recommended).
To add a second display device, repeat this procedure and select SPICE (the only option for the second display device).
Enter a fixed port number in Port.
To allow TrueNAS to assign the port after restarting the VM, set the value to zero (leave the field empty).
Specify the display session settings:
a. Select the screen resolution to use for the display from the Resolution dropdown.
b. Select an IP address for the display device to use in Bind. The default is 0.0.0.0.
c. Enter a unique password for the display device to securely access the VM.
Select Web Interface to allow access to the VNC web interface.
Click Save.
Click on the Virtual Machines breadcrumb at the top of the screen, and restart the VM.
Reporting
TrueNAS has a built-in reporting engine that provides helpful graphs and information about the system.
TrueNAS uses Netdata to gather metrics, create visualizations, and provide reporting statistics.
The built-in Netdata UI, accessible from the Netdata button on the Reporting screen in TrueNAS 24.04 and 24.10, is removed in TrueNAS 25.04 (and later) for security hardening.
Users wishing to continue using the Netdata UI to monitor system reports can install the Netdata application.
Reporting data is saved to permit viewing and monitoring usage trends over time.
This data is preserved across system upgrades and restarts.
TrueCommand offers enhanced features for reporting like creating custom graphs and comparing utilization across multiple systems.
Interacting with Graphs
Click on and drag a certain range of the graph to expand the information displayed in that selected area in the Graph.
Click on the icon to zoom in on the graph.
Click on the icon to zoom out on the graph.
Click the to move the graph forward.
Click the to move the graph backward.
Configuring Reporting Exporters
You can configure TrueNAS to export Netdata information to any time-series database, reporting cloud service or application installed on a server.
For example, Graphite, Grafana, etc., installed on a server or use their cloud service.
Creating reporting exporters enables TrueNAS to send Netdata data reporting metrics, formatted as a JSON object, to another reporting entity.
For more information on exporting Netdata records to other servers or services, refer to the Netdata exporting reference guide.
Graphite is a monitoring tool available as an application you can deploy on a server or use their cloud service.
It stores and renders time-series data based on a plaintext database.
Netdata exports data reporting metrics to Graphite in the format prefix.hostname.chart.dimension.
For additional information, see the Netdata Graphite exporting guide.
Adding a Reporting Exporter
To configure a reporting exporter in TrueNAS, you need the:
IP address of the reporting service or server.
If using another TrueNAS system with a data reporting application, this is the IP address of the TrueNAS running the application.
Port number the reporting service listens on.
If using another TrueNAS system with a reporting application, this is the port number the TrueNAS system listens on (port:80)
Go to Reporting and click on Exporters to open the Reporting Exporters screen.
Any reporting exporters configured on the system display on the Reporting Exporters screen.
Select Enable to send reporting metrics to the configured exporter instance.
Clearing the checkmark disables the exporter without removing configuration.
Enter the IP address for the data collection server or cloud service.
Enter the port number the report collecting server, etc. listens on.
Enter the file hierarchy structure, or where in the collecting server, etc. to send the data.
First enter the top-level in Prefix and then the data collection folder in the Namespace field.
For example, entering DF in Prefix and test in Namespace creates two folders in Graphite with DF as the parent to Test.
You can accept the defaults for all other settings, or enter configuration settings to match your use case.
Click Save.
To view the Graphite web UI, enter the IPaddress:Port# of the system hosting the application.
TrueNAS can now export the data records as Graphite-formatted JSON objects to the other report collection and processing application, service, or servers.
TrueNAS also populates the exporter screen with default settings.
To view these settings, click Edit on the row for the exporter.
System Settings
TrueNAS system management options are collected in this section of the UI and organized into a few different screens:
Update controls when the system applies a new version.
There are options to download and install an update, have the system check daily and stage updates, or apply a manual update file to the system.
General Settings shows system details and has basic, less intrusive management options, including web interface access, and localization of the UI and keyboard.
This is also where users can download a system debug, input an Enterprise license, or create a software bug ticket.
Advanced Settings contains options that are more central to the system configuration or meant for advanced users.
Specific options include configuring the system console, log, and dataset pool, managing sessions, adding custom system controls, kernel-level settings, scheduled scripting or commands, global two-factor authentication, NTP server connections, and determining any isolated GPU devices.
TrueNAS Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration.
Enterprise-licensed HA systems have access to the failover settings located on this screen.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Boot lists each ZFS boot environment stored on the system.
These restore the system to a previous version or a specific point in time.
Services displays each system component that runs continuously in the background.
These typically control data sharing or other external access to the system.
Individual services have their own configuration screens, start and stop buttons, and can be set to start automatically.
Shell allows users to use the Linux command-line interface (CLI) directly in the web UI.
Alert Settings allows users to configure Alert Services and to adjust the threshold and frequency of various alert types. See Alerts Settings Screens for more information.
Audit allows users to review auditing logs of all actions performed by a session, user, or service (SMB, middleware).
Enclosure appears when the system is attached to compatible TrueNAS hardware.
This is a visual representation of the system with additional details about disks and other physical hardware components.
Contents
Updating TrueNAS: Provides instructions on updating TrueNAS releases in the UI.
Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.
Advanced Settings: Tutorials for configuring advanced system settings in TrueNAS.
Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.
Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.
Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.
Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.
Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.
FTP: Provides instructions on configuring the FTP service including storage, user, and access permissions.
NFS: Provides information on configuring NFS service in TrueNAS.
SMB: Provides instructions on configuring the SMB service in TrueNAS.
SNMP: Provides information on configuring SNMP service in TrueNAS.
SSH: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.
UPS: Provides information on configuring UPS service in TrueNAS.
Using Shell: Provides information on using the TrueNAS shell.
Audit Logs: Provides information on the System and SMB Share auditing screens and function in TrueNAS.
Updating TrueNAS
TrueNAS has several software branches (linear update paths) known as trains.
Update profiles offer updates to the release running on your system based on specific use cases.
Some profiles are not available or recommended for Enterprise customers.
TrueNAS systems are shipped with the profile set for the user based on their use case.
The Update screen shows the installed version, other installation or update options, and user profiles.
Some users can select a different profile option from the Select and update profile dropdown list.
Software Update Paths
When upgrading TrueNAS to a new major version, follow the upgrade path of major versions until the system is on the desired major version release.
For more information on the upgrade path from one version to the next, see Software Releases.
See the Software Status page for the latest recommendations for software usage.
Do not change to a prerelease or nightly release unless you intend to keep the system permanently on early versions and are not storing critical data on it.
The Developer update profile allows using a non-production train in active development, but be prepared to experience bugs or other problems.
Testers are encouraged to submit bug reports with debug files.
For information on how to file an issue ticket, see Filing an Issue Ticket in TrueNAS.
The TrueNAS Update screen provides users with automatic and manual update methods.
We recommend updating TrueNAS when the system is idle (no clients connected, no disk activity, etc.).
The system restarts after an upgrade.
Update during scheduled maintenance times to avoid disrupting user activities.
All auxiliary parameters are subject to change between major versions of TrueNAS due to security and development issues.
We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
Automatically Updating
If an update is available, it shows in the Update Available section on the Update screen.
Select Export Password Secret Seed, then click Save Configuration.
Why should I save the secret seed?
The secret seed is 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.
TrueNAS downloads the configuration and the update files, then starts the installation.
After updating, clear the browser cache (CTRL+F5) before logging in to TrueNAS. This ensures stale data doesn’t interfere with loading the TrueNAS UI.
Manually Updating
If the system detects an available update, it and the Install Update button show below the current release running on the system.
Click Install Update. The Save configuration settings from this machine before updating? window opens.
Leave Export Password Secret Seed selected, and then click Save Configuration.
TrueNAS Manual update files are available from the TrueNAS Download page website.
If using the Developer update profile and a nightly build, you can use the manual update option to update the release running on your system if an update is not shown in the Update Available section of the Update screen.
Click Install to the right of Manual Update.
The Save configuration settings from this machine before updating? window opens.
Click Export Password Secret Seed, then click Save Configuration.
The Manual Update screen opens.
Click Choose File to locate the update file on your system.
Select a temporary location to store the update file.
Select Memory Device or the mount location from the dropdown list to keep a copy in the server.
Click Apply Update to start the update process. A status window opens and displays the installation progress.
When complete, the system automatically Restarts.
Update Progress
When a system update starts, appears in the toolbar at the top of the UI.
Click the icon to see the current status of the update and which TrueNAS administrative account initiated the update.
This procedure only applies to TrueNAS Enterprise (HA) systems.
If attempting to migrate from FreeBSD- to Linux-based TrueNAS versions, see TrueNAS Migrations.
Installing, upgrading, or making some changes to TrueNAS on High Availability (HA) systems is complicated and should be guided by Enterprise-level support.
Contact TrueNAS Enterprise Support for assistance whenever attempting to install or make some changes to TrueNAS on Enterprise HA hardware.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
If the system does not have an administrative user account, create the admin user as part of this procedure.
Take a screenshot of the license information found on the Support widget on the System > General Settings screen. You use this to verify the license after the update.
To update your Enterprise (HA) system to the latest TrueNAS release, log into the TrueNAS UI using the virtual IP (VIP) address and then:
Check for updates. Go to the main Dashboard and click Check for Updates on the System Information widget for the active controller.
This opens the System > Update screen. If an update is available for the Update Profile selected, it shows on this screen.
Click Install Update.
Save the password secret seed and configuration settings to a secure location.
The Save configuration settings window opens.
Leave Export Password Secret Seed selected, then click Save Configuration.
The system downloads the file with sensitive system data. Keep this file in a secure location.
Why should I save the secret seed?
The secret seed is 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.
Click Install to begin the installation, click Cancel to return to the Update screen.
If manually updating your system:
click Install to the right of Manual Update.
Save the secret seed, and configuration file to a secure location, and click Save Configuration to show the Manual Install screen.
Click Choose File and use the file browser to select the update file downloaded to your system.
Click Apply Update to start the update process.
After the system finishes updating it restarts.
After the system sign-in screen shows:
Sign in to the TrueNAS UI. If using root to sign in, create the admin account (see step 3).
If using admin, continue to the next step.
Verify the system license after the update. Go to System > General Settings.
Verify the license information in the screenshot of the Support widget you took before the update matches the information on the Support widget after updating the system.
Verify the admin user settings, or if not created, create the admin user account now.
Before adding a new admin user, create a dataset for home directories if you do not have one already set up.
If editing an existing admin user, select the user on the Credentials > Users screen and click Edit.
If you want the admin account to have the ability to execute sudo commands in an SSH session, set Allow Access to both TrueNAS Access and SSH Access, assign the new admin user the Full Admin role.
Add the SSH pubic key, enter and confirm the password, then go to Sudo Commands to set the option for sudo access you want to allow.
Verify Shell is set to bash if you want to give the admin user the ability to execute commands in Shell.
To set a location where the admin user can save or browse files, and then select the dataset path in Home Directory.
If set to the default /nonexistent files are not saved for this user.
Click Save to create the user or save changes to the existing user.
Verify the admin user can log in to the UI.
a. Log out of the UI.
b. Enter the admin user credentials in the sign-in splash screen.
After validating access to the TrueNAS UI using the admin credentials, disable the root user password.
Go to Credentials > User, select the root user, then click Edit. Select Dissable Password and click Save.
The TrueNAS General Settings provide options to configure support, file a ticket or provide feedback on the UI or a feature, download a system debug, configure a graphic user interface (GUI), set UI and keyboard languages, and add system email.
The Support widget shows information about the TrueNAS version and system hardware.
Links to the open-source TrueNAS documentation, community forums, and official Enterprise licensing are provided.
Add License opens a screen where you can paste a copy of your TrueNAS Enterprise license (details).
After adding a license, the option changes to Update License.
Save Debug starts a download of the system debug file.
File Ticket opens the Send Feedback window with two options: Rate this page and Report a bug.
These options allow you to report a system bug or to send TrueNAS feedback on the UI and rate a screen. Feedback goes to the TrueNAS development team.
An icon shows on new UI feature screens where TrueNAS is asking you to send feedback, and it allow you to capture a screenshot of that screen.
Proactive Support shows for Enterprise-licensed systems.
It opens the Proactive Support window, where you enter configuration settings to set up proactive support for an Enterprise system.
For information on configuring proactive support, see Adding a License and Proactive Support.
Sending Feedback
TrueNAS provides two feedback options: one to rate a UI screen and the other to report a problem encountered with the system.
Some screens show the option to rate the screen.
Click on the Send Feedback icon to open the feedback window.
The window allows you to select the Report a bug option to open a Jira ticket.
To send feedback, go to System > General Settings, and click File Ticket on the Support widget.
The File Ticket option on Enterprise systems shows two options: File Ticket and Proactvie Support. Select File Ticket to open the Send Feedback window.
Rating a UI Screen
Select Rate this page to show the options to send feedback on a UI page, add comments, add a screenshot or additional images, or click the link to go to the TrueNAS forum where you can vote for new features on the community forum, report a problem, or suggest improvements directly to the TrueNAS development team.
Select Report a bug to show the options to open an engineering ticket and submit it directly to the TrueNAS development team when a TrueNAS screen or feature is not working as intended.
Submitting a bug report requires a free Atlassian account.
Select Report a bug to see the fields to create a Jira engineering ticket.
For example, reporting a bug where a middleware error and traceback occurred while saving a configuration change. You must have a Jira account to submit a ticket.
Enter a descriptive summary in the Subject.
For example, if an application does not update after clicking the update option for the app and you get an error message or traceback after attempting the update, enter XYZ application fails to update with a traceback in Subject.
Enter the details of actions taken that resulted in the error or failed action in Message.
With the same example, enter more details on the issue:
Clicked on the XYZ app row, stopped the app, clicked Update, but the update failed, and showed the following traceback message (include the traceback text).
My system is running on TrueNAS 25.10.0.
Keep the details concise and focused on how to reproduce the issue, what you expected from the actions taken, and the actual result.
This helps ensure a speedy ticket resolution.
Include system debug is enabled by default. You can also include screenshot files, which can speed up the issue resolution.
Attach Debug is selected by default. This uploads the debug file to a Private Attachment ticket to protect sensitive data in the log files, and it links this ticket to the Jira report ticket. Only authorized TrueNAS developers can access the debug file.
To attach a screenshot of the current page, select Take screenshot of the current page, or Attach additional images, which opens a file browser where you can select log.txt, image, or video files to attach to the ticket.
Before using this form, take screenshots of the screen, copy the traceback or other error messages to a text file, copy a log into a text file, or create any other file to attach.
After opening this form, attach those files by selecting Attach additional images and clicking Choose File opens a File Explorer window where you can browse to select the files you want to attach to the report.
TrueNAS can show a list of existing Jira tickets with similar summaries.
When there is an existing ticket about the issue, consider clicking on that ticket and leaving a comment instead of creating a new one.
Duplicate tickets are closed in favor of consolidating feedback into one report.
Click Login To Jira To Submit to finish and submit the report.
Reporting an Issue - Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug screen includes additional environment and contact information fields for sending bug reports directly to the TrueNAS team.
Filling out the entire form with precise details and accurate contact information ensures a prompt response from the TrueNAS Customer Support team.
Configuring GUI Options
The GUI widget allows users to configure the TrueNAS web interface address. Click Settings on the widget to open the GUI Settings configuration screen.
The system uses a self-signed certificate to enable encrypted web interface connections.
To change the default certificate, create or import a certificate as described in Managing Certificates to add it to the dropdown list of certificates available on the system. Select the certificate from the GUI SSL Certificate dropdown list.
Setting the Web Interface IP Address
To set the WebUI IP address, when using IPv4 addresses, select a recent IP address on the Web Interface IPv4 Address dropdown list. This limits the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
When using an IPv6 address, select a recent IP address from the Web Interface IPv6 Address dropdown list.
Configuring HTTPS Options
To allow configuring a non-standard port to access the GUI over HTTPS, enter a port number in the Web Interface HTTPS Port field.
Select the cryptographic protocols for securing client/server connections from the HTTPS Protocols dropdown list.
Select the Transport Layer Security (TLS) versions TrueNAS can use for connection security.
To redirect HTTP connections to HTTPS, select Web Interface HTTP -> HTTPS Redirect. A GUI SSL Certificate is required for HTTPS.
Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year).
This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year.
A warning displays when setting this function.
Select Crash Reporting to send failed HTTP request data, which might include client and server IP addresses, tracebacks for failed method calls, and middleware log file contents to TrueNAS.
Sending Usage Statistics and UI Error Reports
To send anonymous usage statistics and WebUI errors to TrueNAS, select the Usage Collection & UI Error Reporting option.
When enabled, anonymous usage statistics and WebUI errors are reported to the TrueNAS engineering team.
No personally identifiable information is collected.
When disabled, anonymous usage statistics consisting only of the software version and total system capacity (e.g., TrueNAS 24.04.0, 55 TB) are collected.
To show real-time console messages at the bottom of the browser window, select Show Console Messages.
Localizing the TrueNAS System
Localizing the TrueNAS system consists of changing the UI language and the keyboard layout to support the selected language, setting the time zone to match where the TrueNAS server is located, and setting date and time formats.
To change the Web UI on-screen language and set the keyboard to work with the selected language, click Settings on the Localization widget to open the Localization Settings configuration screen.
Clear the field and begin typing in the field to filter the long list of languages, or scroll to select an option from the Language dropdown list.
Scroll to select the keyboard language layout in Console Keyboard Map.
Begin typing in the Timezone field to filter the long list or scroll down to select the geographic timezone that corresponds to the location of the TrueNAS server.
Select the local date and time formats to use.
Click Save.
Setting Up System Email
The Email widget displays information about current system mail settings.
When configured, an automatic script sends a nightly email to the administrator account containing important information, such as the health of the disks.
To configure the system email send method, click Settings to open the Email Options screen.
Select either SMTP or GMail OAuth to display the relevant configuration settings.
For more information on configuring system email, see Setting Up System Email.
Setting Up System Email: Provides instructions on configuring email using SMTP or GMail OAuth and setting up the email alert service in TrueNAS.
Adding a License and Proactive Support
Adding a TrueNAS Enterprise License
For users with a valid TrueNAS license, click Add License.
Copy your license into the box and click Save.
You are prompted to reload the page for the license to take effect, click RELOAD NOW.
Log back into the WebUI where the End User License Agreement (EULA) displays.
Read it thoroughly and completely.
After you finish, click I AGREE.
The system information updates to reflect the licensing specifics for the system.
Silver and Gold level Support customers can also enable Proactive Support on their hardware to automatically notify iXsystems if an issue occurs.
To find more details about the different Warranty and Service Level Agreement (SLA) options available, see TrueNAS Enterprise Support.
When the system is ready to be in production, update the status by selecting This is a production system and then click the Proceed button.
This sends an email to iXsystems declaring that the system is in production.
While not required for declaring the system is in production, TrueNAS has the option to include an initial debug with the email that can assist support in the future.
Setting Up Proactive Support
Silver/Gold Coverage Customers can enable iXsystems Proactive Support.
This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
To configure proactive support, click Get Support on the Support widget located on the System > General Settings screen.
Select Proactive Support from the dropdown list.
Complete all available fields and select Enable iXsystems Proactive Support, then click Save.
Setting Up System Email
An automatic script sends a nightly email containing important information such as disk health to configured recipients.
For fast awareness and resolution of critical issues, configure TrueNAS system email with the recipient addresses that should receive these notifications.
TrueNAS mails Scrub Task issues separately to the address configured in those services.
Configuring Email Recipients
Starting with TrueNAS 25.10, system emails are sent to a configurable list of recipients rather than automatically using local administrator email addresses. Configure the recipient list in the system email settings to specify who receives system notifications.
Setting Up System Email
Configure the send method and recipients for the email service.
Go to System > General Settings and locate the Email widget to view the current configuration, or click the Alerts icon at the top right of the UI screen, then click the gear settings icon, and select Email to open the General Settings screen.
Click Settings on the Email Widget to open the Email Options screen.
The configuration options change based on the selected method.
After configuring the send method, click Send Test Mail to verify you can send email.
If the email test fails, verify the recipient addresses are correctly configured in the Email Recipients field.
Save stores the email configuration and closes the Email Options screen.
Configuring Email Using SMTP
To set up SMTP service as the system email send method, you need the outgoing mail server and port number for the email address.
Enter the email address that sends the alerts in From Email and the name that appears before the address in From Name.
Enter the SMTP server host name or IP address in Outgoing Mail Server.
Enter the SMTP port number in Mail Server Port. This is typically 25, 465 (secure SMTP) or 587 (submission).
Select the level of security from the Security dropdown list.
Options are Plain (No Encryption), SSL (Implicit TLS), or TLS (STARTTLS).
Select SMTP Authentication for TrueNAS to reuse authentication credentials from the SMTP server.
Enter the SMTP credentials in the new fields that appear.
Typically, Username is the full email address, and Password is the password for that account.
Click Send Test Email to verify you receive an email.
Click Save.
Configuring Email Using GMail OAuth
To set up the system email using Gmail OAuth, use the TrueNAS web UI to log in to your Gmail account.
Select the account to use for authentication or select Use another account.
When prompted, enter the Gmail account credentials.
Type in the GMail account to use and click Next.
Enter the password for the GMail account you entered.
When the TrueNAS wants to access your Google Account window opens, scroll down and click Allow to complete the setup or Cancel to exit setup and close the window.
After setting up Gmail OAuth authentication, the Email Options screen displays Gmail credentials have been applied, and the button changes to Log In To Gmail Again.
Enter the email, phone number, or Skype username associated with your Outlook account, then click Next to enter your password.
When the TrueNAS wants to access your Outlook Account window opens, scroll down and click Allow to complete the setup or Cancel to exit the setup process.
After setting up Outlook OAuth authentication, the Email Options screen shows Outlook credentials have been applied and the button changes to Logged In To Outlook.
Click Send Test Email to verify you receive an email.
Click Save.
Setting Up the Email Alert Service
After configuring the system email send method, configured recipients receive a system health email every night/morning.
To add or configure the Email Alert Service to send timely warnings when a system alert hits the warning level specified in Alert Settings:
Go to System > Alert Settings or from any screen, click on the Alertsnotifications icon at the top right of the screen to open the Alerts panel.
Click on the settings settings icon and then on Alert Settings.
Locate Email under Alert Services, select the more_vert icon, and then click Edit to open the Edit Alert Service screen.
Add the alert recipient email address in the Email Address field.
Use the Level dropdown to adjust the email warning threshold or accept the default Warning setting.
Click Send Test Alert to generate a test alert and confirm the email address and alert services work.
Advanced Settings
Advanced Settings provides configuration options for the console, syslog, kernel, sysctl, replication, cron jobs, init/shutdown scripts, system dataset pool, isolated GPU device(s), self-encrypting drives, system access sessions, allowed IP addresses, audit logging, and global two-factor authentication.
TrueNAS Enterprise
Enterprise-licensed system administrators have additional options to configure security-related settings, such as FIPS and STIG compatibility and Self-Encrypting Drive (SED) configuration.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Audit widget displays the current audit storage and retention policy settings.
The public-facing TrueNAS API allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
Use Add on the Sysctl widget to add a tunable that configures a kernel module parameter at runtime.
The Add Sysctl or Edit Sysctl configuration screens display the settings.
Enter the sysctl variable name in Variable. Sysctl tunables configure kernel module parameters while the system runs and generally take effect immediately.
Enter a description and then select Enabled. To disable but not delete the variable, clear the Enabled checkbox.
Click Save.
Adding NTP Servers
The NTP Servers widget allows users to add Network Time Protocol (NTP) servers.
These sync the local system time with an accurate external reference.
By default, new installations use several existing NTP servers. TrueNAS supports adding custom NTP servers.
Managing the System Dataset
Storage widget shows the pool configured as the system dataset pool and allows users to select a different storage pool to hold the system dataset.
The system dataset stores core files for debugging and keys for encrypted pools.
It also stores Samba4 metadata, such as the user and group cache and share-level permissions.
It also includes the reslivering priority setting.
Configure opens the Storage Settings configuration screen.
Storage Settings Configuration Screen
If the system has one pool, TrueNAS configures that pool as the system dataset pool.
If your system has more than one pool, you can set the system dataset pool using the Select Pool dropdown.
Users can move the system dataset to an unencrypted or key-encrypted pool.
Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward.
If the encrypted pool already has a passphrase set, you cannot move the system dataset to that pool.
Changing Resilvering Priority
To set a different resiliver priority, select Run Resilvering At Higher Priority At Certain Times.
Two additional setting options show that allow you to configure the day and time range for resilvering to run.
To return to the default resilver prioirty, clear the checkbox and click Save.
Setting the Number of Replication Tasks
The Replication widget displays the number of replication tasks that can execute simultaneously on the system. It allows users to adjust the maximum number of replication tasks the system can execute simultaneously.
Click Configure to open the Replication configuration screen.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
Managing Allowed IP Addresses
Use the System > Advanced Settings screen Allowed IP Addresses configuration screen to restrict access to the TrueNAS web UI and API.
Entering an IP address limits access to the system to only the address(es) entered here. To allow unrestricted access to all IP addresses, leave this list empty.
Managing Access (WebSocket Sessions)
The Access widget shows a list of all active sessions including the current logged-in user and the time it started.
The Session Timeout setting shows the number of minutes for the current session.
The Login Banner shows the custom text entered on the Access Settings screen. This text shows before the login screen.
When configured, users see the login banner and must click Continue to show the TrueNAS login splash screen.
Administrators can manage other active sessions and configure the session timeout for their accounts.
Terminate Other Sessions ends all sessions except the current session.
To end individual sessions, click the logout button next to that session.
You must check a confirmation box before the system allows you to end sessions.
The logout icon is inactive for the currently logged-in administrator session and active for any other current sessions.
It cannot be used to terminate the currently logged-in active administrator session.
Session Timeout shows the configured token duration for the current session (default is five minutes).
TrueNAS logs out user sessions that are inactive for longer than the configured token setting for the user.
New activity resets the token counter.
When the configured session timeout is exceeded, TrueNAS displays a Logout dialog with the exceeded ticket lifetime value and the time the session is scheduled to terminate.
Enter a value in the number of seconds to suit your needs and security requirements. For example, to change the timeout to 10 minutes, enter 6000.
The default session timeout setting is 300 seconds or five minutes.
The minimum value allowed is 30 seconds, and the maximum is 2147482 seconds, or 20 hours, 31 minutes, and 22 seconds.
Click Save.
Adding a Banner
To show a login banner before the login screen shows, enter the text in the Login Banner field.
Use carriage returns to break up a large block of text and to improve the readability of the text.
After saving the text. The next time an administrative user logs into the UI, a banner screen shows.
To advance to the login screen, click Continue.
Allowing Directory Service Users to Access the UI
TrueNAS Enterprise
Only Enterprise-licensed systems allow TrueNAS web UI access for Directory Service accounts
TrueNAS allows Enterprise users to show the UI to users in an Active Directory group.
To configure this access, first, add the selected AD users to a group that is granted a TrueNAS privilege that permits it, and enable the Allow Directory Service users to access WebUI option on the Access Settings screen. This option only shows on Enterprise-licensed systems.
After TrueNAS joins AD, it automatically creates a new privilege entry in the Privileges screen table, and this privilege is automatically populated with the domain admins group for the domain.
You can edit this privilege by selecting the table row and clicking Edit.
Never modify the settings for the standard pre-defined privileges (listed below)! Changing these pre-defined roles can result in lost access to the UI!
Pre-defined TrueNAS privileges are:
Read-Only Administrator - Allows the user to view settings but not make changes in the UI.
Sharing Administrator - Allows the user to create new shares and the share dataset.
Local Administrator - Gives full control (read/write/exeute permissions) to the user.
Security Settings
TrueNAS Enterprise
Only Enterprise-licensed systems show the Security widget and have access to the STIG and FIPS settings.
Administrators considering enabling STIG and FIPS security settings should contact TrueNAS Support before making any changes.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Review these topics and contact TrueNAS Support before enabling STIG and FIPS security settings.
When STIG (and FIPS) are enabled:
TrueNAS cannot issue API keys, and existing API keys cannot be used for authentication. Only the user credential with a two-factor authentication method is accepted.
SSH log-ins require a cryptographic algorithm.
SMB authentication for local TrueNAS accounts is disabled.
NTLM authentication passthrough to a domain controller is disabled.
Usage stats are not reported, and the Usage Collection option is disabled.
One-time passwords (OTP) configured for administrative users have a single use and expire after 24 hours.
After logging in with the OTP, the system prompts the user to immediately change the password and set up two-factor authentication.
TrueNAS is limited to a maximum of 10 concurrent sessions.
Accounts lock for 15 minutes after three consecutive failed login attempts.
Password aging rules are applied to the SMB protocol. After a failed login attempt, users with expired passwords receive a password-expired message.
TrueNAS prompts users to change their passwords when logging in, and the system flags the account as requiring this change.
Users cannot reuse a password if it is marked as used within the last five passwords in the history file. Passwords must be 15 characters in length.
TrueNAS updates can only use a signed update file provided by the TrueNAS team.
What features are not available?
When enabled, STIG disables these features:
Virtualization
Apps
TrueCommand connectivity
What events are included in auditing?
When STIG (and FIPS) are enabled, auditing includes these events:
Account creation events
Privilege commands (with full text of the commands run)
Privilege changes
Log-ins and other system access events.
Account log-ins are tracked from two distinct sources (UI and SSH)
Kernel module load/unload
Audit log modifications and attempts to modify audit logs
Security object modifications and attempts to modify security objects
Configuring STIG and FIPS
To set up FIPS or STIG compliance on a TrueNAS server, you must first configure two-factor authentication for an admin user with full permissions.
After configuring two-factor authentication, go to System > Advanced Settings and locate the Security widget.
Click Settings to open the System Security configuration screen.
Select the toggle to enable FIPS and STIG, then click Save.
You must enable FIPS with STIG!
The system prompts you to restart.
The system restart takes several minutes to complete before showing the login screen.
Highly Available (HA) systems must restart each storage controller before STIG mode is fully enabled.
TrueNAS Administrator Password Rules
The remaining options are for setting TrueNAS administrator password rules.
Options include defining a password lifetime, types of characters that must be present in the password, how many characters must be present in a valid password, and how many previously used passwords to remember for an account and prevent reuse in a new password.
Adjust these as needed for your security requirements.
Enabling STIG compatibility mode requires specific minimum values for these settings.
Note that TrueNAS begins warning all local account types (administrator, full admin, read-only, and sharing-only) seven days before password expiration. After expiration, the account locks and requires administrative action to unlock.
Additional Content
Managing the System Configuration: Provides information on downloading your TrueNAS configuration to back up system settings, uploading a new configuration file, and resetting back to default settings.
Managing Cron Jobs: Provides information on adding or modifying cron jobs in TrueNAS.
Managing the Console Setup Menu: Provides information on the Console setup menu configuration settings including the serial port, port speed, password protection, and the banner users see.
Managing System Logging: Provides information on setting up or changing syslog server settings, the level of logging, the information included in the logs, and using TLS as the transport protocol.
Configuring SED Settings: Provides information on adding or modifying self-encrypting drive (SED) user and global passwords in TrueNAS.
Developer Mode (Unsupported): Provides information on the unsupported TrueNAS developer mode and how to enable it.
Managing the System Configuration
TrueNAS allows users to manage the system configuration by uploading or downloading configurations or by resetting the system to the default configuration.
System Configuration Options
The Manage Configuration option on the System > Advanced Settings screen provides three options:
Download File that downloads your system configuration settings to a file on your system.
Upload File that allows you to upload a replacement configuration file.
Reset to Defaults resets system configuration settings back to factory settings.
Downloading the File
The Download File option downloads your TrueNAS current configuration to the local machine.
A system config file is a database file containing your settings, including accounts, directory services, networking, services, shares, storage configuration, system settings, data protection tasks, and more.
In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file.
Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations.
See Using Administrator Logins for more information on admin account types.
When downloading the configuration (config) file, select the Export Password Secret Seed option to include the secret seed in the config file.
Downloading the config file allows you to restore the system to a different operating system device where the secret seed is not already present.
Why should I save the secret seed?
The secret seed is 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.
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?
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.
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 a system configuration reset is required.
TrueNAS Enterprise Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
Save the current system configuration with the Download File option before resetting the configuration to default settings!
If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.
The Reset to Defaults option resets the system configuration to factory settings.
After the configuration resets, the system restarts, and users must set a new login password.
Remote Backups of the Config File
TrueCommand provides an easy solution for users who want to schedule an automatic remote backup of the system configuration file:
Cron jobs allow users to configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Cron Jobs widget on the System > Advanced Settings screen displays No Cron Jobs configured until you add a cron job, and then it displays information on cron job(s) configured on the system.
Click Add to open the Add Cron Job configuration screen and create a new cron job. If you want to modify an existing cron job, click anywhere on the item to open the Edit Cron Jobs configuration screen populated with the settings for that cron job.
The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Enter a description for the cron job.
Next, enter the full path to the command or script to run in Command. For example, for a command string to create a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt.
Select a user account to run the command from the Run As User dropdown list. The user must have permissions allowing them to run the command or script.
Select a schedule preset or choose Custom to open the advanced scheduler.
An in-progress cron task postpones any later scheduled instances of the task until the one already running completes.
Cron Job Schedule Format
Cron job schedules use six asterisks that represent minutes, hours, days of the month, days of the week, and months in that order.
For example, a schedule of 1 1 1 * sat,sun would run at 01:01 AM, on day 1 of the month, and only on Saturday and Sunday.
Separate multiple values for a segment with commas, not spaces.
If you want to hide standard output (stdout) from the command, select Hide Standard Output. If left cleared, TrueNAS emails any standard output to the user account cron that ran the command.
To hide error output (stderr) from the command, select Hide Standard Error. If left cleared, TrueNAS emails any error output to the user account cron that ran the command.
Select Enabled to enable this cron job. Leave this checkbox cleared to disable the cron job without deleting it.
Click Save.
The TrueNAS UI has several fields that allow users to write custom scripts. When a user writes a password into a custom script, the password is provided in cleartext form within system debug files, creating a serious security concern.
We do not recommend using custom scripting on TrueNAS, as it is a highly advanced feature for expert storage administrators and can lead to security breaches.
Managing the Console Setup Menu
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
The Console widget on the System > Advanced Settings screen displays current console settings for TrueNAS.
Click Configure to open the Console configuration screen. The Console configuration settings determine how the Console setup menu displays, the serial port it uses and the speed of the port, and the banner users see when it is accessed.
To display the console without being prompted to enter a password, select Show Text Console without Password Prompt. Leave it clear to add a login prompt to the system before showing the console menu.
Select Enable Serial Console to enable the serial console but do not select this if the serial port is disabled.
Enter the serial console port address in Serial Port and set the speed (in bits per second) from the Serial Speed dropdown list. Options are 9600, 19200, 38400, 57600 or 115200.
Finally, enter the message you want to display when a user logs in with SSH in MOTD Banner.
Click Save
Managing System Logging
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
By default, TrueNAS writes system logs to the system boot device.
The Syslog widget on the System > Advanced Settings screen allows users determine how and when the system sends log messages to a connected syslog server or server array of two servers.
Each syslog server can have its own host, transport, and TLS certificate settings.
The Syslog widget displays the existing system logging settings.
Before configuring your syslog server to use TLS as the Syslog Transport method, first add a certificate(s) to the TrueNAS system.
Go to Credentials > Certificates and use the Certificates widget to verify you have the required certificates, and if not present, to import them.
Click Configure to open the Syslog configuration screen.
The Syslog configuration screen settings specify the logging level the system uses to record system events, the syslog server DNS host name or IP, the transport protocol it uses, and if using TLS, the certificate for that server, and finally if it uses the system dataset to store the logs.
Select Use FQDN for Logging to include the fully-qualified domain name (FQDN) in logs to precisely identify systems with similar host names.
Select the minimum log priority level to send to the remote syslog server (or array) from the Syslog Level dropdown list.
The system only sends logs at or above this level.
Enter the remote syslog server DNS host name or IP address in the Syslog server Host field.
To use non-standard port numbers like mysyslogserver:1928, add a colon and the port number to the host name.
Log entries are written to local logs and sent to the remote syslog server.
Select the transport protocol for the remote system log server connection in Transport.
Selecting Transport Layer Security (TLS) shows the Syslog TLS Certificate field.
Select the certificate from the TLS Certificate dropdown list.
To add a second syslog server, click Add Syslog Server again and repeat the steps above.
Select Include Audit Logs to enable audit logging.
Click Save.
Configuring SED Settings
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
UI management of Self-Encrypting Drives (SED) is an Enterprise-licensed feature in TrueNAS 25.04 (and later).
SED configuration options are not visible in the TrueNAS Community Edition.
Community users wishing to implement SEDs can continue to do so using the command line sedutil-cli utility.
Note: Additional changes to SED management options in the TrueNAS UI ahead of the 25.04.0 release version, with documentation updates to follow.
Configuring Global SED Settings
To configure global SED settings, go to the System > Advanced Settings screen and locate the Self-Encrypting Drive widget.
Select the user to unlock SEDs from the ATA Security User dropdown list.
Options are USER or MASTER.
Enter the global SED password in SED Password and in Confirm SED Password.
Click Save.
Remember SED passwords!
If you lose the SED password, you cannot unlock SEDs or access their data.
After configuring or modifying SED passwords, always record and store them in a secure location!
Configuring Individual SED Passwords
To configure individual, per-disk SED passwords, go to Storage and click Disks in the top right of the screen to open the Disks screen.
Click the row or expand_more for a confirmed SED to expand the row.
Click Edit to open the Edit Disk screen.
Enter and confirm the password in the SED Password fields to assign an individual SED password.
If both an individual and global SED password are present, the individual SED password overrides the global password for the disk it is configured on.
Repeat this process for each SED and any SEDs added to the system in the future.
The Init/Shutdown Scripts widget on the System > Advanced Settings screen allows you to add scripts to run before or after initialization (start-up), or at shutdown. For example, creating a script to backup your system or run a systemd command before exiting and shutting down the system.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, and then the widget lists the scripts configured on the system.
Note that the table(s) below can be reorganized by clicking on the column titles. This allows you to toggle the information in each toggle between a descending and ascending order.
Enter a description and then select Command or Script from the Type dropdown list. Selecting Script displays additional options.
Enter the command string in Command, or if using a script, enter or use the browse to the path in Script. The script runs using dash(1).
Select the option from the When dropdown list for the time this command or script runs.
Enter the number of seconds after the script runs that the command should stop in Timeout.
Select Enable to enable the script. Leave clear to disable but not delete the script.
Click Save.
Script Execution
Scripts run at different points in the system lifecycle based on the option you select in the When dropdown:
Pre Init: Select to run a script early in the boot process, after filesystems and networking are available.
Post Init: Select to run a script later in the boot process, just before TrueNAS services start.
Shutdown: Select to run a script during system shutdown, after services begin stopping.
Scripts in the same category (for example, multiple Post Init scripts) run sequentially in the order in which the user added them.
Use the Timeout setting to limit how long each script runs. A script that hangs or takes too long delays the next script in that category.
Shutdown scripts run while the system powers down, so not all services or resources remain available.
Editing an Init/Shutdown Script
Click a script listed on the Init/Shutdown Scripts widget to open the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
You can change from a command to a script, and modify the script or command as needed.
To disable but not delete the command or script, clear the Enabled checkbox.
Click Save.
Isolating GPU for VMs
Systems with more than one graphics processing unit (GPU) installed can isolate additional GPU device(s) from the host operating system (OS) and allocate them for use by a virtual machine (VM).
Isolated GPU devices are unavailable to the OS and for allocation to applications.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
To isolate a GPU, you must have at least two in your system; one available to the host system for system functions and the other available to isolate for use by a VM.
One isolated GPU device can be used by a single VM.
Isolated GPU cannot be allocated to applications.
To allocate an isolated GPU device, select it while creating or editing VM configuration.
When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM and becomes unavailable for any other allocations.
Click Configure on the Isolated GPU Device(s) widget to open the Isolate GPU PCI Ids screen, where you can select a GPU device to isolate.
Reboot the system after adding or removing a GPU from isolation to ensure the device isolation status is fully updated.
Managing Global 2FA (Two-Factor Authentication)
Global Two-factor authentication (2FA) is great for increasing security.
TrueNAS offers global 2FA to ensure that entities cannot use a compromised administrator or root password to access the administrator interface.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
To use 2FA, you need a mobile device (or desktop application) with the correct time and date, and a TOTP-compatible authenticator app installed.
TrueNAS uses the TOTP (Time-based One-Time Password) standard (RFC 6238), which is compatible with most authenticator apps. Popular options include:
Microsoft Authenticator (iOS, Android)
Google Authenticator (iOS, Android)
Authy (iOS, Android, desktop)
Bitwarden (cross-platform, open source)
1Password (cross-platform)
Choose an authenticator app based on your platform and preferences. All TOTP-compatible apps work with TrueNAS.
Two-factor authentication is time-based and requires a correct system time setting.
We strongly recommend ensuring Network Time Protocol (NTP) is functional before enabling two-factor authentication!
What is 2FA and why should I enable it?
2FA adds an extra layer of security to your system to prevent someone from logging in, even if they have your password.
2FA requires you to verify your identity using a randomized six-digit code that regenerates every 30 seconds (unless modified) to use when you log in.
Benefits of 2FA
Unauthorized users cannot log in since they do not have the randomized six-digit code.
Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.
Internet access on the TrueNAS system is not required to use 2FA.
Drawbacks of 2FA
2FA requires an app to generate the 2FA code.
If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled).
You can bypass or unlock 2FA using the CLI.
Enabling Global 2FA
Set up a second 2FA device as a backup before proceeding.
Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.
Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Configure.
If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.
The Window setting extends the validity of authentication codes to include previously generated codes. This can be helpful in high-latency situations where there can be delays between code generation and entry. The default setting works for most environments - only adjust this if users experience authentication issues due to network delays.
After enabling Global 2FA, the system prompts users to set up their individual 2FA configuration:
Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until Global 2FA is enabled.
When Global 2FA is enabled, user accounts without 2FA settings configured are prompted with the Two-Factor Authentication screen on their next login to set up 2FA authentication for that account.
See Setting Up Individual 2FA for detailed instructions on configuring 2FA for individual user accounts.
Disabling Global 2FA
Go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Config. Clear the Enable Two-Factor Authentication Globally checkbox and click Save.
Reactivating Global 2FA
If you want to enable 2FA again, go to System > Advanced Settings, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save.
To change the system-generated Secret, click on the Settings icon on the top toolbar and select Two-Factor Authentication.
Click Renew 2FA Secret.
Setting Up Individual 2FA
When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. Users can also set up 2FA at any time by accessing Settings > Two-Factor Authentication from the top toolbar.
Set up a second 2FA device as a backup before proceeding.
Before you begin, install a TOTP-compatible authenticator app on your mobile device or desktop computer. See About TrueNAS 2FA for recommended options.
To set up individual 2FA:
Click the Settings icon on the top toolbar, then select Two-Factor Authentication to open the User Two-Factor Authentication Actions screen.
Click Configure 2FA Secret to open the Set Up Two-Factor Authentication screen and view the QR code. The Set Up Two-Factor Authentication screen also has the unique key with a copy to clipboard button so you can configure 2FA using a non-camera method if necessary.
You can configure two-factor authentication and get the QR code for an authenticator app for the logged-in user at any time, but you must configure global two-factor authentication to enable it.
Set Interval to 30 seconds to match the default setting used by most authenticator apps. Using a non-standard interval can cause authentication codes to fail during login.
Scan the QR code using your authenticator app or manually enter the unique key.
To generate a new QR code click Renew 2FA Secret.
When administrators enable Global 2FA, users without 2FA configured are prompted to set it up on their next login. However, individual setup is optional and can be skipped. See Setting Up Individual 2FA for the full setup process.
To skip the setup:
When the Two-Factor Authentication setup screen appears, click Skip Setup.
Confirm the decision in the dialog that appears.
While 2FA significantly enhances security and is strongly recommended, skipping the initial setup does not prevent access to the system. Users can configure 2FA later by accessing Settings > Two-Factor Authentication from the top toolbar.
The setup prompt appears once per login session. If you skip setup, you are prompted again on your next login until you configure 2FA.
Removing Individual 2FA Configuration
Users can remove their personal 2FA configuration without disabling global 2FA:
Click the Settings icon on the top toolbar and select Two-Factor Authentication.
Click Unset 2FA Secret.
Confirm the removal when prompted.
Removing 2FA configuration reduces account security. Only remove 2FA if you plan to reconfigure it with a different authenticator device, or if you no longer have access to your current authenticator.
After removing your 2FA configuration:
If Global 2FA is still enabled, you are prompted to set up 2FA again on your next login
You can skip this prompt if needed using the Skip Setup button
2FA configurations for other users remain unaffected
Administrator Clearing User 2FA
Administrators can clear 2FA for any user without needing to log in as that user. This is useful when:
A user has lost access to their authenticator device
A user is locked out due to 2FA issues
Troubleshooting login problems for users
To clear 2FA for another user:
Go to Credentials > Users
Select the user whose 2FA needs to be cleared
Click Clear Two-Factor Authentication on the Access widget
Confirm the action in the dialog
After clearing, the user can log in without 2FA. If Global 2FA is still enabled, they are prompted to reconfigure 2FA on their next login.
TOTP codes regenerate every 30 seconds (by default). If a code expires while you are entering it, wait for your authenticator app to display a new code and retry.
Logging In Using SSH
Confirm that you set Enable Two-Factor Auth for SSH in System > Advanced > Global Two Factor Authentication.
Go to Credentials > Users and edit the desired user account. Set SSH password login enabled, then click Save.
Go to System Settings > Services and click the SSHStart Service button to start the service. Wait for the service status to show that it is running.
Open your authenticator app on your mobile device or desktop.
Open a terminal (such as Windows Shell) and SSH into the system using either the host name or IP address, the administrator account user name and password, and the 2FA code.
Developer Mode (Unsupported)
Developer mode is for developers only.
Users that enable this functionality will not receive support on any issues submitted to iXsystems.
Only enable when you are comfortable with debugging and resolving all issues encountered on the system.
Never enable it on a system that has production storage and workloads.
TrueNAS is an Open Source Storage appliance, not a standard Linux operating system (OS) that allows customization of the OS environment.
By default, the root/boot filesystem and tools such as apt are disabled to prevent accidental misconfiguration that renders the system inoperable or puts stored data at risk.
However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.
Do not make system changes using the TrueNAS UI web shell.
Using package management tools in the web shell can result in middleware changes that render the system inaccessible.
Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.
To enable developer mode, log into the system as the root account and access the Linux shell.
Run the install-dev-tools command.
Running install-dev-tools removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS.
These changes do not persist across updates and install-dev-tools must be re-run after every system update.
Troubleshooting
install-dev-tools is a developer-focused option that might not work in scenarios beyond those intended by TrueNAS developers, such as modified installations or deployments that use non-default settings.
Users with NVIDIA GPU drivers installed cannot enable developer mode while the NVIDIA kernel module is mounted.
Running install-dev-tools in this state results in the following error:
/usr is currently provided by a readonly systemd system extension.
This may occur if nvidia module support is enabled. System extensions
must be disabled prior to disabling rootfs protection.
This happens because the NVIDIA drivers are overlaid onto /usr via systemd-sysext, making it read-only by design.
To resolve the issue, unmerge systemd-sysext, run install-dev-tools, then merge system extensions again.
Boot Pool Management
The Boot Environment screen has options that monitor and manage the ZFS boot pool and devices that store the TrueNAS operating system.
Changing the Scrub Interval
The Stats/Settings option shows current system statistics. It also allows you to change the scrub interval or how often the system runs a data integrity check on the operating system device.
Go to the System > Boot Environment screen and click Stats/Settings.
The Stats/Settings window shows statistics for the operating system device: Boot Pool Condition as Online or Offline, Size in GiB, the consumed space in Used, and Last Scrub Run with the date and time of the most recent scrub task.
By default, the operating system device is scrubbed every seven days.
To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.
Boot Pool Device Management
From the Boot Environment screen, click Boot Pool Status to open the Boot Pool Status screen.
This screen shows the boot-pool. Expand it to show the devices allocated to that pool.
Read, write, or checksum errors show for the pool.
TrueNAS supports a ZFS feature known as boot environments.
These are snapshot clones of the TrueNAS boot-pool install location that TrueNAS boots into.
Only one boot environment is used for booting at a time.
A boot environment allows restarting the system to a specific point in time and greatly simplifies recovering from system misconfigurations or other potential system failures.
With multiple boot environments, updating the operating system becomes a low-risk operation.
For example, the TrueNAS update process automatically creates a snapshot of the current boot environment and adds it to the boot menu before applying the update.
If anything goes wrong during the update, the system administrator can activate the snapshot of the pre-update environment and restart TrueNAS to restore system functionality.
Boot environments do not preserve or restore the state of any attached storage pools or apps, only the system boot-pool.
Storage backups must be handled through the ZFS snapshot feature or other backup options.
TrueNAS applications also use separate upgrade and container image management methods to provide app update and rollback features.
To view the list of boot environments on the system, go to System > Boot.
Each boot environment entry contains this information:
Name: the name of the boot entry as it appears in the boot menu.
Active: indicates which entry boots by default if a boot environment is not active.
Date Created: indicates the boot environment creation date and time.
Space: shows boot environment size.
Keep: indicates whether or not TrueNAS deletes this boot environment when a system update does not have enough space to proceed.
Use the icons row to take different actions for a boot environment.
Following Best Practices
Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but not all state changes made in an environment appear in another.
Changes made in a new boot environment do not subsequently appear in older environments of earlier releases. Similarly, changes made while booted into a previous environment do not automatically appear in the upgraded boot environment.
The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information.
We recommend only reverting to an earlier boot environment when a pool upgrade in the new version introduces a problem, or to recover from a broken configuration if the system console or IPMI is unavailable.
Activating a Boot Environment
The option to activate a boot environment only displays for boot entries not set to Active
Activating an environment means the system boots into the point of time saved in that environment the next time it is started.
Click the Activate (Activate) icon for an inactive boot environment to open the Activate dialog.
The System Boot screen status changes to Reboot and the current Active entry changes from Now/Reboot to Now, indicating that it is the current boot environment but it is not used on the next system restart (boot operation).
Activating and booting into an older environment restores only that environment state. Any changes made there do not carry forward into newer environments.
Cloning a Boot Environment
Cloning copies the selected boot environment into a new inactive boot environment that preserves the boot-pool state at the clone-creation time.
Click the Clone (Clone) icon to open the Clone Boot Environment window.
Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
The Source field displays the boot environment you are cloning. If the displayed name is incorrect, close the window and select the correct boot environment to clone.
Click Save.
Deleting a Boot Environment
Deleting a boot environment removes it from the ** Boot Environment** screen and the boot menu.
Click on the Delete (Delete) icon for a boot environment to open the Delete dialog.
Select Confirm and then click Delete.
You cannot delete the default or any active entries.
Because you cannot delete an activated boot entry, this option does not show for activated boot environments.
To delete the active boot environment, first, activate another entry and then delete the environment you want to remove.
Keeping a Boot Environment
By default, TrueNAS prunes boot environments when the boot pool runs out of remaining storage space.
Keep toggles with the Unkeep option, and they determine whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.
Click the Keep (Keep) icon for a boot environment to open the Keep dialog.
Select Confirm and then click Keep Flag.
This makes the boot environment subject to automatic deletion if the TrueNAS updater needs space for an update.
Recovering a Boot Pool
When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and restore your system configuration. This process involves a complete system rebuild while preserving your data pools and configuration settings.
Recovery Steps
Replace the failed boot drive - Install a new drive to serve as the boot device.
Perform a clean TrueNAS installation - Follow the standard installation procedure to install TrueNAS on the new boot drive.
Upload your configuration file - Use your previously saved configuration backup to restore system settings:
Go to System > General > Manage Configuration
Click Upload Config and select your configuration backup file
Follow the prompts to restore your settings
Import existing data pools - Your data pools should be automatically detected and imported after the configuration restore. If not:
Go to Storage > Import Pool
Select your existing pools and import them
Important Considerations
By default, TrueNAS creates a new boot environment when you update or reinstall the system, but if you revert to an earlier environment and make changes, those changes do not carry into the newer environment. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists.
Keep external backups - Always maintain current configuration backups stored outside the TrueNAS system
Regular backup schedule - Export configuration files regularly, especially after making system changes
Data pools preserved - This process only affects the boot pool - your data pools and their contents remain intact
Boot environments lost - All boot environments are lost and must be recreated after recovery
After Recovery
After completing the recovery:
Verify all pools are imported and healthy
Check that sharing services are working correctly
Recreate any custom boot environments as needed
Update your configuration backup to reflect the new system state
Services
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact TrueNAS Enterprise Support to receive additional guidance on system configuration.
Contacting Support
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services.
The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
System > Services displays each system component that runs continuously in the background. These typically control data-sharing or other external access to the system. Individual services have configuration screens, activation buttons, and you can set them to run automatically.
Documented services related to data sharing or automated tasks are in their respective Shares and Tasks articles.
Contents
FTP: Provides instructions on configuring the FTP service including storage, user, and access permissions.
NFS: Provides information on configuring NFS service in TrueNAS.
SMB: Provides instructions on configuring the SMB service in TrueNAS.
SNMP: Provides information on configuring SNMP service in TrueNAS.
SSH: Provides information on configuring the SSH service in TrueNAS and using an SFTP connection.
UPS: Provides information on configuring UPS service in TrueNAS.
FTP
The File Transfer Protocol (FTP) is a simple option for data transfers.
SSH provides secure transfer methods for critical objects like configuration files, while TFTP provides simple file transfer methods for non-critical files.
Options for configuring FTP, SSH, and TFTP are in System > Services.
Click the edit to configure the related service.
Configuring FTP Service
FTP requires a new dataset and a local user account.
Go to Storage to add a new dataset to use as storage for files.
Next, add a new user. Go to Credentials > Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory.
Add ftp to the Auxiliary Groups field.
You can do this for every user or create a global account for FTP (for example, OurOrgFTPaccnt).
You cannot create multiple accounts utilizing the same dataset as your home directory.
By default, only members of the ftp group can authenticate via FTP.
Add your newly created user to the ftp group, or change this behavior in the FTP service configuration:
Enable Allow Local User Login to allow any local user to authenticate
Enable Allow Anonymous Login to allow anonymous connections without authentication
Dataset permissions are configured separately and control what files authenticated users can access.
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields.
Select Apply User and Apply Group.
Select the Read, Write, and Execute for User, Group, and Other you want to apply.
Click Save.
Configuring Service Settings
To configure FTP, go to System > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
To confine FTP sessions to the home directory of a local user, select chroot.
Authentication Options:
By default, only ftp group members can authenticate (no additional configuration needed)
Enable Allow Local User Login to allow any local user to authenticate without ftp group membership
Enable Allow Anonymous Login to allow anonymous connections without authentication
Do not allow anonymous access unless it is necessary.
Enable TLS when possible (especially when exposing FTP to a WAN).
TLS creates FTPS for better security.
Click Save, then start the FTP service.
Connecting with FTP
Use a browser or FTP client to connect to the TrueNAS FTP share.
The images below show FileZilla, a free option.
The user name and password are those of the local user account on the TrueNAS system.
The default directory is the same as the user home directory.
After connecting, you can create directories and upload or download files.
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
Go to System > Services screen, locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
We recommend using the default NFS settings unless you require specific settings.
Select the IP address from the Bind IP Addresses dropdown list to use a specific static IP address, or leave this field blank for NFS to listen to all available addresses.
By default, TrueNAS dynamically calculates the number of threads the kernel NFS server uses.
To manually enter an optimal number of threads the kernel NFS server uses, clear Calculate number of threads dynamically and enter the number of threads you want in the Specify number of threads manually field.
If using NFSv4, select NFSv4 from Enabled Protocols. NFSv3 ownership model for NFSv4 clears, allowing you to enable or leave it clear.
Selecting NFSv3 ownership model for NFSv4 deactivates the Manage Group Server-side option.
To force NFS shares to fail if the Kerberos ticket is unavailable, select Require Kerberos for NFSv4.
Next, enter a port to bind to in the field that applies:
Enter a port to bind mountd(8) in mountd(8) bind port.
Enter a port to bind rpc.statd(8)in rpc.statd(8) bind port.
Enter a port to bind rpc.lockd(8) in rpc.lockd(8) bind port.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Only select Allow non-root mount if the NFS client requires it to allow serving non-root mount requests.
Select Manage Groups Server-side to allow the server to determine group IDs based on server-side lookups rather than relying solely on the information provided by the NFS client.
This can support more than 16 groups and provide more accurate group memberships.
It is equivalent to setting the --manage-gids flag for rpc.mountd.
This setting assumes group membership is configured correctly on the NFS server.
Changes to local groups or directory service groups take up to 10 minutes to take effect for NFS shares. For immediate effect, reload or restart the NFS service.
Click Save.
Start the NFS service.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
SMB
The Services > SMB screen displays after going to the Shares screen, finding the Windows (SMB) Shares section, and clicking more_vert + Config Service.
Alternatively, you can go to System > Services and click the edit edit icon for the SMB service.
Configuring SMB Service
The SMB Services screen displays setting options to configure TrueNAS SMB settings to fit your use case.
In most cases, you can set the required fields and accept the rest of the setting defaults. If you have specific needs for your use case, click Advanced Options to display more settings.
Enter the name of the TrueNAS host system if not the default displayed in NetBIOS Name. This name is limited to 15 characters and cannot be the Workgroup name.
Enter any alias name or names that do not exceed 15 characters in the NetBIOS Alias field. Separate each alias name with a space between them.
Enter a name that matches the Windows workgroup name in Workgroup. TrueNAS detects and sets the correct workgroup from these services when unconfigured with enabled Active Directory or LDAP active.
NetBIOS names (workgroup, domain, and computer names) are limited to 15 characters and cannot contain the following characters: \ / : * ? " < > |
Microsoft and RFC 852 define reserved words that should not be used as NetBIOS names. TrueNAS 25.04 and later enforce these restrictions through validation.
View complete list of reserved words
The following words cannot be used as NetBIOS names (case-insensitive):
If you encounter validation errors when joining Active Directory or configuring SMB services, verify that your NetBIOS Name, Workgroup, and Domain Name comply with these requirements.
If using SMB1 clients, select Enable SMB1 support to allow legacy SMB1 clients to connect to the server. Note: SMB1 is deprecated. We advise upgrading clients to operating system versions that support modern SMB protocols.
If you plan to use the insecure and vulnerable NTLMv1 encryption, select NTLMv1 Auth to allow smbd attempts to authenticate users.
This setting enables backward compatibility with older versions of Windows, but we do not recommend it. Do not use on untrusted networks.
Enter any notes about the service configuration in Description.
TrueNAS and Samba default behavior for SMB transport encryption allows SMB clients to negotiate different encryption levels for shares.
This default setting enables negotiating encryption but does not turn on data encryption globally per share.
SMB1 and SMB2 provide different settings to change the level of global or per-share SMB encryption applied to connections.
See Samba Server SMB Encrypt(s) for more information.
You can change the SMB service to apply different SMB transport encryption levels to suit your use case.
Go to the SMB service, found on the System > Services screen, and click Edit for the SMB service to open the SMB Service screen, then click on Advanced Settings.
Click in the Transport Encryption Behavior field to select the option and behavior you want applied:
Default - follow upstream/TrueNAS default
Negotiate - only encrypt transport if explicitly requested by the SMB client
Desired - encrypt transport if supported by client during session negotiation
Required - always encrypt transport (rejecting access if client does not support encryption - incompatible with SMB1 server enable_smb1)
Select the Default option to use the TrueNAS current behavior.
If set to default, there is no technical limitation preventing an SMB client from negotiating an encrypted session if required.
If you are concerned about having Windows SMB clients always using signing in your environment, make a GPO change on the client side to always sign SMB2+ traffic.
This defaults to the Windows settings digitally sign communications (always) and to off.
To monitor SMB service event logs, such as when a client attempts to authenticate to the share, use the TrueNAS auditing screen.
Go to System > Audit to review event logs, including SMB connect, disconnect, create, read or write events, and others.
Enter SMB in the search bar to view only SMB service logs or use the advanced search to further limit results.
Configuring SMB Share Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
SNMP
SNMP (Simple Network Management Protocol) monitors network-attached devices for conditions that warrant administrative attention.
TrueNAS uses Net-SNMP to provide SNMP.
To configure SNMP, go to System > Services page, find SNMP, and click the edit.
To download an MIB from your TrueNAS system, you can enable SSH and use a file transfer command like scp.
When using SSH, make sure to validate the user logging in has SSH login permissions enabled and the SSH service is active and using a known port (22 is default).
Management Information Base (MIB) files are located in /usr/local/share/snmp/mibs/.
Example (replace mytruenas.example.com with your system IP address or hostname):
Allowing external connections to TrueNAS is a security vulnerability!
Do not enable SSH unless you require external connections.
See Security Recommendations for more security considerations when using SSH.
Configuring SSH Service
To configure SSH go to System > Services, find SSH, and click edit to open the basic settings General Options configuration screen.
Use the Password Login Groups and Allow Password Authentication settings to allow specific TrueNAS account groups the ability to use password authentication for SSH logins.
Click Save. Select Start Automatically and enable the SSH service.
Configuring Advanced SSH Settings
If your configuration requires more advanced settings, click Advanced Settings.
The basic options continue to display above the Advanced Settings screen.
Configure the options as needed to match your network environment.
Select specific network interfaces from Bind Interfaces for SSH to listen on, or deselect all options to have SSH listen on all interfaces (default).
Select Compress Connections to reduce latency over slow networks.
Configure SFTP logging by selecting the appropriate SFTP Log Level and SFTP Log Facility.
Select additional cipher options in Weak Ciphers if needed.
None allows unencrypted SSH connections while AES128-CBC allows the 128-bit Advanced Encryption Standard cipher.
These ciphers are security vulnerabilities and should only be used in secure network environments.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
Add sshd_config options not covered by other settings in Auxiliary Parameters.
Enter one option per line.
Parameters are case-sensitive.
SSH auxiliary parameters are unsupported.
Certain configurations can prevent the SSH service from starting.
Remember to enable the SSH service in System > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account.
See Adding SSH Credentials for more information.
Using SSH File Transfer Protocol (SFTP)
SFTP (SSH File Transfer Protocol) is available by enabling SSH remote access to the TrueNAS system.
SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.
Go to System > Services, find the SSH entry, and click the edit to open the Services > SSH basic settings configuration screen.
Go to Credentials > Users. Click anywhere on the row of the user you want to access SSH to expand the user entry, then click Edit to open the Edit User configuration screen. Make sure that SSH password login enabled is selected. See Managing Users for more information.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
SSH with root is a security vulnerability. It allows users to fully control the NAS remotely with a terminal instead of providing SFTP transfer access.
Choose a non-root administrative user to allow SSH access.
Review the remaining options and configure them according to your environment or security needs.
Remember to enable the SSH service in System > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
TrueNAS shows an error if users activate Global 2FA (Two-Factor Authentication) and attempt to enable password-based SSH authentication without a 2FA token. See Managing Global 2FA for more information.
Using SFTP Connections
Open an FTP client (like FileZilla) or command line.
This article shows using FileZilla as an example.
Using FileZilla, enter SFTP://{TrueNAS IP} {username} {password} {port 22}. Where {TrueNAS IP} is the IP address for your TrueNAS system, {username} is the administrator login user name, and {password} is the administrator password, and {port 22} to connect.
SFTP does not offer chroot locking.
While chroot is not 100% secure, lacking chroot lets users move up to the root directory and view internal system information.
If this level of access is a concern, FTP with TLS might be the more secure choice.
UPS
An Uninterruptible Power Supply (UPS) is a power backup system that ensures continuous electricity during outages, preventing downtime and damage.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support.
For supported device and driver information, see their hardware compatibility list.
Further device-specific compatibility information is available from the NUT Devices Dumps Library.
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
Some UPS models are unresponsive with the default polling frequency (default is two seconds).
TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.
Auxiliary parameters are an unsupported configuration.
Parameters entered here are not validated and can cause undefined system behavior, including data corruption or data loss.
If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10.How do I find a device name?
For USB devices, the easiest way to determine the correct device name is to enable and view console messages in the TrueNAS UI.
Go to System > General Settings, find the GUI widget, and click Settings.
Select Show Console Messages under Other Options.
Click Save.
Plug in the USB device and look for a /dev/ugen or /dev/uhid device name in the console messages.
Can I attach Multiple Computers to One UPS?
A UPS with adequate capacity can power multiple computers.
One computer connects to the UPS data port with a serial or USB cable.
This primary system makes UPS status available on the network for other computers.
The UPS powers the secondary computers, and they receive UPS status data from the primary system.
See the NUT User Manual and NUT User Manual Pages.
Using Shell
The TrueNAS Shell is convenient for running command line tools, configuring different system settings, or finding log files and debug information.
Warning! The supported mechanisms for making configuration changes are the TrueNAS WebUI and API exclusively.
All other are not supported and result in undefined behavior that can result in system failure!
The Font Sizeremove and add buttons adjust the displayed text size in the Shell.
The shell window stores the command history for the current session.
Leaving the Shell screen clears the command history.
Navigating In Shell
This section provides keyboard navigation shortcuts you can use in Shell.
Action
Keyboard/Command
Description
Scroll up
Up arrow expand_less
Scroll up through previous commands.
Scroll down
Down arrow expand_more
Scroll down through following commands.
Top of screen
Home
Moves the cursor to the top of the screen when viewing entries and results.
Bottom of screen
End
Moves the cursor to the bottom of the screen command when viewing entries and results.
Delete
Delete
Deletes highlighted text.
Auto-fill text
Tab
Type a few letters and press Tab to complete a command name or filename in the current directory.
right-click
Right-clicking in the terminal window opens the browser default right click menu, which allows you to use native copy and paste functions.
Exit to root prompt
exit
Entering exit leaves the session.
Copy text
Ctrl+Insert
Enter Ctrl+Insert to copy highlighted text in Shell.
Paste text
Shift+Insert
Enter Shift+Insert to paste copied text in Shell.
Kill running process
Ctrl+c
Enter Ctrl+c to kill a process running in Shell. For example, the ping command.
Changing the Default Shell
zsh is the default shell, but you can change this by going to Credentials > Users.
Select the admin or other user to expand it.
Click Edit to open the Edit User screen.
Scroll down to Shell and select a different option from the dropdown list.
Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh.
Click Save.
Admin users can set the Shell to default to the TrueNAS Console by selecting TrueNAS Console in Shell on the Edit User screen.
Clicking other TrueNAS UI menu options closes the shell session and stops commands running in the Shell screen.
Tmux allows you to detach sessions in Shell and then reattach them later.
Commands continue to run in a detached session.
Audit Logs
TrueNAS auditing and logs provide a trail of all actions performed by a session, user, or service (SMB, middleware).
The audit function backends are the syslog and Samba debug libraries.
Syslog sends audit messages via an explicit syslog call with configurable priority (WARNING is the default) and facility (for example, USER).
The default is syslog-sent audit messages.
Debug sends audit messages from the Samba debug library. Messages have a configurable severity (WARNING, NOTICE, or INFO).
The System > Audit screen lists all session or user events, facilitating comprehensive monitoring.
Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).
Audit logs retain at least one week of data. Logs are downloadable.
Auditing event types are:
Session and user
Sudo and root user commands (includes STIG-compliant shell commands)
SMB protocol and share
iSCSI protocol and share
FTP service
STIG-compliant security objects
HA shutdown and restart reason
Enterprise and Enterprise HA systems have security object (FIPS and STIG) event logging.
HA primary and standby controller event logs are downloadable from either the primary or the standby controller.
Session and User Auditing Events
Session and user auditing events include authentication, method call, and sudo accept/reject events.
Authentication Events
Audit messages are generated every time a client logs into the TrueNAS UI or an SSH session or makes changes to user credentials.
TrueNAS terminates inactive sessions when it reaches the specified timeout limit. If a user initiates a new session within five minutes of the last session, TrueNAS logs the user as associated with the previous session. If the log-in occurs outside the five minutes, TrueNAS initiates a new websocket session.
Method Call Events
Audit messages are generated every time a currently logged-in user creates a new user account or changes user credentials.Sudo Accept or Reject Events
Generated every time a user logs into a shell session and uses sudo to perform a command as root, or is denied sudo permission.
The event data for a sudo event includes the command.
SMB Auditing Events
SMB events are omitted by default from the System > Audit screen.
To view these audit results, go to System > Services and click receipt_longAudit Logs for the SMB service or use the Service dropdown on the main Audit screen to select SMB.
SMB audit logs include all SMB protocol events, but do not include changes to SMB configuration, such as creating an SMB share or querying and modifying SMB ACLs.
See the middleware service log to review those events.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List configuration.
Watch and ignore lists control subsequent SMB operations (connect, create, write, read, etc.) but do not filter authentication events.
This ensures a complete audit trail of all authentication attempts for security and compliance purposes.
Connect Events
Generated every time an SMB client performs an SMB tree connection (TCON) to a given share.
Each session can have zero or more TCONs.Disconnect Events
Generated every time an SMB client performs an SMB tree disconnect to a given share.Create Events
Generated every time an SMB client performs an SMB create operation on a given tree connection (TCON).
Does not log internally-initiated create operations.
Each SMB tree connection can have multiple open files.Read or Write Events
Generated 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.
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.
Open or Close Events
Generated every time an SMB client opens or closes a file.
When a file is opened or closed, a summary of file system operations performed on the type is included in the audit message.Rename Events
Generated when a client attempts to rename a file.Set_Attr Events
Generated when a client attempts to set basic file attributes (for example, DOS mode or file timestamps).
The key attr_type indicates the precise type of attributes changed in the event this message records.Set_Quota Events
Generated when a client attempts to set basic file attributes (for example, DOS mode or file timestamps).
The key attr_type indicates the precise type of attributes changed in the event this message records.Unlink Events
Generated when a client attempts to delete a file or directory from a share.Set_ACL Events
Generated when a client attempts to set an NFSv4 ACL on a file system or to grant a user (OWNER) read and write permissions to the file system.
Audit Message Records
Audit records contain information that establishes:
Type of event
When the event occurred (timestamp)
Where the event occurred (source and destination addresses)
Source of the event (user or process)
Outcome of the event (success or failure)
Identity of any individual or file names associated with the event
Each audit message is a single JSON file containing mandatory fields.
It can also include additional optional records.
Message size is limited to not exceeding 1024 bytes for maximum portability with different syslog implementations.
Use the Export button on an audit screen to download audit logs in CSV, JSON, or YAML format. CSV format is readable in spreadsheet programs.
Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file.
The JSON object for an audit message contains the version information, the service that might be the name of the SMB share, a session ID, and the tree connection (tcon_id).
Message Fields
Each audit message JSON object includes:
Field
Description
aid
GUID uniquely identifying the audit event.
vers
JSON object containing version information of the audit event. Audit version identifiers represent the major and minor versions of the internal TrueNAS audit message. Major versions are not made outside a major TrueNAS release. Minor version changes indicate non-breaking changes to the format, such as adding a new optional field. Major version changes that can be renaming or removing an existing mandatory field.
time
UTC timestamp indicating when the event occurs.
addr
IPv4 or IPv6 address for the client generating the audit message.
user
Username of the user or client generating the audit message. If no username, it can be the user ID prefixed with UID.
svc
Unique human-readable service identifier (all uppercase alpha characters) for the TrueNAS service generating the audit message (always SMB).
event
Human-readable name for the event type for the audit message. Name is in all uppercase alpha characters that can include the underscore (_) or dot (.) special characters. See Audit Event Types above for more information.
svc_data
A JSON object containing tree connection (TCON) specific data. This is standardized for all events.
event_data
A JSON object containing event-specific data. This varies based on the event type.
sess
GUID unique identifier for the session.
success
Shows true if the operation succeeds or false if it fails.
Accessing Auditing Screens
Users have access to audit information from three locations in the TrueNAS UI:
Credentials > Users details screen through the Audit Logs option
* On the Users screen, click Audit Logs on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user. For more details, see Audit Screen.
Shares > Window (SMB) Shares details screen through the share edit Audit Logging option
* On the Sharing screen, click the editEdit icon on the desired SMB share row where Enable, watch and ignore settings are available. For details, see Configuring SMB Auditing.
System > Services > SMB to view SMB audit logs
* On the Services screen, click the receipt_longAudit Logs icon on the SMB row. This opens the main Audit log page with the Search field filter configured to show only SMB events. For details, see Audit Screen.
System > Audit option on the main navigation panel
* The default Audit log screen is unfiltered and displays all system events such as authentication and SMB events.
Use the Service dropdown at the top of the screen to filter audit entries by service type (SMB, Middleware, etc.).
The audit screen includes basic and advanced search options.
Click Switch to Basic to change to the basic search function or click Switch to Advanced to show the advanced search operators.
You can enter any filters in the basic Search field to show events matching the entry.
To enter advanced search parameters, use the format displayed in the field, for example, Event = “CLOSE” to show close events. Use the Service dropdown to filter by service type (SMB, Middleware, etc.) before or after applying advanced search filters.
Event types are listed in Auditing Event Types.
Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering.
Parentheses define query priority.
Clicking the advanced Search field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.
For example, to search for connect or close events from the user smbuser, select SMB from the Service dropdown and enter Event in ("Connect", "Close") AND User = "smbuser" in the advanced search field. To exclude authentication events, enter Event != "Authentication".
The advanced search automatically checks syntax and shows done when the syntax is valid and warning for invalid syntax.
Click on a row to show details of that event in the Metadata and Event Data widgets.
Export provides a dropdown to export event log data in CSV, JSON, or YAML format. CSV files can be opened in spreadsheet programs (i.e., MS Excel, Google Sheets, etc.). JSON and YAML formats are useful for importing into data management applications or automation tools.
The assignment (Copy to Clipboard) icon shows two options, Copy Text and Copy Json.
Copy Text copies the event to a text file.
Copy Json copies the event to a JSON object.
Configuring SMB Auditing
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions.
SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
At least one of Watch List or Ignore List must contain entries when enabling audit logging.
Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
Configure filtering to audit only necessary operations.
TrueNAS 25.10.1 and later automatically disables SMB shares when auditing is enabled and the watch list or ignore list contains invalid groups, such as groups that:
No longer exist (for example, deleted or renamed groups in Active Directory).
Are not SMB groups (groups with SMB Group selected in the group configuration).
TrueNAS generates an alert identifying the affected share and the problematic group.
The share remains disabled until you resolve the group issue or update the share configuration to remove the invalid group.
See Troubleshooting Group Validation Issues for detailed steps.
Configuring Watch and Ignore Lists
Use Watch List to specify which groups should have their SMB operations audited.
To configure the watch list:
Click the Watch List field to display available groups on the system.
Select a group to add it to the list.
Repeat to add additional groups.
When Watch List contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
Use Ignore List to exclude specific groups from auditing.
To configure the ignore list:
Click the Ignore List field to display available groups on the system.
Select a group to exclude it from auditing.
Repeat to exclude additional groups.
TrueNAS does not record SMB operations performed by members of groups in the Ignore List.
When using both lists: If a user is a member of groups in both Watch List and Ignore List, the Watch List takes precedence and TrueNAS audits that user’s operations.
SMB authentication events are logged globally for all users connecting to the SMB server, regardless of Watch List or Ignore List settings.
Watch and ignore lists control subsequent operations (connect, file creates, reads, writes, etc.) but do not filter authentication events.
Users in the Ignore List still have their initial authentication logged, but their file operations on the share are not audited.
Review your settings to verify that at least one list contains entries and the correct groups are selected.
Click Save.
After saving, restart the SMB service for audit logging to begin.
Go to System Settings > Services, toggle the SMB service off then on, and verify the service is running before testing audit log generation.
Troubleshooting Group Validation Issues
If you receive an alert indicating an SMB share has been disabled due to invalid groups in the audit configuration, follow these steps:
Identify the problem:
Review the alert message to identify which share is affected and which group is invalid.
Check group status:
Navigate to Credentials > Local Groups to verify the group exists and is configured as an SMB group.
For Active Directory groups, verify the group exists in AD and the directory service connection is functioning.
Confirm the group type is set to SMB (not changed from SMB to another type).
Resolve the issue:
If the group was deleted or renamed: Navigate to Shares > Windows (SMB) Shares, edit the affected share, and update the Watch List or Ignore List to remove the invalid group or replace it with the correct group name.
If the group exists but is not an SMB group: Edit the group in Credentials > Local Groups and select the SMB Group option, or update the share audit configuration to use a different group.
If using Active Directory: Verify the Active Directory connection is active in Credentials > Directory Services. If the connection was temporarily offline, restarting the SMB service might re-enable the share once the connection is restored.
Restart the SMB service:
After correcting the group configuration or share settings, go to System > Services and restart the SMB service to re-enable the share.
Verify the share is functioning by checking the alert has cleared and testing access from an SMB client.
Configuring Audit Storage and Retention Policies
To configure Audit storage and retention settings, click Audit Settings on the Audit screen or go to System > Advanced Settings, then click Configure on the Audit widget.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
For example, to change the percent usage warning threshold for the storage allocated to the Audit database:
Navigate to System > Advanced screen.
Select the Configure button on the Audit widget.
In the Audit configuration popup, change the value in the Quota Fill Warning field to the desired percentage.
Remove this port from the subsystem icon on the Ports widget.
icon to open the feedback window.
The window allows you to select the Report a bug option to open a Jira ticket.
