Documents each screen and field available in the SCALE interface. Articles are organized parallel to the SCALE interface layout.
Welcome to the TrueNAS SCALE UI Reference Guide!
This document shows and describes each screen and configurable option contained within the TrueNAS web interface.
The document is arranged in a parallel manner to the TrueNAS web interface, beginning with the top panel and then descending through each option displayed in the web interface left side menu.
To display this document in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
SCALE UI Reference Guide Sections
⎙ Download or Print: View the TrueNAS SCALE UI Reference Guide as a single page for download or print.
Top Toolbar: All the icons and options contained in the TrueNAS SCALE top toolbar.
Settings Options: Describes the top-level Settings options in TrueNAS SCALE.
Tasks Screens: Describes the TrueNAS SCALE task manager and how to use the task manager to view failed jobs and task logs.
Dashboard: Explains the main dashboard information cards (widgets) and provides basic information on synchronizing the system and SCALE server times, and on customizing the Dashboard display.
Storage: Provides information on the Storage Dashboard widgets and options for pools, devices, and disks listed on this screen.
Disks: Describes UI screens and dialogs related to disk operations.
Pool Creation Wizard: Descriptions for settings and functions found in the Pool Creation Wizard.
Devices: Provides information on settings and functions found on the Devices screens and widget.
Datasets: Provides information on the Datasets screens and settings.
Zvols: Provides information on the settings and functions found on the Zvol screens and widgets.
Capacity Settings: Provides information on the quota settings and functions found on the Capacity Settings screen.
Snapshots: Provides information on the settings and functions found on the Snapshots screen.
User and Group Quotas : Provides information on the settings and functions found on the User and Group Quota screens.
Encryption Settings: Provides information on the settings and functions found on the SCALE storage encryption screens.
Permissions: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.
Shares: Describes the various storage sharing screens in TrueNAS SCALE.
SMB Shares Screens: Provides information on SMB share screens and settings.
NFS Shares Screens: Provides information on NFS Shares screens and settings.
Replication Task Screens: Provides information on the Replication screens, wizard, and settings used to add or edit replication tasks.
Network: Describes the screens and fields in the TrueNAS SCALE Network section.
Network Interface Screens: Provides information on the Network screen Interfaces widget and configuration screens.
Global Configuration Screens: The Global Configuration widget displays the general TrueNAS network settings not specific to any interface.
Static Routes Widget: The Static Routes widget displays existing static routes or sets up new ones.
IPMI Screens: Provides information on the Network screen IPMI widget and configuration screen.
Credentials: Describes the screens and fields in the TrueNAS SCALE Credentials section.
Users Screens: Provides information on the Users screens and settings and information on settings for the TrueNAS SCALE Shell screen.
Groups Screens: Provides information on the Groups screens and settings.
Directory Services Screens: Describes the screens and fields in the TrueNAS SCALE Directory Services section.
Backup Credentials: Information on backup credential screens and settings to integrate TrueNAS SCALE with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about the Certificates screen and widgets.
KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS SCALE Enterprise.
Virtualization: Provides information on the screens and settings to add virtual machines (VMs) and devices to your TrueNAS SCALE system.
Apps: Articles describing the TrueNAS Apps screens and fields.
Custom App Screens: Provides information on the Install Custom App screen and configuration settings.
Reporting: Provides information on TrueNAS SCALE reporting graph screens and settings.
System Settings: Articles describing the various screens and fields contained within the TrueNAS SCALE System Settings section.
Update Screens: Provides information on functions and fields on the TrueNAS SCALE Update screens.
General Settings Screen: Provides information on General system setting screen, widgets, and settings for getting support, changing console or the GUI, localization and keyboard setups, and adding NTP servers.
Advanced Settings Screen: Provides information on the System Settings > Advanced screen, widgets, and configuration screen settings.
Boot: Provides reference descriptions of the boot environment screens and settings.
Failover Screen: Provides information on the Failover screen settings and functions.
Services: Information on the Services screen and individual service articles in the Services area.
Shell Screen: Provides information on the TrueNAS SCALE Shell screen, buttons, and slider.
Alert Settings Screen: Provides information on Alert Settings service screen settings.
The top toolbar icon buttons provide access to the iXsystems website, displays the status of TrueCommand and directory services configured on your system, and displays other configuration menu options.
Click to expand or collapse the main menu panel on the left side of the screen.
Search UI
Searches UI screens and elements or redirects queries to the TrueNAS Documentation Hub.
iXsystems
Opens the iXsystems home page website where users can find information about storage and server systems. Users can also use the iXsystems home page to access their customer portal and community section for support.
Send Feedback
Opens the Send Feedback feedback window for sending UI ratings and bug reports to the TrueNAS developers.
Shows the system update progress and which user account started the update. Only appears in the top bar when a TrueNAS system update starts.
info
Directory Services status
Displays a dialog with the status of Active Directory and LDAP directory servers configured on the system.
assignment
Jobs
Displays the Jobs dialog. Click the History button to display the Tasks screen with a list of All, Active or Failed tasks or processes.
notifications
Alerts
Displays a list of system alerts and a dropdown list with the alert options Alert Settings and Email.
account_circle
Settings
Displays a dropdown list of setting options Change Password, Two-Factor Authentication, API Keys, Guide, About, and Log Out.
power_settings_new
Power options
Displays the power related options Restart or Shut Down.
Search UI
The Search UI global search bar allows users to search for screens and elements within the TrueNAS SCALE UI or to redirect search terms to the TrueNAS Documentation Hub.
Using Global Search
Searching UI Fields
Click the Search UI bar or type Ctrl + / to select the UI global search.
Global search returns UI screens, widgets, and button names matching the entered query.
Click View More to view additional results, if needed.
Navigating Results
Select a screen result under UI to go to the matching screen within the TrueNAS UI.
For example, select Shares arrow_right_alt SMB to go to the SMB screen.
Select a widget or button result to go to the screen containing the element.
For example, select Shares arrow_right_alt SMB arrow_right_alt Add SMB Share to locate to the Add button on the SMB screen.
TrueNAS SCALE indicates the selected element with a glowing blue outline.
Searching TrueNAS Documentation
Click Search Documentation for «query» to redirect the search to the TrueNAS Documentation Hub.
TrueNAS SCALE opens a new browser tab to display documentation search results for the query.
Use this option to search for tutorials and UI reference documentation for the feature, or to look for further information when the entered search term does not find any matching UI elements.
Send Feedback
The Send Feedback icon opens a feedback window.
Alternately, go to System > General, find the Support widget, and click File Ticket to see the feedback window.
The feedback window allows users to send page ratings, comments, vote for new features on the community forum, report issues, or suggest improvements directly to the TrueNAS development team.
Submitting a bug report requires a free Atlassian account.
Click between the tabs at the top of the window to see options for your specific feedback.
Rate this page
Use the Rate this page tab to quickly review and provide comments on the currently active TrueNAS user interface screen.
You can include a screenshot of the current page and/or upload additional images with your comments.Report a bug
Use the Report a bug tab to notify the development team when a TrueNAS screen or feature is not working as intended.
For example, report a bug when a middleware error and traceback appears while saving a configuration change.
Enter a descriptive summary in the Subject.
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.
Enter details about the issue in the Message.
Keep the details concise and focused on how to reproduce the issue, what the expected result of the action is, and what the actual result of the action was.
This helps ensure a speedy ticket resolution.
Include system debug and screenshot files to also speed up the issue resolution.
Bug Reports from Enterprise Licensed Systems
TrueNAS Enterprise
When an Enterprise license is applied to the system, the Report a bug tab has additional environment and contact information fields for sending bug reports directly to iXsystems.
Click on History to open the Tasks screen with lists of all successful, active, and failed 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 SCALE Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Settings
The account_circleSettings icon button displays a menu of general system settings options.
The options are Change Password, Two-Factor Authentication, Preferences, API Keys, Guide and About.
The dialpadChange Password icon button displays a dialog where you can change the login password for the currently logged-in administrator password.
The laptopAPI Keys icon button displays the API Keys screen that lists current API keys and where you can add or manage API keys that identify outside resources and applications without a principal.
The library_booksGuide icon button opens the TrueNAS Documentation Hub website in a new browser tab.
The infoAbout icon button displays a window with links to the TrueNAS Documentation Hub, the TrueNAS Community Forums, the FreeNAS Open Source Storage Appliance GitHub repository, and the iXsystems home page. Use the Close button to close the window.
Tasks Screens: Describes the TrueNAS SCALE task manager and how to use the task manager to view failed jobs and task logs.
Alerts
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the SCALE Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
Contents
Alert Settings Screens: The Alert Settings screen allows users to set the warning levels and frequency of alerts.
Email Screens: Provides information on the email configuration screens for SMTP and GMail OAuth.
Alert Settings Screens
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies.
To access this screen, click the notifications icon, then click the settings icon and select Alert Settings on the dropdown list.
Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
Add/Edit Alert Service Screen
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default.
To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the more_vert icon for the service, and then click Edit to display the Edit Alert Service screen.
Name and Type Settings
Setting
Description
Name
Enter a name for the new alert service.
Enabled
Clear the checkmark to disable this service without deleting it.
Type
Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS.
Level
Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. TrueNAS SCALE sends alert notifications for all warnings matching and above the selected level. For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Alert Service Types
AWS SNS
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
Authentication Settings
Setting
Description
API Key
Enter the API key. Find the API key by signing into the OpsGenie web interface and going to Integrations/Configured Integrations. Click the desired integration, Settings, and read the API Key field.
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
Authentication Settings
Setting
Description
Hostname
Enter the hostname or IP address of the system to receive SNMP trap notifications.
Port
Enter the UDP port number on the system receiving SNMP trap notifications. The default is 162.
SNMPv3 Security Model
Select to enable the SNMPv3 security model.
SNMP Community
Enter the network community string. The community string acts like a user ID or password. A user with the correct community string can access network information. The default is public. For more information, see What is an SNMP Community String?.
Telegram
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Enter a list of chat IDs separated by a space ( ), comma (,), or semicolon (;). To find your chat ID, send a message to the bot, group, or channel and visit https://core.telegram.org/bots/api#getting-updates.
VictorOPS
Click here for more information
Select VictorOps from the Type dropdown list to display VictorOps authentication settings.
Use the Category dropdown list to display alert settings for each category.
Applications
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Click here for more information
You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.
Certificates
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Click here for more information
You can customize alert settings for when a certificate expires, a certificate parsing fails, a certificate revokes, and the web UI HTTPS certificate setup fails.
Directory Service
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
Click here for more information
You can customize alert settings for when the Active Directory bind is unhealthy, Active Directory domain validation fails, the domain is offline, and the LDAP bind bind is unhealthy.
High Availability Settings
TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only displays on the list of alerts for dual-controller High-Availability systems with an Enterprise license applied.
Click here for more information
You can customize alert settings for when an automatic sync to peer fails, disks are missing on the active and/or standby controller, the system fails to check failover status with the other controller, syncing operations fail such as encryption keys to peer and KMIP keys to peer, the failover interface is not found, and when a failover action fails.
Hardware
Hardware alert settings apply to the IPMI network connections, and S.M.A.R.T. and smartd that monitors the hard drives installed on your TrueNAS system.
Click here for more information
You can customize alert settings for when disk(s) format with the data integrity feature, IPMI has system events, the IPMI system event log space is low, S.M.A.R.T. has an error, and smartd is not running.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Key Management Interoperability Protocol (KMIP)
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Click here for more information
You can customize alert settings for when the system fails to communicate, sync the SED global password, and sync keys with the KMIP server.
Plugins
Plugins alert settings apply to plugins installed on your TrueNAS.
Click here for more information
You can customize the alert setting for when plugin updates are available.
Network
Network alert settings apply to network interfaces configured on your TrueNAS.
Click here for more information
You can customize alert settings for when ports are not active on the LAGG interface and when the LAGG interface has no active ports.
Reporting
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Click here for more information
You can customize alert settings for when netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.
Sharing
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Click here for more information
You can customize alert settings for when a deprecated service is running, IP addresses bound to an iSCSI portal are not found, NFS services cannot bind to specific IP addresses using 0.0.0.0, and the system cannot resolve NFS share references hosts.
You can also customize alerts for when NTLMv1 attempts authentication in the last 24 hours, SMB1 connections to TrueNAS server are performed in the last 24 hours, and a share is unavailable because it uses a locked dataset.
Storage
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
Click here for more information
You can customize alert settings for when a dataset exceeds standard and critical quotas, a pool has new available feature flags, pool space usage exceeds 70, 80, or 90 percent, and pool status is not healthy.
You can change alert settings for when a pool consumes USB disks, a scrub pauses, and too many snapshots exist.
System
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system reboots, updates, and the web interface.
Click here for more information
You can customize alert settings for when the admin user is overridden, the boot pool is unhealthy, the system dataset has core files, a device slows down pool I/O, NTP health checks fail, and TrueCommand API keys are disabled or need confirmation.
You can also change alert settings for when SSH logins fail, the system is not ready for Kdump, the web UI cannot bind to a configured address, TrueCommand fails health checks, the system reboots off schedule, and update are available, failed, or not applied.
Tasks
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
Click here for more information
You can customize alert settings for when cloud sync tasks, VMWare snapshot creation, login, and deletion, replication, rsync tasks, scrubs, and snapshot tasks fail in general or due to locked datasets.
You can also change alert settings for when replication, rsync tasks, and scrubs succeed.
UPS
UPS alert settings apply to a UPS connected to your TrueNAS.
Click here for more information
You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.
Alert Warning Levels
Use the Set Warning Level dropdown list to customize alert importance.
Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
TrueNAS SCALE sends alert notifications for all warnings matching and above the selected level
For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Level
Icon
Alert Notification?
INFO
No
NOTICE
Yes
WARNING
Yes
ERROR
Yes
CRITICAL
Yes
ALERT
Yes
EMERGENCY
Yes
Alert Frequency
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
Email Screens
The top toolbar Alertsnotifications icon button and settings icon display the Alerts dropdown list with two options: Alert Settings and Email.
Select Email to go to the General settings screen and find the Email widget.
Email Widget
The Email widget on the General Settings screen displays information about current system mail settings.
Settings opens the Email Options screen that allows users to configure the system email send method.
Email Options Screen
An automatic script sends a nightly email to the administrator account containing important information such as the health of the disks.
Users must first configure an email address for the admin account or another administrative user in Credentials > Users.
The Email Options screen offers two options to set up email.
Select either SMTP or GMail OAuth.
The configuration settings change based on the selected radio button.
SMTP
If SMTP is selected, the screen displays the SMTP configuration fields.
The name to show in front of the sending email address, for example: TrueNAS.
Outgoing Mail Server
Host name or IP address of SMTP server to use for sending emails.
Mail Server Port
SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).
Security
Select the security option from the dropdown list. Options are Plain (No Encryption), SSL (Implicit TLS), or TLS (STARTTLS). See email encryption for more information on types.
SMTP Authentication
Select to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password.
Username
Displays after selecting SMTP Authentication. The user name for the sending email account, typically the full email address.
Password
Displays after selecting SMTP Authentication. The password for the sending email account.
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
Gmail OAuth
If GMail OAuth is selected, the screen displays Log in to Gmail to set up Oauth Credentials and the Log In To Gmail button.
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
Settings Options
The account_circleSettings icon button displays a menu of general system settings options.
The options are Change Password, Preferences, API Keys, Guide and About.
Change Password
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
The truenas_admin user and admin users with full control permissions see the Change Password dialog with the New Password and Confirm Password fields.
These users do not need to enter their current password to change the password.
Sharing Admin and Readonly Admin users see the Change Password dialog with the Current Password, New Password, and Confirm Password fields.
These users must enter the current password to validate the user account before changing the password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
API Keys
Click on laptopAPI Keys to display the API Keys screen where you can add new or manage existing API keys on your system.
Guide
Click on library_booksGuide to display the TrueNAS Documentation Hub in a new tab.
About
Click on About to display the information window links to the TrueNAS Documentation Hub, TrueNAS Community Forums, FreeNAS Open Source Storage Appliance GitHub repository, and iXsystems home page.
Contents
API Keys Screen: Describes how the API keys screen in TrueNAS SCALE.
The API Keys option on the top toolbar Settings dropdown menu displays the API Keys screen.
This screen displays a list of TrueNAS SCALE API keys on your system and allows you to add, edit, or delete keys.
Click the icon to the right of an API key to display options for that key. API key options are Edit and Delete.
Use Add to add a new API key to your TrueNAS.
Always back up and secure keys. The key string displays only one time, at creation!
API Key Documentation
Click API Docs to access API documentation for your system.
Two-Factor Authentication Screen
Two-factor authentication is time-based and requires a correct system time setting.
The Two-Factor Authentication screen, accessed from the Settings menu on the top toolbar, allows managing user-level two-factor authentication (2FA) credentials. It shows a different message if 2FA enabled than when not configured or disabled.
The Tasks screens, accessed from the Jobs list after clicking History, displays all jobs executed on the system.
There are three tab views, All, Active and Failed. All displays by default.
Use the arrow display options to change the number of jobs per screen. Options are the default 10, 50 or 100.
Click View to display the argument passed for the selected job.
Use the north arrow beside the State or ID header to change the display order, or the south arrow to return to the top down display order.
Failed Jobs Screen
The Failed screen displays the list of failed jobs.
Use the View button to display the task log. The system error for this failed job displays at the bottom of the log file.
Certain jobs, such as debugs, cannot be aborted after they start. Advanced users can use the API to abort such job; however, this is not generally recommended.
In the majority of instances, it is more reliable to wait for the job to finish without interference.
Dashboard
The Dashboard is the first screen you see after logging into the web interface after installing SCALE.
It displays a set of default widgets with system, help, storage, and network information, but you can customize the display to suit your needs and preferences.
Dashboard on the left side navigation panel returns to the main dashboard from any other screen in the UI.
The Configure button at the top right of the Dashboard changes the screen to configuration mode and allows you to turn widget displays on or off.
Dashboard Widgets
The Dashboard widgets show information about the TrueNAS system basic settings, CPU and memory usage, network traffic and link status, storage, and backup tasks.
Dashboard widgets are customizable. Options include changing which widgets layouts and the location on the screen, and adding custom or application widgets.
Pool and network interface widgets vary based on storage and network configurations on the system.
Click on the Reports icon to display the data report screen that corresponds to the widget category.
For example, clicking the assessment icon on the CPU widget opens the Reporting > CPU screen.
System Information Widget
The System Information widget shows general information about the SCALE system.
The Updates Available button opens the System > Update screen.
Shows as Generic for customer-provided server and hardware and displays the TrueNAS SCALE logo to the left of the System Information fields. The TrueNAS model number for the iXsystems-provided server and hardware and a picture of the server shows in the area to the left of the fields.
Version
Shows the currently-installed software release of TrueNAS SCALE. Use the clipboard assignment icon to display the full name of the release installed and to copy the version to the clipboard.
Hostname
Shows the host name for the TrueNAS system. Configure the host name on the Network > Global Configuration screen.
Uptime
Shows the number of consecutive days, and hours and minutes the system of runtime since the last reboot.
Updates Available Check for Updates
Opens the System Update screen, or go to System > Update on the left-side main menu panel to open the System Update screen. Updates Available shows when systems updates are available for the current system release train.
HA System Information Widgets
TrueNAS Enterprise
The two HA Active and Standby controller System Information widgets show only for systems licensed for HA.
Each HA active or standby System Information widget shows the same information found on the non-HA System Information widget but also shows the system serial number, and system license number and type.
The standby controller widget shows the Initiate Failover button.
The active controller widget shows the Check for Updates button.
The widget includes a gauge showing GiB Free in blue, ZFS Cache in fuchsia pink, and Services in orange.
You can configure the memory widget as a one large (100%) or one long (50%) plus two quarter size (25%) widget layouts.
Network and Interface Widgets
The Network widget shows the status the configured primary system interface(s), link status, network I/O traffic, primary interface IP address, and media type and subtype if known.
It includes a dynamic graph showing the time of recorded traffic and the incoming (blue) and outgoing (orange) traffic in kbs.
You can configure an individual network interface (NIC) widgets in addition to the Network widget.
An Interface widget shows traffic, link status, interface media type and subtype, and any VLANS and the IP Address and port number.
The Storage widget shows information on the primary (root) pool status, path, and number of VDEVs configured in that pool.
It also shows the percentage of used and free space, and any caches.
It reports the number disks with errors, the total number of disks in the pool, and if a spare exists.
The Backup Task widget shows links to quickly set up an automated data backup schedule if a backup task does not exist.
Click open_in_new to open the Data Protection screen with all options for checking or backing up stored data.
The widget shows the number of tasks for each type of backup, direction for data (sent or received), the number of times tasks failed and succeeded, and weekly success counters.
Help Widget
The TrueNAS Help widget shows links to various TrueNAS websites.
Click on each link to open it in a new browser tab.
App Widget
The App widget shows the app name, version, state (Deploying, Active, Stopped, etc.), release status, CPU usage in percentage, memory usage in MiB, network I/O traffic, and disk I/O traffic.
The TrueNAS SCALE logo shows in the the top left corner of the widget if a logo image for the app is unavailable.
Save saves any changes and exits configuration mode.
Cancel exists configuration mode without saving changes.
Pressing Esc (escape) also exits configuration mode and discards any changes made to widget group area configurations or placements.
Widget Group Areas
Widget groups (areas) can use one of five layouts that consist of other widgets of different sizes and configurations.
Layouts options show on the Widget Editor screen.
Each grouping area shows three function icons:
Drag handle that allows you to grab and move the widget to a new location on the screen.
Dragging a widget to a new location shifts the other widgets one position to the left or right depending on where the dragged widget is placed.
Edit opens the Widget Editor populated with the settings for the existing widget.
Delete removes the widget from the Dashboard.
Pressing Tab allows selecting the next button or function icon on the screen and across all widget groups.
Widget Editor
Access to the Widget Editor screen is available when the Dashboard screen is in configuration mode.
The edit icon for any widget group opens the Widget Editor populated with the current settings for that widget group.
Add opens the Widget Editor with no settings.
Select an individual widget in a layout with multiple widgets to change the category and type and customize the display of the widget group.
Widget Editor Settings
Setting
Description
Layouts
Click on the layout image to add one to four widgets in the group. Not all widget categories support all layouts.
Widget Category
Select the information category from the dropdown list of options:
Empty - Default selection for a new widget. Use to fill a grouping of multiple widgets where only two are defined and the others are not.
Network - Use to to set up a network widget.
Storage - Use to set up a storage or single pool widget.
Help - Use to include the widget with links to SCALE resources.
Memory - Use to set up a memory-usage widget.
Backup Tasks - Use to set up a widget showing either configured data protection tasks or links to locations to configure tasks.
CPU - Use to set up a CPU usage widget.
System Information - Use to add one of four system information widget types.
Custom - Use to set up a text-only widget with whatever text-based information you want to include on the Dashboard.
The Widget Type field shows after selecting the category.
Widget Type
Select the type of information to show in the selected widget. Options change based on the selected Widget Category. See Widget Type Options by Category for information on the options by the category and type selected.
Widget Type Options by Category
Widget Type Options for Network
There are four types available when Widget Category is set to Network.
Selecting Network, IPv4 Address or IPv6 Address as the type adds the Interfaces field to the screen.
Hostname can use a full, half, or quarter size widget. It does not add additional fields.
IPv4 Address and IPv6 Address can use a full, half, or quarter size widget. Shows the Interface field.
Network can use a full or half size widget with network information for a primary or other interface configured on the system. Shows the Interface field.
Select the interface to show in the widget from the Interface dropdown field.
Widget Type Options for Storage
There are two widget types available when Widget Category is set to Storage: Storage and Pool.
The layout for the widget must be full size.
Selecting either Storage or Pool as the type adds the Pool field to the screen.
Widget Type Options for Help
Only Help is the available widget type when Widget Category is set to Help.
The Help widget can use a full, half, or quarter size widget, but using the half or quarter size adds scrollbars to the widget to provide access to the full content in this widget category.
For best viewing and access to the content we recommend using the full size for the Help widget.
Widget Type Options for Memory
Only Memory is the available widget type when Widget Category is set to Memory.
The Memory widget can use a full, half, or quarter size widget, and can be included in a widget group with other widget categories and types.
Widget Type Options for Backup Tasks
Only Backup Tasks is the available widget type when Widget Category is set to Backup Tasks.
The Backup Task widget can only use a full size widget.
Widget Type Options for CPU
Only CPU is the available widget type when Widget Category is set to CPU.
The CPU widget can only use a full size widget.
Widget Type Options for System Information
There are four widget types available when Widget Category is set to System Information: System Information Active Node, OS Version, System Uptime, and System Image.
System Information Active Node shows system information for a single controller system in a full size widget.
OS Version, System Uptime, or System Image can use a full, half, or quarter size widget.
These can be included in a widget group with other widget categories and types to create a mixed information widget.
Widget Type Options for Custom
Only Arbitrary Text is the available widget type when Widget Category is set to Custom.
There are three additional fields to enter text strings in a full, half, or quarter-size widget.
Enter text in Widget Title, Widget Text, and Widget Subtext (if desired) that does not exceed the maximum character count.
The maximum number of character for the Custom widget is 200 upper and lower case alpha-numeric or special characters.
Spaces between characters count as characters.
Storage
The Storage Dashboard screen allows users to configure and manage storage resources such as pools (VDEVs), and disks, and keep the pool healthy (scrub).
The dashboard widgets organize functions related to storage resources.
No Pools Screen
The No Pools screen displays before you add the first pool.
Select a pool from the Pool dropdown list.
These are ZFS storage pools previously created and stored on disks connected to the TrueNAS system.
TrueNAS detects these as present on the system but not yet connected in TrueNAS.
Import starts the process of connecting the pool in TrueNAS and bringing it into SCALE.
Export/Disconnect opens the Export/disconnect pool: poolname window where users can export, disconnect, or delete a pool.
The Export/disconnect pool window includes a warning stating data becomes unavailable after export and that selecting Destroy Data on this pool destroys data on the pool disks.
Exporting/disconnecting can be a destructive process!
Back up all data before performing this operation. You might not be able to recover data lost through this operation.
This window displays the share type (for example, SMB share, etc.) affected by the export/disconnect operation if a share uses the pool.
Disks in an exported pool become available to use in a new pool but remain marked as used by an exported pool.
If you select a disk used by an exported pool to use in a new pool, the system displays a warning message about the disk.
Setting
Description
Destroy data on this pool?
Select to erase all data on the pool. A field displays where you enter the pool name to confirm the operation before the Export/Disconnect button activates.
Delete configuration of shares that use this pool
Enabled by default to remove the share connection to this pool. Exporting or disconnecting the pool deletes the configuration of shares using this pool. You must reconfigure the shares affected by this operation.
Confirm Export/Disconnect
(Required) Select to confirm the operation and accept the warnings displayed. Activates the Export/Disconnect button.
Export/Disconnect executes the process and begins the pool export or disconnect.
A status window displays with progress. When complete, a final dialog displays stating the export/disconnect completed successfully.
Expand (Click to expand)
Select Expand Pool to increase the pool size to match all available disk space.
This is used as the final step to resize disk partitions when expanding a pool capacity with disk replacements.
Also, users with pools of virtual disks use this option to resize these virtual disks apart from TrueNAS.
This is a permament action that cannot be reverted.
After adding a pool, the screen displays storage widgets.
The same set of four widgets and the Export/Disconnect and Expand buttons display for each pool created on the system.
The Unassigned Disks widget at the top of the Storage Dashboard only shows when there are disks available to add to a new or existing pool.
Each set of pool widgets provides access to screens for disks, datasets, VDEVs, snapshots, quotas, and pool ZFS functions for the pool.
For example, Manage Devices on the Topology widget opens the Devices screen with the VDEVs configured for only that pool.
Unassigned Disks Widget
The Unassigned Disks widget displays the number of disks available on your system to use in pools.
The disk count includes disks assigned in an exported pool.
If you attempt to use a disk assigned in an exported pool, a warning message displays that prompts you to select a different disk.
To see information on each disk on the system, click Manage Disks on the Disk health widget
Add to Pool on the Unassigned Disks widget opens the Add to Pool window.
It displays the number of unassigned disks and provides the option to assign these disks to a new or existing pool.
Add Disks opens the Pool Manager screen if the existing pool was created with the Pool Manager, otherwise it opens the Pool Creation Wizard.
If you select New Pool, Add Disks opens the Pool Creation Wizard screen.
Topology Widget
The Topology widget shows information on the VDEVs configured on the system and the status of the pool.
The widget lists each VDEV type (data, metadata, log, cache, spare, and dedup).
A Data VDEV includes the data type (stripe, mirror, RAID, or mixed configuration), the number of disks (wide), and the storage capacity of that VDEV.
Manage Devices opens the Devices screen where you can add or manage existing VDEVs.
Usage Widget
The Usage widget shows information on the space datasets consume in the pool, and the status of pool usage.
The widget includes a color-coded donut chart that illustrates the percentage of space the pool uses.
Blue indicates space usage in the 0-80% range and red indicates anything above 80%.
A warning displays below the donut graph when usage exceeds 80%.
Usable Capacity details pool space statistics by Used, Available, and Used by Snapshots.
View Disk Space Reports opens the pool usage reports for the selected pool.
Large (>1 petabyte) systems could report storage numbers inaccurately.
Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
View all Scrub Tasks opens the Data Protections > Scrub Tasks details screen.
This lists all scheduled scrub tasks and allows you to add a new or edit an existing task.
Scrub Pool Dialog (Click to expand)
Click Scrub on the ZFS Health widget to initiate a check on pool data integrity.
The Scrub Pool dialog allows you to perform an unscheduled scrub task.
If TrueNAS detects problems during the scrub, it either corrects them automatically or generates an alert in the web interface.
By default, TrueNAS automatically checks every pool to verify it is on a reoccurring scrub schedule.
To schedule a single or a regular pool scrub operation, click View All Scrub Tasks to open the Data Protections > Scrub Tasks details screen and add or manage scrub tasks configured on your system.
When enabled, Auto TRIM allows TrueNAS to periodically review data blocks and identify which empty blocks of obsolete blocks it can delete.
Leave unselected to incorporate day block overwrites when a device write is started (default).
Select Confirm to activate Save.
For more details about TRIM in ZFS, see the autotrim property description in zpool.8.
Disk Health Widget
The Disk Health widget shows information on the health of the disks in a pool.
The details on the widget include the non-dismissed disk temperature alerts for highest, lowest, and average temperature, and failed S.M.A.R.T. tests.
View Reports opens the Report screen for the disks in the selected pool.
View all S.M.A.R.T. Tests opens the Data Protection > S.M.A.R.T. Tests screen.
Pool Status Indicator
Each widget in the set of four pool widgets includes a color-coded icon just to the right of the header.
This icon indicates the status of the pool as healthy (green checkmark), offline (orange triangle), or in a warning state (purple warning sign).
This same information displays on both the Storage widget and a pool widget you can add to the Dashboard.
Upgrade Dialog
The Storage Dashboard shows the Upgrade button for existing pools after an upgrade to a new TrueNAS release that includes new OpenZFS feature flags.
Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS release.
Storage pool upgrades are typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Consider these factors before upgrading a storage pool to the latest OpenZFS feature flags.
Upgrading can affect data.
Before performing any operation that affects data on a storage disk, always back up data first and verify the backup integrity.
New OpenZFS feature flags are permanently applied to the upgraded pool.
An upgraded pool cannot be reverted or downgraded to an earlier OpenZFS version.
A storage pool with the latest feature flags cannot import into another operating system that does not support those feature flags.
Upgrading a ZFS pool is optional.
Do not upgrade the pool when reverting to an earlier TrueNAS version or repurposing the disks in another operating system that supports ZFS is a requirement.
The upgrade itself only takes a few seconds and is non-disruptive.
It is not necessary to stop any sharing services to upgrade the pool.
However, it is best to upgrade when the pool is not in heavy use.
The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
Section Contents
Disks: Describes UI screens and dialogs related to disk operations.
Pool Creation Wizard: Descriptions for settings and functions found in the Pool Creation Wizard.
Devices: Provides information on settings and functions found on the Devices screens and widget.
Disks
The Disks screen lists the physical drives (disks) installed in the system.
The list includes the names, serial numbers, sizes, and pools for each system disk.
Use the Columns dropdown list to select options to customize disk the information displayed.
Options are Select All, Serial (the disk serial number), Disk Size, Pool (where the disk is in use), Disk Type, Description, Model, Transfer Mode, Rotation Rate (RPM), HDD Standby, Adv. Power Management, Enable S.M.A.R.T., S.M.A.R.T. extra options, and Reset to Defaults.
Each option displays the information you enter in the Edit Disk screen or when you install the disk.
Select the checkbox to the left of a disk to display the Batch Operations options.
The checkbox at the top of the table selects all disks in the system. Select again to clear the checkboxes.
Storage in the breadcrumb at the top of the screen returns to the Storage Dashboard.
Disks Screen - Expanded Disk
Click anywhere on a disk row to expand it and show the traits specific to that disk and available options.
The expanded view of a disk includes details for the disk and options to edit disk properties, run a SMART test and view the test results, and in some instances the ability to wipe the disk.
Manual Test opens the Manual SMART Test dialog with a list of the disk(s) selected.
Bulk Edit Disks
The Bulk Edits Disks screen allows you to change disk settings for multiple disks simultaneously.
The screen lists the device names for each selected disk in the Disks to be edited section.
Select the minutes of inactivity before the drive enters standby mode from the dropdown list. Options are Always On or 5, 10, 20, 30, 60, 120, 240, 300, and 330. For more information read this [forum post
Advanced Power Management
Select the power management profile from the dropdown list. Options are Disabled, Level 1 - Minimum power usage with Standby (spindown), Level 64 - Intermediate power usage with Standby, Level 127 - Maximum power usage with Standby, Level 128 - Minimum power usage without Standby (no spindown), Level 192 - Intermediate power usage without Standby, and Level 254 - Maximum performance, maximum power usage.
Enable S.M.A.R.T.
Select to enable and allow the system to conduct periodic S.M.A.R.T. tests.
The Manual S.M.A.R.T. Test dialog displays the name of the selected disk(s) and the option to specify the type of test you want to run outside of a scheduled S.M.A.R.T. test.
Runs SMART Extended Self Test. This scans the entire disk surface and can take many hours on large-volume disks.
Short
Runs SMART Short Self Test (usually under ten minutes). These are basic disk tests that vary by manufacturer.
Conveyance
Runs a SMART Conveyance Self-Test. This self-test routine is intended to identify damage incurred during transporting of the device. This self-test routine requires only minutes to complete.
Offline
Runs SMART Immediate Offline Test. The effects of this test are visible only in that it updates the SMART Attribute values, and if the test finds errors, they appear in the SMART error log.
Start begins the test. Depending on the test type selected, the test can take some time to complete. TrueNAS generates alerts when tests discover issues.
For information on automated S.M.A.R.T. testing, see the S.M.A.R.T. tests article.
S.M.A.R.T. Test Results of diskname Screen
The S.M.A.R.T. Test Results of diskname lists test results for the selected disk.
The Storage and Disks breadcrumbs return to other storage pages.
Storage opens the Storage Dashboard and Disks opens the Disks screen.
Customize the information displayed with the Columns option.
Options are Unselect All (toggles to Select All), Description, Status, Remaining, Lifetime, Error, and Reset to Defaults.
Unselect All removes all information except the ID number.
Expand the row to see the Description, Status, Remaining, Lifetime, and Error information for the test ID.
The Select All option displays all information on the table view and eliminates the expand function for the tests listed.
SMART Test Result Column Options
These options, except the ID, appear on the Columns dropdown list.
Option
Description
ID
The test identification number assigned by the system.
Description
Type of test run and the status of the system. For example, Short offline indicates the test type is Short while the system is offline when the test runs.
Status
Lists the test status. Options are Success or Fail.
Remaining
How much of the test is left to perform. If the test encounters an error, the field shows at what point in the test the error occurs. A value of 0 means the test completed and with no errors encountered.
Lifetime
The age of the disk when the test ran.
Error
Displays details about any error encountered during the test. Displays N/A if no error was encountered during the test.
Wipe Disk Dialogs
The option to wipe a disk only displays when a disk is unused by a pool.
Wipe opens three dialogs, one to select the method, a confirmation dialog, and a progress dialog that includes the option to abort the process.
The Wipe Disk diskname opens after clicking Wipe on the expanded view of a disk on the Disks screen.
Method provides options for how you want the system to wipe the disk.
Options are Quick, Full with zeros, or Full with random data.
See Wiping Disks for more information.
Abort stops the disk wipe process. At the end of the disk wipe process a success dialog displays.
Close closes the dialog and returns you to the Disks screen.
Edit Disk Screen
The Edit Disk screen allows users to configure and manage general disk, power management, temperature alert, S.M.A.R.T., and SED settings for system disks not assigned to a pool.
Click Edit Disk on the Devices screen to open the the Edit Disk screen.
General Settings
Setting
Description
Name
Displays the current name of the disk. To change, enter a Linux disk device name.
Serial
Displays the serial number for the selected disk. To change, enter the disk serial number.
Description
Enter notes about this disk.
Power Management Settings
Setting
Description
HDD Standby
Select a value from the dropdown list of options or leave it set to the default Always On. This specifies the minutes of inactivity before the drive enters standby mode. This forum post describes identifying spun-down drives. Temperature monitoring is disabled for standby disks.
Advanced Power Management
Select a power management profile from the dropdown list of options that include Disabled (the default setting), Level 1 - Minimum power usage with Standby (spindown), Level 64 - Intermediate power usage with Standby, Level 127 - Maximum power usage with Standby, Level 128 - Minimum power usage without Standby (no spindown), Level 192 - Intermediate power usage without Standby, or Level 254 - Maximum performance, maximum power usage.
Temperature Alerts Settings
Setting
Description
Critical
Enter a threshold temperature in Celsius. If the drive temperature is higher than this value, it creates a LOG_CRIT level log entry and sends an email to the address entered in the Alerts. Enter 0 to disable this check.
Difference
Enter a value in degrees Celsius that triggers a report if the temperature of a drive changes by this value since the last report. Enter 0 to disable this check.
Informational
Enter a value in degrees Celsius that triggers a report if the drive temperature is at or above this temperature. Enter 0 to disable this check.
S.M.A.R.T./SED Settings
Setting
Description
Enable S.M.A.R.T.
Select to enable the system to conduct periodic S.M.A.R.T. tests.
Configuration Preview lists pool and VDEV settings that dynamically update as you configure settings in the wizard.
Inventory displays the number of available disks by size on the system, and this list dynamically updates as disks move to VDEVs added in the wizard.
Pool Creation Wizard
The Pool Creation Wizard for most systems has seven configuration screens, numbered in sequence, to create a pool with VDEVs.
TrueNAS Enterprise
Larger iXsystems-provided servers for Enterprise users equipped with expansion shelves include the additional Enclosure Options screen.
Each wizard VDEV configuration screen includes the Automated Disk Selection and Advanced Options areas.
Click Manual Disk Selection to open the Manual Selection screen.
Back and Next move to the previous or next wizard screen.
Reset Step clears the VDEV settings for the VDEV type selected. For example, Data VDEV configuration.
Save And Go To Review saves the current selections and goes directly to the Review wizard screen.
General Info
The General Info area includes two default settings, Name and Encryption.
Name is a required field.
Enter a pool name of up to 50 characters in length that follows ZFS naming conventions.
Use lower-case alpha characters to avoid potential problems with sharing protocols.
Names can include numbers and special characters such as underscore (_), hyphen (-), colon (:), or a period (.).
Encryption applies key-type encryption to the pool.
TrueNAS 22.12.3 or later forces encryption for all child datasets and zvols within an encrypted root or parent dataset that are using the TrueNAS UI.
However, datasets created outside of the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured.
For more granular control and awareness, we do not recommend users configure pool-level encryption of the root dataset.
Instead, create an unencrypted pool and populate it with encrypted or unencrypted child datasets, as needed.
Select to enable ZFS encryption for the pool and all datasets (or zvols) within the pool created using the TrueNAS UI.
See Storage Encryption for more information on using TrueNAS storage encryption.
An encryption warning dialog displays with a Confirm checkbox.
Select to enable the I Understand button. I Understand allows you to continue adding the pool with encryption applied.
Keep the encryption key file in a safe location where you perform regular backups. Losing the encryption key file results in lost data you cannot recover.
If system disks contain data exported from pools, a warning displays with a checkbox for the pool name.
Allow non-unique serialed disks has two radio buttons, Allow and Don’t Allow.
Allow permits using disks with non-unique serial numbers, such as those that can occur on virtual disks, and displays them as available disks on the Data wizard screen.
Don’t Allow does not permit using disks with non-unique serial numbers.
TrueNAS Enterprise
Enclosure Options
The Enclosure Options screen shows in the Pool Creation Wizard if the iXsystems hardware includes one or more expansion shelves.
The Enclosure Options screen shows three radio buttons that could apply a set pool storage configuration topology when using the Automated Disk Selection option to assign disks to a VDEV.
No Enclosure Dispersal Strategy does not apply a dispersal strategy in how the system adds disks by size and type to the pool VDEVs created when using the Automated Disk Selection option.
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 in how the system adds disks by size and type to the pool VDEVs created when using the Automated Disk Selection option.
This balances disk selection across all enclosures and available disks.
Does not show additional options. Disks added to the pool VDEVs are spread across all available enclosure disks.
Limit Pool To A Single Enclosure applies a minimum dispersal strategy in how the system adds disks by size and type to the pool VDEVs created when using the Automated Disk Selection option.
Shows the Enclosure dropdown with a list of available expansion shelf options. Disks added to the pool VDEVs are spread across the enclosure disks that align with the selection in Enclosure.
The Data wizard screen includes the option to automatically or manually add disks to a data VDEV.
You must add a data VDEV before you can add other types of VDEVs to the pool.
The Layout dropdown list shows the Stripe, Mirror, RAIDZ1, RAIDZ2, RAIDZ3, dRAID1, dRAID2, and dRAID3 VDEV types on the Data wizard screens.
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 2 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 2.
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. It is recommended to set this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Log (Optional)
Use the Log wizard screen to configure a log VDEV. ZFS log devices can improve the speeds of synchronous writes.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least 2 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 2.
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. It is recommended to set this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Spare (Optional)
Use the Spare wizard screen to configure a hot spare for a drive in a data VDEV.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least 2 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 2.
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. It is recommended to set this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Cache (Optional)
Use the Cache wizard screen to configure a ZFS L2ARC read-cache VDEV.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least 2 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 2.
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. It is recommended to set this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Metadata (Optional)
Use the Metadata wizard screen to configure a special allocation class VDEV. Metadata VDEVS are used when creating a fusion pool.
This VDEV type is used to speed up metadata and small block IO.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least 2 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 2.
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. It is recommended to set this to at least 1. The Distributed Hot Spares number cannot be modified after the pool is created.
Children
The total number of disks to allocate in the dRAID VDEV. The field selection and options update dynamically based on the chosen dRAID Layout, Disk Size, Data Devices, and Distributed Hot Spares. Increasing the number of Children in the dRAID VDEV can reduce the options for Number of VDEVs.
Number of VDEVs
Select the number of VDEVs from the options provided on the dropdown list. Options are populated dynamically depending on the selections made in all the other fields.
Dedup (Optional)
Use the Dedup wizard screen to configure a VDEV. A Dedup VDEV is used to store de-duplication tables.
Size dedup VDEVs as x GiB for each x TiB of general storage.
The Layout dropdown list includes the Stripe or Mirror types.
This wizard screen lets you configure a VDEV using the Automated Disk Selection fields.
To individually find and select disks for a VDEV, click Manual Disk Selection in the Advanced Options area.
Choosing a dRAID VDEV layout removes the Manual Disk Selection button and adds different options to the Automated Disk Selection area.
It also removes the Spare VDEV section from the pool creation wizard and replaces it with the Distributed Hot Spares option in the Data VDEV section.
Designates that each disk is used sequentially in the VDEV.
Requires at least one disk and has no redundancy.
A data VDEV with a stripe layout irretrievably loses all stored data if a single disk in the VDEV fails.
Not recommended for data VDEVs storing critical data.
Mirror
Denotes that each disk in the VDEV stores an exact data copy.
Requires at least 2 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 2.
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. It is recommended to set 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.
Advanced Options
The Manual Selection screen allows adding a Stripe or the Data VDEV Layout, then selecting individual disks to add to the new VDEV.
You can filter disks by type or size.
Add places a VDEV area to populate with individual disks.
The screen shows disk icons for available disks, or click on the system field to expand the dropdown list to show a list of available system disks.
You can use the disk filters separately or together to find disks of the same type and size.
Drag disks to the VDEV to add them.
Save Selection creates the VDEV and closes the window.
Inspect VDEVs opens the Inspect VDEVs screen that shows the VDEVs with assigned disks added to the pool.
Start Over clears the current pool configuration so you can start over.
Create Pool completes the configuration process and adds the pool.
Devices
The Devices screen lists VDEVS and disks configured for the selected pool.
Go to Storage and click on Manage Devices on the Topology widget to view the Devices screen.
Add VDEV opens the Add a VDEVs to Pool screen with the Pool Creation Wizard for the selected pool.
For example, find the Topology widget for a pool and click Manage Devices.
This opens the Pool Creation Wizard with tank prepopulated but not editable.
ZFS Info Widget (VDEV)
The ZFS Info widget for the VDEV shows a count of read, write, and checksum errors for that VDEV, and the Extend and Remove options.
Remove opens the Remove device dialog where you confirm you want to remove the selected VDEV.
To remove a drive from the VDEV, select the drive then select Detach on the ZFS Info widget to remove the drive from the VDEV (pool).
Disk Widgets
Each disk in a VDEV has a set of four widgets that show information for that disk.
After selecting a disk, the widgets display on the right side of the screen in the Details for diskname area of the screen.
The ZFS Info widget for each device (disk drive) in the VDEV shows the name of the VDEV (Parent) the read, write, and checksum errors for that drive, and the Detach and Offline options.
Offline opens a confirmation dialog and takes the selected drive to an offline state so you can take the selected disk offline before replacing it.
Toggles to Online so you can bring a replacement disk online.
After taking a drive offline you can remove or replace the physical drive.
Global SED Password shows the status as set or not set.
The Manage Global SED Password link opens the System Settings > Advanced screen where you can change the global SED password that overrides the disk passwords.
S.M.A.R.T. Info for Devicename Widget
The S.M.A.R.T. Info for devicename widget, where devicename is the name of the disk, provides the number of Completed S.M.A.R.T. Tests and the number of S.M.A.R.T. Tests configured on the system.
The widget shows the status for the last short test performed.
The Type dropdown list includes the LONG, SHORT, CONVEYANCE, and OFFLINE options, and the Cancel and Start buttons.
Disk Info Widget
The Disk Info widget shows the Disk Size, Transfer Mode, the Serial and Model numbers for the drive, the Type of drive it is, the HDD Standby setting, and any Description associated with the selected drive.
Select the new disk for the pool from the Member Disk dropdown list.
The system prevents losing existing data by stopping the add operation for the new disk if the disk is already in use or has partitions present.
Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
Replace Disk adds the new disk to the pool.
Datasets
The Datasets screen and widgets display information about datasets, provide access to data management functions, indicate the dataset roles, list the services using the dataset, and show the encryption status and the permissions the dataset has in place.
The screen focuses on managing data storage including user and group quotas, snapshots, and other data protection measures.
Datasets Screen
The Datasets screen displays No Datasets with a Create Pool button in the center of the screen until you add a pool and the first root dataset.
The screen has two main sections, the dataset tree table on the left and the Details for datasetname on the right.
After creating a dataset, the tree table that lists parent and child datasets (or zvols) on the system.
The Details for datasetname area displays a set of dataset widgets.
Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Begin typing the name of a dataset in the Search field to filter datasets to a short list of those matching what is typed.
Dataset Tree Table
The datasets tree table lists datasets in an expandable hierarchical structure with the root dataset first, then each child or non-root parent dataset, and the child datasets of each nested under them.
Click on any parent dataset to expand the tree table and show nested child datasets.
Select a dataset to display the dataset widgets for that dataset.
The table includes used and available storage space for that dataset, encryption status (locked, unlocked, or unencrypted), the role of that dataset, and what service uses it (i.e., the system dataset, a share, virtual machine, or application).
Tree Table Encryption Icons
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
Tree Table Role Icons
Dataset tree table roles are represented by icons. Hover over the icons to view the description or icon label.
Roles in the dataset tree correspond to the Roles widget.
A dataset with an active task includes an activity spinner when that task is in progress.
Role
Icon
Description
System dataset
Indicates the parent (root) dataset designated as the system dataset. To change the system dataset go to System > Advanced Settings and edit the System Dataset Pool.
Share
Indicates the dataset is used by a share or that child datasets of the parent are used by shares.
SMB share
Indicates the dataset is used by an SMB share.
VM
Indicates the dataset is used by a virtual machine (VM).
Apps
Indicates this dataset is used by applications and stores Kubernetes configuration and container-related data.
Dataset Widgets
Each dataset has a set of information cards (widgets) that display in the Details for datasetname area of the screen.
These widgets provide information grouped by functional areas.
The set of widgets for a root or parent dataset differs from child datasets or datasets used by another service or with encryption.
The Dataset Details widget lists information on dataset type, sync type, compression level, case sensitivity, Atime, and ZFS deduplication settings.
Path displays the full path for the selected dataset.
Edit opens the Edit Dataset screen for the selected dataset.
Promote appears on the Dataset Details widget when you select a cloned snapshot on the dataset tree table.
This option promotes the cloned child dataset and allows users to delete the parent volume that created the clone.
Otherwise, you cannot delete a clone while the original volume still exists. See zfs-promote.8.
Non-root parent and child dataset versions of the card include the Delete button.
To delete a root dataset, use the Disconnect/Export option on the Storage Dashboard screen.
Delete opens a window that includes information about other options or services that use the dataset, for example a parent to other datasets and the services the child datasets of a parent dataset uses.
Non-root parent and child datasets include the Delete button.
Delete Window
The Delete window for a parent dataset (non-root) includes information about snapshots, shares or other services such as Kubernetes or VMs that use the dataset.
If a parent to other datasets, the window includes the services a child dataset uses.
The window includes a field where you enter the path for the dataset. Select the Confirm option to activate the Delete Dataset button.
Dataset Space Management Widget
The Dataset Space Management widget displays space allocation (reserved, used, available) for all datasets.
The widget displays if an encrypted dataset is unlocked. After locking the dataset this widget disappears until you unlock the dataset.
The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected dataset.
This includes data written and space allocated to child datasets of this dataset.
It provides access to quota configuration options for the parent dataset and the child dataset of the parent and for users and groups with access to the dataset.
Edit opens the Capacity Settings screen where you can set quotas for the dataset.
The Data Protection widget displays for all datasets.
It shows the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system.
Manage Snapshots opens the Snapshots screen list view where you can manage snapshots.
Manage Snapshot Tasks opens the Data Protection > Periodic Snapshot Tasks screen list view where you can manage scheduled periodic snapshot tasks.
Manage Replication Tasks opens the Data Protection > Replications Tasks screen list view where you can manage scheduled replication tasks.
Manage Cloud Sync Tasks opens the Data Protection > Cloud Sync Tasks screen list view where you can manage scheduled cloud sync tasks.
Manage Rsync Tasks opens the Data Protection > Rsync Tasks screen list view where you can manage scheduled rsync tasks.
The Snapshot counter shows the number of snapshots taken.
The Snapshot Tasks counter shows the number of scheduled snapshot tasks.
The Replication Tasks counter shows the number of scheduled replication tasks.
The Cloud Sync Tasks and Rsync Task counters show the number of scheduled push tasks.
These tasks protect or back up data, whereas pull sync tasks do not and are not included in the task count.
Permissions Widget
The Permissions widget displays for all datasets.
It shows the type of ACL as either NFSv4 or Unix Permissions (POSIX), and lists access control user or group entries and the owner and group for the dataset.
NFSv4 ACL type (the default ACL type) shows the user and group entries on the Permissions widget as buttons.
Click to show a selectable checklist of Permissions Advanced and Flags Advanced options for that entry on the Permissions widget.
The Roles widget displays the dataset role or the service that uses it (i.e., a share, application, virtual machine, or the system dataset).
A parent dataset displays information on child datasets that a service uses.
If the dataset is also the system dataset, the widget includes a link to the System > Advanced Settings screen where you can manage the system dataset.
The Roles widget shows information about the service using the dataset and provides a link to manage that service.
The information corresponds to the roles icon in the dataset tree table.
The Roles widget for a dataset with no share shows two links, one to create an SMB share and the other to create an NFS share.
Displays the name of the VM using the dataset(zvol). Select it on the Virtual Machines screen to edit it.
ZFS Encryption Widget
The ZFS Encryption widget displays for datasets configured with encryption.
The options in the widget vary based on the type of dataset (root, non-root parent, or child dataset).
It includes the current state of the dataset encryption, the encryption root, the type, and the algorithm used.
The ZFS Encryption widget displays the Lock or Unlock options that are not available on the root dataset or a child dataset of a non-root parent it inherits encryption settings from.
The root dataset ZFS Encryption widget includes the Export All Keys and the Export Key options, and the Edit option to change encryption settings.
Parent or child dataset ZFS Encryption widgets include the options to Lock and Unlock the dataset, and to Edit the encryption settings.
Child dataset ZFS Encryption widgets include the Go to Encryption Root when the Encryption Options setting is set to Inherit.
The non-root parent dataset controls the state of the child dataset.
For more details on encryption windows and functions see Encryption Settings.
Add and Edit Dataset Screens
The Add Dataset and Edit Dataset screens allow admin users with the right permission level to create and or modify datasets.
Both screens include the same settings but you cannot change the dataset name, Dataset Preset selection, or on the Advanced Options screen, change the Case Sensitivity settings after you click Save on the Add Dataset screen.
After adding a dataset, click Edit on the Dataset Details widget to open the Edit Dataset screen.
To edit encryption options, click Edit on the ZFS Encryption widget.
To edit dataset permissions, click Edit on the Permissions widget.
Add Dataset and Edit Dataset screens include the Basic Options and Advanced Options.
TheBasic Options and Advanced Options screens include the Name and Options section.
Basic Options and Advanced Options screens both show the Name and Options settings.
The common settings are Parent Path, Name, and the Dataset Preset (previously known as the share type).
Read-only field that displays the dataset path. Populated with the parent dataset path, adds the name given to the dataset after entering it in Name. For example, tank/shares/smbshare1.
Name
Enter a unique identifier for the dataset. Names allow upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters, but TrueNAS does not allow trailing spaces after the dataset name. You cannot change the dataset name after clicking Save. The Name field on the Edit Dataset screen shows the path.
Dataset Preset
Select the option from the dropdown list to define the type of data sharing the dataset uses. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are:
Generic - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.
SMB - Select to optimize the dataset for SMB shares. Displays the Create SMB Share option pre-selected and SMB Name field populated with the value entered in Name. Sets the ACL to NFSv4.
Apps - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the ix-apps dataset for Docker storage for but separate datasets used for application data storage.
Multiprotocol - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. Allows clients to use either protocol to access the same data. Displays the Create NFS Share and Create SMB Share options pre-selected and the SMB Name field populated with the value entered in Name. See Multiprotcol Shares for more information. Sets the ACL to NFSv4.
Setting cannot be edited after saving the dataset.
Quota Management Settings
Shows only on the Advanced Options screen.
The This Dataset and This Dataset and Child Datasets sections include the same setting options.
This Dataset applies the quota settings to the for the dataset you are creating or editing.
This Dataset and Child Datasets applies to any children of the dataset.
These settings also display on the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset or the dataset and child datasets.
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 include all child datasets.
Quota Settings
Setting
Description
Quota for this dataset Quota for this dataset and all children
Enter a value to define the maximum allowed space for the dataset. 0 disables quotas.
Quota warning alert at, %
Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Quota critical alert at, %
Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Reserved space for this dataset Reserved space for this dataset and all children
Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.
Encryption Options Section
Encryption setting options display on the Advanced Options of the Add Dataset screen but not on the Edit Dataset screen.
To edit encryption settings, click Edit on the ZFS Encryption widget.
This opens the Edit Encryption Options for datasetName window where you can change encryption settings for an existing dataset.
If you create an unencrypted dataset, the default setting is Inherit (Non-Encrypted), and you can create encrypted or unencrypted child datasets under it.
If you create an encrypted dataset, the default setting is Inherit (Encryption), and all child datasets created under it are encrypted.
The default Inherit option is pre-selected.
Clear the Encryption option (pre-selected) checkbox to show the key type encryption settings.
Select Passphrase in Encryption Type to show other settings.
Leave selected to inherit encryption from the parent dataset (encrypted/non-encrypted). Select to clear the checkmark and display the Encryption option.
Encryption
Leave selected to show the other encryption settings and to set the encryption type as pass key or password. Select to clear the checkmark and hide the encryption settings on the Add Dataset screen.
Setting
Description
Encryption Type
Select the option for the type of encryption to secure the dataset from the dropdown list. Select Key to use key-based encryption and display the Generate Key option. Select Passphrase to enter a user-defined passphrase to secure the dataset. This displays two additional Passphrase fields to enter and confirm the passphrase and the pbkdf2iters field.
Generate key
Selected by default to have the system randomly generate an encryption key for securing this dataset. Clearing the checkbox displays the Key field and requires you to enter an encryption key you define. Warning! The encryption key is the only means to decrypt the information stored in this dataset. Store encryption keys in a secure location! Creating a new key file invalidates any previously downloaded key file for this dataset. Delete any previous key file backups and back up the new key file.
Key
Enter or paste a string to use as the encryption key for this dataset.
Algorithm
Displays for both key and passphrase encryption types. Select the mathematical instruction set that determines how plaintext converts into ciphertext from the dropdown list of options. See Advanced Encryption Standard (AES) for more details.
Passphrase Confirm Passphrase
Enter the alpha-numeric string or phrase you want to use to secure the dataset.
pbkdf2iters
Enter the number of password-based key deviation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Other Options Section
The Other Options tune the dataset for specific data-sharing protocols by setting compression level and sync type options, ACL type and mode, and other settings.
Enter optional text to describe or define the dataset usage or any other information to associate with the dataset.
Sync
Select the sync setting option from the dropdown list. Options are:
Standard uses the sync settings requested by the client software.
Always waits for data writes to complete.
Disabled never waits for writes to complete.
Compression level
Select the compression algorithm to use from the dropdown list. Options encode information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of space saved. Options include:
LZ4 is generally recommended as it maximizes performance and dynamically identifies the best files to compress.
ZSTD is the Zstandard compression algorithm with several options for balancing speed and compression.
Gzip options range from 1 for least compression with best performance or 9 for maximum compression with greatest performance impact.
ZLE is a fast algorithm that only eliminates runs of zeroes.
LZJB is a legacy algorithm that is not recommended for use.
Enable Atime
Select the access time for files option from the dropdown list. Access time can result in significant performance gains. Inherit uses the access time setting of the parent or the root dataset. On updates the access time for files when they are read. Off disables creating log traffic when reading files to maximize performance.
ZFS Deduplication
Select the option from the dropdown list to transparently reuse a single copy of duplicated data to save space. Options are:
Inherit - Select to use the parent or root dataset settings.
On - Select to use deduplication.
Off - Select to not use deduplication.
Verify - Select to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical.
Deduplication can improve storage capacity but is RAM intensive. Compressing data is recommended before using deduplication. Deduplication is experimental in 24.10 and not fully supported. When enabled, data is permanently stored, creating the need for adequate data backups prior to enabling this feature.
Case Sensitivity
Select the option from the dropdown list. Options are:
Sensitive assumes file names are case sensitive.
Insensitive assumes file names are not case sensitive.
You cannot change case sensitivity after saving the dataset. Note: The Mixed option no longer exists.
Checksum
Select the checksum option from the dropdown list. Options:
Inherit - Select to use the parent setting.
On - Select to use checksum without specifying the variant.
FLETCHER2 (deprecated) or FLETCHER4 - Select to use a position-dependent checksum that uses two checksums to determine single-bit errors in messages transmitted over network channels or ZFS streams.
SHA256 (default for dedupted datasets) or SHA512 - Select to use a sequence of numbers and letters to check the copy of a downloaded update file is identical to the original.
SKEIN Not supported for a file system on boot pools.
EDNOR is not supported for file systems on boot pools and Edon-R requires verification when used with dedup so it automatically uses verify.
Select the option to allow or prevent dataset modification from the dropdown list. On prevents modifying the dataset. Off allows users accessing the dataset to modify its contents.
Exec
Select the option for executing processes from within the dataset from the dropdown list. On allows executing processes from within this dataset. Off prevents executing processes from with the dataset. We recommend setting it to On.
Snapshot directory
Select the option to controls visibility of the .zfs directory on the dataset from the dropdown list. Select either Visible or Invisible.
Snapdev
Select the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible from the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Copies
Select the number of ZFS user data duplicates stored on this dataset from the dropdown list. Select between 1, 2, or 3 redundant data copies. This can improve data protection and retention but is not a substitute for storage pools with disk redundancy.
Record Size
Select the logical block size in the dataset from the dropdown list of options. Matching the fixed size of data, as in a database, can result in better performance.
ACL Type
Select the access control list type from the dropdown list of options. Options are:
Inherit - Select to preserve ACL type from the parent dataset.
Off - Select to use neither NFSv4 or POSIX protocols.
NFSv4 -Select to cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with TrueNAS Core, FreeBSD, or other non-Linux ZFS implementations.
POSIX - Select when an organization data backup target does not support native NFSv4 ACLs. Since the Linux platform used POSIX for a long time, many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSv4 ACLs.
All datasets within an SMB share path must have identical ACL types. For a more in-depth explanation of ACLs and configurations in TrueNAS SCALE, see our ACL Primer. This advanced setting changes ACL type and mode settings configured by the Dataset Preset option. Do not make changes here if you do not understand ACLs.
ACL Mode
Select the option that determines how chmod behaves when adjusting file ACLs. See the zfs(8)aclmode property for more information. Options are:
Passthrough - Only updates ACL entries that are related to the file or directory mode.
Restricted - Does not allow chmod to make changes to files or directories with a non-trivial ACL. An ACL is trivial if it can be fully expressed as a file mode without losing any access rules. Set ACL Mode to restricted to optimize a dataset for SMB sharing, but it can also require further optimizations. For example, configuring an rsync task with this dataset could require adding --no-perms in the task Auxiliary Parameters field.
Metadata (Special) Small Block Size
Enter a threshold block size for small file blocks you include in 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. Before setting this property, you must add a metadata special class VDEV to the pool.
Data Compression Algorithms
Select the compression algorithm that best suits your needs from the Compression dropdown list of options.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Contents
Zvols: Provides information on the settings and functions found on the Zvol screens and widgets.
Capacity Settings: Provides information on the quota settings and functions found on the Capacity Settings screen.
Snapshots: Provides information on the settings and functions found on the Snapshots screen.
User and Group Quotas : Provides information on the settings and functions found on the User and Group Quota screens.
Encryption Settings: Provides information on the settings and functions found on the SCALE storage encryption screens.
Permissions: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.
Zvols
The zvol screens and widgets, accessed from the Datasets screen, allow you to add or edit a zvol and manage the volume storage.
Zvols are listed on the Datasets screen tree table.
The tree table includes storage space used and available for that zvol (or dataset), encryption status (locked, unlocked, or unencrypted), and the role of that zvol or dataset or what service uses it (i.e., the system dataset, a share, virtual machine, or application).
Add Zvol displays after you select a root, non-root parent, or child dataset. It does not display if you select an existing zvol. Click on any root or non-root parent dataset to expand the tree table.
Click on any zvol to select it and display the widgets for that zvol.
Zvol Widgets
Each zvol has a set of information cards (widgets) that display in the Details for zvolname area of the screen and provide information grouped by functional areas.
Add Zvol opens the Add Zvol screen.
Dataset widgets are:
The Zvol Details widget lists information on volume type, and the sync, compression level, case sensitivity, Atime, and ZFS deduplication settings. The Zvol Details widget shows information on volume type, and the sync, compression level, case sensitivity, Atime, and ZFS deduplication settings.
Path displays the full path for the selected zvol.
The Delete Zvol dialog shows information about other options or services that use the zvol. It also shows the services child datasets use.
This includes information about snapshots, shares, or if used, other services such as Kubernetes or VMs that use the dataset.
Parent and child datasets include the Delete button.
The window includes a field where you type the path for the zvol, and a Confirm option you must select to activate the Delete Dataset button.
Zvol Space Management Widget
The Zvol Space Management widget displays space allocation (reserved, used, available) for the zvol. The widget displays after unlocking encrypted zvols.
The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected zvol.
This includes data written and space allocated to child datasets of this dataset.
It provides access to quota configuration options for the parent dataset and the child dataset of the parent, and for users and groups with access to the dataset.
Edit opens the Capacity Settings screen where you can set quotas for the zvol.
The widget displays quotas set for users or groups.
ZFS Encryption Widget
The ZFS Encryption widget displays for zvols configured with encryption.
It shows the current state of the encryption, the encryption root, the type, and the algorithm used.
The ZFS Encryption widget displays the Lock or Unlock options if it uses key encryption instead of a passphrase.
The Export Key option displays if the zvol uses key encryption.
For more details on encryption windows and functions see Encryption Settings.
Data Protection Widget
The Data Protection widget displays for all datasets or zvols.
It shows information for the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system.
It provides access to the tasks found on the Data Protection screen through links.
Manage Snapshots opens the Snapshots screen list view where you can manage snapshots.
Manage Snapshot Tasks opens the Data Protection > Periodic Snapshot Tasks screen list view where you can manage scheduled periodic snapshot tasks.
Manage Replication Tasks opens the Data Protection > Replications Tasks screen list view where you can manage scheduled replication tasks.
Manage Cloud Sync Tasks opens the Data Protection > Cloud Sync Tasks screen list view where you can manage scheduled cloud sync tasks.
Manage Rsync Tasks opens the Data Protection > Rsync Tasks screen list view where you can manage scheduled rsync tasks.
Add and Edit Zvol Screens
The Add Zvol and Edit Zvol screens allow admin users with the right permission level to create and modify zvols.
Both screens include the same settings but you cannot change the zvol name, Block Size, or select the Sparse option after you click Save on the Add Zvol screen.
After adding a zvol, click Edit on the Zvol Details widget to open the Edit Zvol screen.
To edit encryption options, click Edit on the ZFS Encryption widget.
Required setting. Enter a short name for the zvol. Using a zvol name longer than 63 characters can prevent accessing zvols as devices. For example, you cannot use a zvol with a 70-character file name or path as an iSCSI extent.
Comments
Enter any notes about this zvol.
Size for this zvol
Specify size and value. You can include units like t as in TiB, and G. You can increase the size of the zvol later, but you cannot reduce the size. If the size is greater than 80% of the available capacity, the creation fails with an out-of-space error unless you select Force size.
Force size
Select to enable the system to create a zvol where the size is over 80% capacity. By default, the system does not create a zvol of this size. While not recommended, enabling this option forces the creation of the zvol.
Sync
Select the data write synchronization option from the dropdown list. Inherit gets the sync settings from the parent dataset. Standard uses the sync settings requested by the client software. Always waits for data writes to complete. Disabled never waits for writes to complete.
Compression level
Select the option from the dropdown list for the type of data compression to use for encoding information in less space than the original data occupies. Select the algorithm that balances disk performance with the amount of space saved. See below for the options.
ZFS Deduplication
Do not change this setting unless instructed to do so by your iXsystems support engineer. Select to transparently reuse a single copy of duplicated data to save space. Deduplication can improve storage capacity, but it is RAM intensive. Compressing data is recommended before using deduplication. Deduplicating data is a one-way process. You cannot un-deduplicate deduplicated data!
Sparse
Used to provide thin provisioning. Use with caution as writes fail when space is low on a pool.
Block size
Select the size option from the dropdown list. The default is 16KiBt, other options are 4KiB, 8KiB, 16KiB, 32KiB, 64KiB, 128KiB. The zvol default block size is automatically chosen based on the number of disks in the pool for a general use case.
Read-only
Select the option to use to prevent modifying the zvol. Options are Inherit (off), On or Off.
Snapdev
Select the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible from the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
Encryption options do not display unless you create the zvol and encrypted dataset.
Block Size Table
TrueNAS recommends a space-efficient block size for new zvols.
This table shows the minimum recommended volume block size values by configuration (mirror or RAIDz type).
Use this table to change the Block size value.
Configuration
Number of Drives
Optimal Block Size
Mirror
N/A
16k
Raidz-1
3
16k
Raidz-1
4/5
32k
Raidz-1
6/7/8/9
64k
Raidz-1
10+
128k
Raidz-2
4
16k
Raidz-2
5/6
32k
Raidz-2
7/8/9/10
64k
Raidz-2
11+
128k
Raidz-3
5
16k
Raidz-3
6/7
32k
Raidz-3
8/9/10/11
64k
Raidz-3
12+
128k
Depending on their workload, zvols can require additional tuning for optimal performance.
See the OpenZFS handbook workload tuning chapter for more information.
Data Compression Algorithms
Select the compression algorithm that best suits your needs from the Compression dropdown list of options.
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.
Encryption Options
Encryption Options only display on the Add Zvol screen.
To change encryption settings, use the Edit button on the ZFS Encryption widget.
The default setting is Inherit. Clearing the checkbox displays the encryption options.
Clear the Inherit (non-encrypted) checkbox to display additional settings.
Selecting other options changes the settings displayed.
Encryption Settings
Setting
Description
Inherit (non-encrypted)
Select to clear the checkmark to display more encryption settings.
Encryption
Select to clear the checkmark and remove the encryption settings from the Add Zvol screen. If the root dataset is not encrypted, leaving Inherit (non-encrypted) selected is the same as clearing the Encryption checkbox.
Setting
Description
Encryption Type
Select the option for the type of encryption to secure the dataset from the dropdown list. Select Key to use key-based encryption and display the Generate Key option. Select Passphrase to enter a user-defined passphrase to secure the dataset. This displays two additional Passphrase fields to enter and confirm the passphrase and the pbkdf2iters field.
Generate key
Selected by default to have the system randomly generate an encryption key for securing this dataset. Clearing the checkbox displays the Key field and requires you to enter an encryption key you define. Warning! The encryption key is the only means to decrypt the information stored in this dataset. Store encryption keys in a secure location! Creating a new key file invalidates any previously downloaded key file for this dataset. Delete any previous key file backups and back up the new key file.
Key
Enter or paste a string to use as the encryption key for this dataset.
Algorithm
Displays for both key and passphrase encryption types. Select the mathematical instruction set that determines how plaintext converts into ciphertext from the dropdown list of options. See Advanced Encryption Standard (AES) for more details.
Passphrase Confirm Passphrase
Enter the alpha-numeric string or phrase you want to use to secure the dataset.
pbkdf2iters
Enter the number of password-based key deviation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Capacity Settings
The Capacity Settings screen allows users to set quotas for the selected dataset and for the selected dataset and any of the child datasets for the selected dataset apart from the dataset creation process.
The settings on the Capacity Settings screen are the same as those in the quota management section on the Add Dataset > Advanced Options screen.
Setting
Description
Quota for this dataset Quota for this dataset and all children
Enter a value to define the maximum allowed space for the dataset. 0 disables quotas.
Quota warning alert at, %
Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Quota critical alert at, %
Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
Reserved space for this dataset Reserved space for this dataset and all children
Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.
Snapshots
The Snapshots screen lists dataset snapshots on the system.
It allows you to add new or manage existing snapshots.
Access to the Snapshots screen is available using the Manage Snapshots link on the Data Protection widget on the Datasets screen and by clicking Snapshots on the Periodic Snapshot Tasks widget on the Data Protection screen.
If the selected dataset does not have snapshots, the screen displays No Snapshots are Available.
My Snapshot screen is blank
If the Snapshots screen does not display a list of snapshots and you know you added snapshots, clear the dataset path in the search field to show all dataset and zvol snapshots on the system.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Show Extra Snapshot List Columns
Click the Show Extra Columns toggle to add extra information columns to the list of snapshots to open the Show Extra Columns dialog.
Show adds the extra columns to the list of snapshots. These columns add the space used (Used), the snapshot creation date, and the amount of data the dataset can access (Referenced).
Click the toggle again to open the Hide Extra Columns dialog. Hide to return to the default view with only the Dataset and Snapshot columns.
Snapshot Details Screen
Click anywhere on a snapshot to expand it and view more information about the snapshot and the options for that snapshot.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Option
Description
Delete
Opens a Delete confirmation dialog for the selected snapshot(s). Select Confirm to activate the Delete button.
Clone to New Dataset
Opens the Clone to New Dataset) window where you enter a new name or clone with the default value in the Dataset Name field.
Select to prevent the snapshot from being deleted. If selected and you batch-operation delete datasets, this opens an error display with the name of the dataset and prevents the delete operation from continuing.
Rollback from Snapshot Window
The snapshot Rollback option replaces the data in the selected dataset with the information saved in the snapshot.
WARNING: Rolling the dataset back destroys data on the dataset and can destroy additional snapshots that are related to the dataset.
This can result in permanent data loss!
Do not roll back until all desired data and snapshots are backed up.
There are three Stop Rollback if Snapshot Exists radio button options that impose safety levels on the rollback operation.
When the safety check finds additional snapshots directly related to the dataset you are rolling back it cancels the rollback.
Select to stop rollback when the safety check finds any related intermediate, child dataset, or clone snapshots that are newer than the rollback snapshots.
Newer Clone
Select to stop rollback when the safety check finds any related clone snapshots newer than the rollback snapshot.
No Safety Check (CAUTION)
Select to stop rollback if snapshot exists. The rollback destroys any related intermediate, child dataset, and cloned snapshots newer than the rollback snapshot.
Confirm
Select to confirm the selection and activate the Rollback button.
Use the Clone to New Dataset button to create a clone of the snapshot.
The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen.
Click Clone to New Dataset to open a clone confirmation dialog.
To delete more than one snapshot in one operation, select the checkbox beside the datasets you want to delete to display the Batch Operations Delete option.
Confirm activates the Delete button. If a snapshot has the Hold option selected, an error displays to prevent you from deleting that snapshot.
Add Snapshot Screen
The Add Snapshots screen allows you to create a snapshot while on the Snapshots screen.
It also opens when you click Create Snapshot on the Dataset Protection widget on the Datasets screen.
Save retains the settings and returns to the Snapshots screen.
Add Snapshot Settings
Setting
Description
Dataset
Select the dataset or zvol from the dropdown list. The snapshot created is from this dataset or zvol.
Name
TrueNAS populates this with a name but you can override the name with any string of your choice. You cannot use Name and Naming Schema for the same snapshot.
Naming Schema
Select an option from the dropdown list or leave this blank to use the system-populated name in the Name field. This generates a name for the snapshot using the naming schema from a previously-entered periodic snapshot. This allows replication of the snapshot. You cannot use Naming Schema with Name. Selecting a schema option overwrites the value in Name.
Recursive
Select to include child datasets or zvols in the snapshot.
User and Group Quotas
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
User Quotas Screen
Select Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.
The User Quotas screen displays names and quota data of user accounts cached on or connected to the system.
If no users exist, the screen displays No User Quotas in the center of the screen.
Click Save to save changes or click the “X” to close the window without saving.
Settings
Description
User
Displays the name of the selected user.
User Data Quota (Examples: 500KiB, 500M, 2 TB)
Enter the amount of disk space the selected user can use. Entering 0 allows the user to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
User Object Quota
Enter the number of objects the selected user can own. Entering 0 allows unlimited objects.
Set User Quotas Screen
To display the Set User Quotas screen click the Add button.
Enter the amount of disk space the selected user can use. Entering 0 allows the user to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
User Object Quota
Enter the number of objects the selected user can own. Entering 0 allows unlimited objects.
Apply Quotas to Selected Users Settings
Settings
Description
Apply To Users
Select the users from the dropdown list of options.
Click Save to set the quotas or click the “X” to exit without saving.
Group Quotas Screens
Click Manage Group Quotas on the Dataset Space Management widget to open the Group Quotas screen.
The Group Quotas screen displays the names and quota data of any groups cached on or connected to the system.
If no groups exist, the screen displays No Group Quotas in the center of the screen.
Click Save to set the quotas or click the “X” to exit without saving.
Edit Group Configuration Settings
Settings
Description
Group
Displays the name of the selected group(s).
Group Data Quota (Examples: 500KiB, 500M, 2 TB)
Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota
Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.
Set Group Quotas Screen
To display the Set Group Quotas screen, click the Add button.
Enter the amount of disk space the selected group can use. Entering 0 allows the group to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes.
Group Object Quota
Enter the number of objects the selected group can own or use. Entering 0 allows unlimited objects.
Apply Quotas to Selected Groups Settings
Settings
Description
Apply To Groups
Select groups from the dropdown list of options.
Encryption Settings
Datasets, root, non-root parent, and child, or zvols with encryption include the ZFS Encryption widget in the set of dataset widgets displayed on the Datasets screen.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon
State
Description
Locked
Displays for locked encrypted root, non-root parent and child datasets.
Unlocked
Displays for unlocked encrypted root, non-root parent and child datasets.
Locked by ancestor
Displays for locked datasets that inherit encryption properties from the parent.
Unlocked by ancestor
Displays for unlocked datasets that inherit encryption properties from the parent.
Dataset Encryption
The Encryption option on the Pool Manager screen sets encryption for the pool and root dataset.
TrueNAS 22.12.3 or later forces encryption for all child datasets and zvols within an encrypted root or parent dataset that are using the TrueNAS UI.
However, datasets created outside of the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured.
For more granular control and awareness, we do not recommend users configure pool-level encryption of the root dataset.
Instead, create an unencrypted pool and populate it with encrypted or unencrypted child datasets, as needed.
The Download Encryption Key warning window displays when you create the pool.
It downloads a JSON file to your downloads folder.
The ZFS Encryption widget for root datasets with encryption includes the Export All Keys and Export Key options. It does not include the Lock option.
If a dataset is encrypted using a key, the ZFS Encryption widget for that dataset includes the Export Key option.
Export All Keys Dialog
Export All Keys opens a confirmation dialog with the Download Keys option that exports a JSON file of all encryption keys to the system download folder.
Export Key opens a dialog with the key for the selected dataset and the Download Key option that exports a JSON file with the encryption key to your system download folder.
Encryption type and options are set for a dataset when it is first created or are inherited from the root dataset.
The Edit Encryption Options for datasetname displays the current encryption option settings for the selected encrypted dataset.
Use to change the encryption type from or to key or passphrase, and the related settings.
The Edit Encryption Options for datasetname window opens with the current dataset encryption settings displayed.
The encryption settings options are the same as those on Add Dataset > Encryption Options.
Select the option for the type of encryption to secure the dataset from the dropdown list. Select Key to use key-based encryption and display the Generate Key option. Select Passphrase to enter a user-defined passphrase to secure the dataset. This displays two additional Passphrase fields to enter and confirm the passphrase and the pbkdf2iters field.
Generate key
Selected by default to have the system randomly generate an encryption key for securing this dataset. Clearing the checkbox displays the Key field and requires you to enter an encryption key you define. Warning! The encryption key is the only means to decrypt the information stored in this dataset. Store encryption keys in a secure location! Creating a new key file invalidates any previously downloaded key file for this dataset. Delete any previous key file backups and back up the new key file.
Key
Enter or paste a string to use as the encryption key for this dataset.
Algorithm
Displays for both key and passphrase encryption types. Select the mathematical instruction set that determines how plaintext converts into ciphertext from the dropdown list of options. See Advanced Encryption Standard (AES) for more details.
Passphrase Confirm Passphrase
Enter the alpha-numeric string or phrase you want to use to secure the dataset.
pbkdf2iters
Enter the number of password-based key deviation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.
Lock Dataset Dialog
Lock displays on encrypted non-root parent or child datasets ZFS Encryption widgets.
An encrypted child that inherits encryption from a non-root parent does not see the Lock option on its ZFS Encryption widget because the lock state is controlled by the parent dataset for that child dataset.
The locked icon for child datasets that inherit encryption is the locked by ancestor icon.
Lock opens the Lock Dataset confirmation dialog with the option to Force unmount and Lock the dataset.
Force unmount disconnects any client system accessing the dataset via sharing protocol. Do not select this option unless you are certain the dataset is not used or accessed by a share, application, or other system services.
After locking a dataset, the ZFS Encryption screen displays Locked as the Current State and adds the Unlock option.
Unlock Datasets Screen
Unlock on the ZFS Encryption widget displays for locked datasets that are not child datasets that inherit encryption from the parent dataset.
Unlock opens the Unlock Datasets screen, which allows you to unlock the selected dataset and child datasets simultaneously.
If you select a child dataset of the root dataset or a non-root parent, the screen includes only the one Dataset Passphrase field, and the option to Unlock Child Encrypted Roots pre-selected.
Select to unlock any encrypted dataset stored within this dataset.
Dataset Passphrase Dataset Key
Enter the user-defined string (passphrase) or system-generated or user-created alpha-numeric key you entered when you created the dataset.
Force
Select to add a force flag to the operation. In some cases the provided key/passphrase may be valid but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, the unlock operation fails. Adding the force flag can override this and when selected, the system renames the existing dataset mount directory/file path and unlocks the dataset.
Save
Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Click Continue to unlock the dataset.
Save
Starts the unlock process, fetches data, and displays the Unlock Datasets dialog with the dataset mount path. Click Continue to unlock the dataset.
Permissions
TrueNAS SCALE offers two Access Control List (ACL) types: POSIX (the SCALE default) and NFSv4.
For a more in-depth explanation of ACLs and configurations in TrueNAS SCALE, see our ACL Primer.
The Dataset Preset option on the Add Dataset screen sets the ACL type applied for SMB shares, apps, multi-protocol shares, and general-use datasets.
The ACL Type setting in the Advanced Options on both the Add Dataset and Edit Dataset screens, determines the ACL presets available on the ACL Select a preset ACL window.
It also determines which permissions editor screens you see after you click the edit edit icon on the Dataset Permissions widget.
Set ACL Type to NSFv4 to activate and select which ACL Mode the dataset uses.
While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.
Unix Permissions Editor Screen
If you set Dataset Preset to Generic, or selected POSIX or Inherit as the ACL Type settings on the Add Dataset > Advanced Options screen, the first screen you see after clicking Edit on the Permissions widget is the Dataset > Edit Permissions screen Unix Permissions Editor.
Use the settings on this screen to configure basic ACL permissions.
POSIX ACL Owner Settings
The Owner section controls which TrueNAS user and group has full control of this dataset.
Setting
Description
User
Enter or select a user to control the dataset. Users created manually or imported from a directory service appear in the menu.
Apply User
Select to confirm user changes. To prevent errors, TrueNAS only submits changes after you select this option.
Group
Enter or select the group to control the dataset. Groups created manually or imported from a directory service appear in the menu.
Apply Group
Select to confirm group changes. To prevent errors, TrueNAS only submits changes after you select this option.
POSIX ACL Access Settings
The Access section lets users define the basic Read, Write, and Execute permissions for the User, Group, and Other accounts that might access this dataset.
A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets.
Removing this permission results in lost access to the path.
POSIX ACL Advanced Settings
The Advanced section lets users Apply Permissions Recursively to all directories, files, and child datasets within the current dataset.
To access advanced POSIX ACL settings, click Add ACL on the Unix Permissions Editor. The Select a preset ACL window displays with two radio buttons.
Select an ACL Preset
There are two different Select a preset ACL windows, one for the POSIX ACL and the other for the NFSv4 ACL.
Selecting a preset replaces the ACL currently displayed on the Edit ACL screen and deletes any unsaved changes.
For a POSIX ACL, a window with three setting options displays before you see the Edit ACL screen.
These setting options allow you to select and use a pre-configured set of permissions that match general permissions situations or to create a custom set of permissions.
You can add to a pre-configured ACL preset on the Edit ACL screen.
The ACL Type setting determines the pre-configured options presented on the Default ACL Options dropdown list on each of these windows.
For POSIX, the options are POSIX_OPEN, POSIX_RESTRICTED, or POSIX_HOME. For NFSv4, the options are NFS4_OPEN, NFS4_RESTRICTED, NFS4_HOME, and NFS4_DOMAIN_HOME.
Setting
Description
Select a preset ACL
Click to populate the Default ACL Options dropdown list with pre-configured POSIX permissions.
Create a custom ACL
Click to open the Edit ACL screen with no default permissions, users, or groups or to configure your own set of permissions. Click Continue to display the Edit ACL screen.
The Edit ACL screen options are based on ACL type (POSIX or NFSv4).
The Dataset Preset and ACL Type settings determine the ACL type. They are under Advanced Options in the Add Dataset and Edit Dataset screens
The section below describes the differences between screens for each ACL type.
ACL Editor Settings - POSIX and NFSv4
Select any user account or group manually entered or imported from a directory service in the Owner or Owner Group.
The value entered or selected in each field displays in the Access Control List below these fields.
Dataset displays the dataset path (name) you selected to edit.
The Access Control List section displays the items and a permissions summary for the owner@, group@, and everyone@ for both POSIX and NSFv4 ACL types. The list of items changes based on a selected pre-configured set of permissions.
To add a new item to the ACL, click Add Item, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.
Edit ACL Functions - POSIX and NFS4
These functions display on the Edit ACL screen for both POSIX and NSFv4 ACL types except for Strip ACL, which only displays for NSFv4 types.
Select to apply all settings or changes on the Edit ACL screen to all child datasets in the path in Dataset.
Save Access Control List
Saves settings or changes made on the Edit ACL screen.
Strip ACL
(NSFv4 only) Remove all ACLs from the current dataset and any directories or files contained within this dataset. Stripping the ACL resets dataset permissions and can make data inaccessible until you create new permissions.
Permissions Editor
(POSIX only) Displays the Unix Permissions Editor screen for POSIX ACL types.
Use Preset
Displays the Select a preset ACL window. If the ACL Type setting, found in the Advanced Options of both the Add Dataset and Edit Dataset screens, is POSIX or Inherit, the Default ACL Options dropdown displays POSIX pre-configured options. If set to NFSv4, the preset options displayed are pre-configured NSFv4 options.
Save As Preset
Saves the current access control list as a custom preset and adds it to the Access Control List.
POSIX Access Control Entry Settings
The POSIX Access Control Entry settings include Who, Permissions, and Flags options.
Select the user or group from the dropdown list the permissions apply to.
User denotes access rights for users identified by the entry qualifier. Group denotes access rights for the filegroup. Other denotes access rights for processes that do not match any other entry in the ACL. Group Obj denotes access rights for the filegroup. User Obj denotes access rights for the file owner. Mask denotes the maximum access rights User, Group Obj, or Group type entries can grant.
Permissions
Select the checkbox for each permission type (Read, Write and Execute) to apply to the user or group in Who.
Flags
Select the Default option to include a flag setting for the user or group in Who.
NFS4 Access Control Entry Settings
There are two Access Control Entry settings, Who and ACL Type.
The NFSv4 ACL Type radio buttons change the Permissions and Flags setting options. Select Allow to grant the specified permissions or Deny to restrict the permissions for the user or group in Who.
User denotes access rights for users identified by the qualifier. Group denotes access rights for groups identified by the qualifier. owner@ applies this entry to the user that owns the dataset. group@ applies this entry to the group that owns the dataset. everyone@ applies this entry to all users and groups.
ACL Type
Determines how the Permissions apply to the chosen Who. Choose Allow to grant the specified permissions and Deny to restrict the specified permissions.
NFS4 Permissions and Flags
TrueNAS divides permissions and inheritance flags into basic and advanced options. The basic permissions options are commonly-used groups of advanced options.
Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.
Basic Permissions Settings
Click the Basic radio button to display the Permissions dropdown list of options that applies to the user or group in Who.
Click the Advanced radio button to display the flag settings that enable or disable ACE inheritance and offer finer control for applying an ACE to new files or directories.
The ACE is inherited with subdirectories and files. It applies to new files.
Directory Inherit
d
New subdirectories inherit the full ACE.
No Propagate Inherit
n
The ACE can only be inherited once.
Inherit Only
i
Remove the ACE from permission checks but allow new files or subdirectories to inherit it. Inherit Only is removed from these new objects.
Inherited
I
Set when this dataset inherits the ACE from another dataset.
Shares
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares. TrueNAS SCALE allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
Click Shares on the main navigation panel to display the Sharing screen, which displays options to access SMB, NFS, and iSCSI shares.
The Windows (SMB) Shares launch toolbar displays the status of the SMB service as either STOPPED (red) or RUNNING (blue).
Before adding the first share, the STOPPED status displays in the default color.
Columns displays a set of options to customize the list view.
Options include Unselect All, Path, Description, Enabled and Reset to Defaults.
Add opens the Add SMB configuration screen.
Enabled indicates whether the share is enabled or disabled. If selected, the share path is available when the SMB service is active.
If cleared, the share is disabled but not deleted from the system.
Audit Logging indicates whether auditing for the share is enabled or disabled.
The more_vert displays a dropdown list of options for each share:
To return to the Share screen, click Shares on the main navigation panel or Sharing on the breadcrumb at the top of the screen.
Add and Edit SMB Screens
The two SMB share configuration screens, Add SMB and Edit SMB, display the same setting options.
The Create Dataset option does not show on the Edit SMB screen, but you can change to another existing dataset on the system.
Click Save to create the share (or save an existing one) and add it to the Windows (SMB) Shares widget and Sharing SMB details screen.
Basic Options Settings
The Basic Options settings in this section also display in the Advanced Options.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Enter the path or use the arrow_right icon to the left of /mnt to locate the dataset and populate the path. Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
/mnt
Click the arrow_right icon to expand the path at each dataset until you get to the SMB share dataset you want to use. This populates the Path.
Create Dataset
Click to open the Create Dataset dialog. Enter a name to create a new dataset for the share. Click Create to add the dataset and populate the Name field on the Add SMB screen.
Name
Enter a name for this share that is less than or equal to 80 characters. Because of how the SMB protocol uses the name, the name must not exceed 80 characters. The name cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. If not supplied, the share name becomes the last component of the path. This forms part of the full share path name when SMB clients perform and SMB tree connect. If you change the name, follow the naming conventions for files and directories or share names.
Purpose
Select a preset option from the dropdown list. The option applies predetermined settings (presets) and disables changing some share setting options.
Description
Enter a brief description or notes on how you use this share.
Enabled
Selected by default to enable sharing the path when the SMB service is activated. Clear to disable this SMB share without deleting it.
Purpose Setting Options
This table details the options found on the Purpose dropdown list.
Setting
Description
No presets
Select to retain control over all Advanced Options settings. This option gives users the flexibility to manually configure SMB parameters.
Default share parameters
The default option when you open the Add SMB screen and to use for any basic SMB share. These settings provide a baseline configuration that ensures compatibility and functionality, and allow users to set up shares with commonly implemented options and behaviors.
Basic time machine share
Select to set up a basic time machine share. This provides a centralized location for users to store and manage system backups.
Multi-User time machine
Select to set up a multi-user time machine share. This option allows multiple users to use TrueNAS as a centralized backup solution while simultaneously ensuring that each backup users make are kept separate and secure from one another.
Multi-Protocol (NFSv3/SMB) shares
Select for multi-protocol (NFSv3/SMB) shares. Choosing this option allows NFS and SMB users to access TrueNAS at the same time.
Private SMB Datasets and Shares
Select to create a share that maps to a path determined by the username of the authenticated user. TrueNAS creates a unique, private dataset matching the user name.
SMB WORM. Files become read-only via SMB after 5 minutes
The SMB WORM preset only impacts writes over the SMB protocol. Before deploying this option in a production environment, determine whether the feature meets your requirements. Employing this option, ensures data written to the share cannot be modified or deleted, thus increasing overall data integrity and security.
Advanced Options Settings
Click Advanced Options to display settings made available or locked based on the option selected in Purpose.
Access Settings
The Access settings customize access to the share and files, and also specifying allow or deny access for host names or IP addresses.
Select to enable ACL support for the SMB share. A warning displays if you clear this option and the SMB dataset has an ACL, and you are required to strip the ACL from the dataset prior to creating the SMB share.
Export Read-Only
Select to prohibit writes to the share.
Browsable to Network Clients
Select to determine whether this share name is included when browsing shares. Home shares are only visible to the owner regardless of this setting. Enabled by default.
Allow Guest Access
Select to enable. Privileges are the same as the guest account. Guest access is disabled by default in Windows 10 version 1709 and Windows Server version 1903. Additional client-side configuration is required to provide guest access to these clients. MacOS clients: Attempting to connect as a user that does not exist in FreeNAS does not automatically connect as the guest account. You must specifically select the Connect As: Guest option in macOS to log in as the guest account. See the Apple documentation for more details.
Access Based Share Enumeration
Select to restrict share visibility to users with read or write access to the share. Open is the default for this setting. See the smb.conf manual page.
Hosts Allow
Enter a list of allowed host names or IP addresses. Separate entries by pressing Enter. You can find a more detailed description with examples here.
Hosts Deny
Enter a list of denied host names or IP addresses. Separate entries by pressing Enter.
Audit Logging
The Audit Logging settings enable the auditing function for the SMB share, and allow configuring a watch and ignore list for groups administrators want to monitor.
Select groups from the dropdown list that you want to generate audit logging message for. Leaving this blank includes all SMB users with access to the share. If also setting a limit list, when a conflict exists the watch list takes precedence.
Limit List
Select groups from the dropdown list that you want to ignore or exclude from audit logging. If a group is a member of both the watch and limit lists, the watch list takes precedence and the group generates audit messages.
Other Settings
The Other Options settings include improving Apple software compatibility, ZFS snapshot features, and other advanced features.
Select to allow the share to host user home directories. Each user has a personal home directory they use when connecting to the share that is not accessible by other users. Home Shares allow for personal, dynamic shares. You can only use one share as the home share. See Adding an SMB Home Share for more information.
Time Machine
Enables Apple Time Machine backups on this share. This option requires SMB2/3 protocol extension support. You can enable this in the general SMB server configuration.
Legacy AFP Compatibility
Select to enable the share to behave like the deprecated Apple Filing Protocol (AFP). Leave cleared for the share to behave like a normal SMB share. This option controls how the SMB share reads and writes data. Only enable this when this share originated as an AFP sharing configuration. You do not need legacy compatibility for pure SMB shares or macOS SMB clients. This option requires SMB2/3 protocol extension support. You can enable this in the general SMB server configuration.
Enable Shadow Copies
Select to export ZFS snapshots as Shadow Copies for Microsoft Volume Shadow Copy Service (VSS) clients.
Export Recycle Bin
Select to enable. Deleted files are renamed to a per-user subdirectory within the .recycle directory at either the root of the SMB share if the path is the same dataset as the SMB share (default is share and dataset have the same name), or at the root of the current dataset if datasets are nested. Nested datasets do not have automatic deletion based on file size. Do not rely on this function for backups or replacements of ZFS snapshots.
Use Apple-style Character Encoding
Select to convert NTFS illegal characters in the same manner as macOS SMB clients. By default, Samba uses a hashing algorithm for NTFS illegal characters.
Enable Alternate Data Streams
Select to allow multiple NTFS data streams. Disabling this option causes macOS to write streams to files on the file system.
Enable SMB2/3 Durable Handles
Select to allow using open file handles that can withstand short disconnections. Support for POSIX byte-range locks in Samba is also disabled. We do not recommend this option when configuring multi-protocol or local access to files.
Enable FSRVP
Select to enable support for the File Server Remote VSS Protocol (FSVRP). This protocol allows remote procedure call (RPC) clients to manage snapshots for a specific SMB share. The share path must be a dataset mount point. Snapshots have the prefix fss- followed by a snapshot creation timestamp. A snapshot must have this prefix for an RPC user to delete it.
Path Suffix
Appends a suffix to the share connection path. Use to provide individualized shares on a per-user, per-computer, or per-IP address basis. Suffixes can contain a macro. See the smb.conf manual page for a list of supported macros. The connect path must be preset before a client connects.
Additional Parameters String
Shows a string of parameters associated with the share preset selected, or if no preset, enter additional smb4.conf parameters not covered by the TrueNAS API.
Advanced Options Presets
The Purpose setting you select in the Basic Options affects which Advanced Options settings (presets) you can select.
Some presets are available or locked based on your choice.
The expandable below provides a comparison table listing these presets and shows whether the option is available or locked.
What do all the presets do?
The following table shows the preset options for the different Purpose options and if those are locked.
A check_box indicates the option is enabled while check_box_outline_blank means the option is disabled. [ ] indicates empty text fields, and [%U] indicates the option the preset created.
Setting
Default Share Parameters
Multi-User Time Machine
Multi-Protocol (NFSv3/SMB) Shares
Private SMB Datasets and Shares
SMB Files become Read Only after 5 minutes
Enable ACL
check_box (locked)
check_box
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
Export Read Only
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Browsable to Network Clients
check_box (locked)
check_box
check_box
check_box
check_box
Allow Guest Access
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Access Based Share Enumeration
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Hosts Allow
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Hosts Deny
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Use as Home Share
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Time Machine
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Enable Shadow Copies
check_box (locked)
check_box
check_box
check_box
check_box
Export Recycle Bin
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Use Apple-style Character Encoding
check_box_outline_blank (locked)
check_box_outline_blank
check_box
check_box
check_box
Enable Alternate Data Streams
check_box (locked)
check_box
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
Enable SMB2/3 Durable Handles
check_box (locked)
check_box
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
Enable FSRVP
check_box_outline_blank (locked)
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
check_box_outline_blank
Path Suffix
[ ] (locked)
[%U] (locked)
[%U]
[%U] (locked)
[ ] (locked)
[Back to Advanced Options Settings](#advanced-options-settings)
Edit Share ACL Screen
The Share ACL for sharename screen opens when you click the shareEdit Share ACL icon on the Windows (SMB) Shares widget or the more_vert on the Sharing SMB details screen.
These settings configure new ACL entries for the selected SMB share and apply them at the entire SMB share level. It is separate from file system permissions.
ACL Entries are listed as a block of settings. Click Add to add a new entry.
Setting
Description
SID
Shows the SID trustee value (who) this ACL entry (ACE) applies to. SID is a unique value of variable length that identifies the trustee. Shown as a Windows Security Identifier. Click Save and re-open Edit Share ACL to update.
Who
Select the domain for account (who) this ACL entry applies to. Options are:
User - Select to show the User field. Enter or select from the dropdown a user (who) this ACL entry applies to, shown as a user name.
Group - Select to show the Group field. Enter or select from the dropdown a group (who) this ACL entry applies to, shown as a group name.
everyone - Select to apply the ACL entry to everyone.
Permission
Select predefined permission combinations from the dropdown list. Options are:
FULL - Select to grant read access, execute permission, write access, delete objects, change permissions, and take ownership (RXWDPO) permissions.
CHANGE - Select to grant read access, execute permission, write access, and delete object (RXWD) permissions.
READ - Select to grant read access and execute permission on the object (RX). For more details, see smbacls(1).
Type
Select the option from the dropdown list that specifies how TrueNAS applies permissions to the share. Options are:
ALLOWED - Select to deny all permissions by default, except manually defined permissions.
DENIED - Select to allow all permissions by default, except manually defined permissions.
Save stores the share ACL and immediately applies it to the share.
Edit Filesystem ACL Screen
The Edit Filesystem ACL option opens the Edit ACL screen for the dataset the share uses.
See Edit ACL Screen more information on the settings found on this screen.
Use the ACL editor screen to set filesystem permissions for the shared dataset.
See Permissions for more information on configuring permissions.
SMB Status Screens
You can access the SMB Status screen from the SMB option on the System > Services screen with the list icon and from the more_vert on the Shares > Windows (SMB) Shares widget.
Refresh updates the information displayed on the selected tab.
Column displays a dropdown list of options for the selected tab to customize the information included on the screen.
Click Sharing or SBM on the top breadcrumb to open the selected screen.
The breadcrumb displays when you access the SMB Status screen from the System > Services SMB row.
NFS Shares Screens
The Sharing screen opens after you click Shares on the main navigation panel.
Unix (NFS) Share Widget
The Unix (NFS) Share launch widget includes the widget toolbar that displays the status of the NFS service and the Add button.
After adding NFS shares, the widget displays a list of the shares below the toolbar.
The toolbar displays the STOPPED service status in red before you start the service or click Enable Service when the dialog displays.
When service starts, it displays RUNNING in blue.
Sharing NFS Details Screen
The Sharing > NFS details screen displays the same list of NFS shares as the Unix (NFS) Share widget.
Customize the information using the Columns dropdown list.
Select from the Unselect All,Description, Enabled, and Reset to Defaults options.
Select Confirm and then UNSHARE to remove the share without affecting the data in the shared dataset.
Add and Edit NFS Screens
The Add NFS and Edit NFS display the same Basic Options and Advanced Options settings.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Basic Options Settings
The Basic Options settings display by default and also show in the Advanced Options settings.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Enter the path or use the arrow_right icon to the left of /mnt to locate the dataset and populate the path. Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
/mnt
Click the arrow_right icon to expand the path at each dataset until you get to the SMB share dataset you want to use. This populates the Path.
Create Dataset
Click to open the Create Dataset dialog. Enter a name to create a new dataset for the share. Click Create to add the dataset and populate the Name field on the Add NFS screen.
Description
Enter any notes or reminders about the share.
Enabled
Select to enable this NFS share. Clear the checkbox to disable this NFS share without deleting the configuration.
Networks
Click Add to display the Networks IP address and CIDR fields. Enter an allowed network IP and select the mask CIDR notation. Click Add for each network address and CIDR you want to define as an authorized network. Defining an authorized network restricts access to all other networks. Leave empty to allow all networks.
Add hosts
Click Add to display the Authorized Hosts and IP addresses field. Enter a host name or IP address to allow that system access to the NFS share. Click Add for each allowed system you want to define. Defining authorized systems restricts access to all other systems. Leave the field empty to allow all systems access to the share.
Advanced Options Settings
Advanced Options settings tune the share access permissions and define authorized networks.
Only the Access settings display on the Advanced Options screen.
Enter a string or select a user from the dropdown to apply permissions for that user to the root user.
Maproot Group
Enter a string or select a group from the dropdown to apply permissions for that group to the root user.
Mapall User
Enter a string or select a user to apply permission for the chosen user to all clients.
Mapall Group
Enter a string or select a group to apply permission for the chosen group to all clients.
Security
Select a security option from the dropdown list. Options are SYS, KRB5, KRB5I, KRB5P. Selecting KRB5 allows you to use a Kerberos ticket.
Security Types
Setting
Description
SYS
Uses locally acquired UIDs and GIDs. No cryptographic security.
KRB5
Uses Kerberos for authentication.
KRB5I
Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity.
KRB5P
Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load.
NFS Sessions Screen
You can access the NFS Sessions screen from the NFS option on the System > Services screen with the list icon and from the more_vert on the Shares > Unix (NFS) Shares widget.
The NFS Sessions screen shows current NFS sessions.
Refresh updates the information displayed on the screen.
Column displays a dropdown list of options for the selected tab to customize the information included on the screen.
Click Sharing on the top breadcrumb to open the Shares dashboard.
Block (iSCSI) Share Target Screens
The Sharing screen opens after you click Shares on the main navigation panel.
Block (iSCSI) Shares Targets Widget
The Block (iSCSI) Shares Targets widget displays the widget toolbar with the status of the iSCSI service.
Click Configure to open the iSCSI screen on the Target Global Configuration tab.
Click Wizard to open the Wizard iSCSI screen.
After adding an iSCSI target or share, the widget toolbar displays the STOPPED service status in red and includes the share below.
Before you add your first iSCSI block share, click anywhere on Block (iSCSI) Shares Targets launch to open the Sharing > iSCSI screen with the Targets iSCSI configuration tab displayed.
Click Add in the top right or Add Target in the middle of the screen to open the Add ISCSI Target screen.
Click Wizard to open the Wizard iSCSI screen. After adding a block share, the widget displays shares below the toolbar.
The No Targets screen opens only when the system does not have an iSCSI target configured on the system.
The more_vert on the toolbar displays options to turn the iSCSI service on or off.
Turn Off Service displays if the service is running. Otherwise, Turn On Service displays.
The Config Service option opens the configuration tabs Target Global Configuration screen.
If you have other share types added to your TrueNAS system, the widget displays as a card on the Sharing screen.
View Details also opens the iSCSI configuration tabs. Each tab includes details on the block shares added to the system.
Basic Info Settings
Setting
Description
Target Name
Required. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Target Alias
Enter an optional user-friendly name.
iSCSI Group Settings
To display the iSCSI Group settings, click Add.
Setting
Description
Portal Group ID
Required if specifying an iSCSI Group. Select the number of the existing portal to use. This is the portal group ID created in Portals.
Initiator Group ID
Select the existing initiator group ID that has access to the target from the dropdown list of options. When initiator groups exist, the dropdown populates with options to select a created group by ID, allow all groups, or allow no groups.
Authentication Method
Select the method from the dropdown list of options. None, CHAP or Mutual Chap. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP you must enter or create a new group in Discovery Authentication Group.
Authentication Group Number
Select the option from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses.
iSCSI Configuration Screens
The iSCSI configuration screens display seven tabs, one for each of the share configuration areas.
The Add button at the top of the Sharing > iSCSI screen works with the currently selected tab or screen. For example, if Portals is the current tab/screen, the Add button opens the Add Portal screen.
The more_vert on configure tab screens with list views display the Edit and Delete options. Edit opens the Edit screen for the selected tab screen. For example, when on the Portals tab/screen, the Sharing > iSCSI > Portals > Edit screen opens.
The Delete option opens the delete dialog for the screen currently selected.
The Add and Edit screens display the same settings.
Target Global Configuration Screen
The Target Global Configuration displays configuration settings that apply to all iSCSI shares.
There are no add, edit, or delete options for this screen.
It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
Setting
Description
Base Name
Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
ISNS Servers
Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Pool Available Space Threshold (%)
Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port
The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators.
Asymmetric Logical Unit Access (ALUA)
Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server.
Portals Screens
The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
The more_vert next to the portal displays the Edit and Delete options.
Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
Basic Info Settings
Setting
Description
Description
Enter an optional description. Portals are automatically assigned a numeric group.
Authentication Method and Group Settings
Setting
Description
Discovery Authentication Method
Select the discovery method you want to use for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None, you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP, you must enter or create a new group in Discovery Authentication Group.
Discovery Authentication Group
Select the discovery authentication group you want to use from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is CHAP or Mutual CHAP. Select None or Create New. Create New displays additional setting options.
IP Address Settings
Setting
Description
IP Address
Select the IP addresses the portal listens to. Click Add to add IP addresses with a different network port. 0.0.0.0 listens on all IPv4 addresses, and :: listens on all IPv6 addresses.
Port
TCP port used to access the iSCSI target. The default is 3260.
Add
Adds another IP address row.
Initiators Groups Screen
The Initiators Groups screen display settings to create new authorized access client groups or edit existing ones in the list.
The more_vert next to the initiator group displays the Edit and Delete options.
Delete opens the Delete dialog for the selected group ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Sharing > iSCSI > Initiators > Add screen. Edit opens the Sharing > iSCSI > Initiators > Edit screen. Both screens have the same setting options.
Setting
Description
Allow All Initiators
Select to allows all initiators.
Allowed Initiators (IQN)
Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description
Enter any notes about the initiators.
Authorized Access Screen
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Add opens the Add Authorized Access screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Authorized Access screen, and Delete opens a dialog to delete the authorized access for the selected user.
The Add and Edit screens display the same settings.
Group Settings
Setting
Description
Group ID
Enter a number. This allows configuring different groups with different authentication profiles. Example: all users with a group ID of 1 inherit the authentication profile associated with Group 1.
User Settings
Setting
Description
User
User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret
Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a “password does not match” error until you enter the same password in Secret (Confirm).
Secret (Confirm)
Enter the same password to confirm the user password.
Peer User Settings
Setting
Description
Peer User
Optional. Enter only when configuring mutual CHAP. Usually the same value as User.
Peer Secret
Enter the mutual secret password. Required if entering a Peer User. Must be a different password than the password in Secret.
Peer Secret (Confirm)
Enter the same password to confirm the mutual secret password.
Targets Screen
The Targets screen displays settings to create new TrueNAS storage resources or edit existing ones in the list.
Add opens the Add iSCSI Targets screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit iSCSI Targets screen, and Delete opens a dialog to delete the select target.
The Add iSCSI Targets and Edit iSCSI Targets screens display the same settings.
Add and Edit iSCSI Target Screens
The Add iSCSI Target and Edit iSCSI Target screens display the same settings, but the current settings populate the Edit iSCSI Target screen settings for the selected share.
To access the Add iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click Add at the top of the screen.
To access the Edit iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click more_vert next to the share and then click Edit.
Extents Screen
The Extents screen displays settings to create new shared storage units or edit existing ones in the list.
Add opens the Add Extent screen.
The more_vert next to each entry opens two options, Edit and Delete. Edit opens the Edit Extent screen, and Delete opens a dialog to delete the extents for the selected user.
The Add and Edit screens display the same settings.
Basic Info Settings
Setting
Description
Name
Enter a name for the extent. An Extent where the size is not 0, cannot be an existing file within the pool or dataset.
Description
Enter any notes about this extent.
Enabled
Select to enable the iSCSI extent.
Type Settings
Setting
Description
Extent Type
Select the extent (zvol) option from the dropdown list. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file.
Device
Required. Displays if Extent Type is set to Device. Select the unformatted disk, controller, or zvol snapshot.
Path to the Extent
Displays when Extent Type is set to File. Click the play_arrow to browse an existing file. Create a new file by browsing to a dataset and appending /{filename.ext} to the path. Users cannot create extents inside a jail root directory.
Filesize
Only appears if File is selected. Entering 0 uses the actual file size and requires that the file already exists. Otherwise, specify the file size for the new file.
Logical Block Size
Enter a new value or leave it at the default of 512 unless the initiator requires a different block size.
Disable Physical Block Size Reporting
Select if the initiator does not support physical block size values over 4K (MS SQL).
Compatibility Settings
Setting
Description
Enable TPC
Select to allow an initiator to bypass normal access control and access any scannable target. This allows xcopy operations that are otherwise blocked by access control.
Xen initiator compat mode
Select when using Xen as the iSCSI initiator.
LUN RPM
Select the option from the dropdown list. Options are UNKNOWN, 5400, 7200, 10000 or 15000. Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics.
Read-only
Select to prevent the initiator from initializing this LUN.
Associated Targets Screen
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user.
The Add and Edit screens display the same settings.
Setting
Description
Target
Required. Select an existing target.
LUN ID
Select the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID.
Extent
Required. Select an existing extent.
Data Protection
The Data Protection screen allows users to set up multiple redundant tasks that protect and/or backup data in case of drive failure.
Scrub tasks and S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) tests 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.
Replication Task Screens: Provides information on the Replication screens, wizard, and settings used to add or edit replication tasks.
TrueCloud Backup Tasks Screens
The TrueCloud Backup Tasks widget on the Data Protection screen shows configured TrueCloud tasks, and provides access to configuration screens to add or schedule recurring transfers between TrueNAS SCALE and a cloud storage provider account like Storj iX.
TrueCloud backup tasks effectively back up data to remote locations, restore snapshots, and perform cloud-storage migration.
TrueCloud Backup Tasks Widget
The TrueCloud Backup Tasks widget shows a list of tasks configured on the system.
play_arrowRun Now starts and runs the backup task outside of the scheduled time.
visibility View Details opens the TrueCloud Backup Tasks screen that lists backup tasks configured on the system. Click on a task to see details for the selected task.
deleteDelete opens a confirmation dialog before the system deletes the task.
State shows the status of the previous or current task. Possible status indications are:
SUCCESS for completed tasks.
FAILED if the task fails to complete.
RUNNING for tasks in progress.
N/A for scheduled tasks before they run.
TrueCloud Logs Dialog
The state oval opens the Logs dialog for that task.
Download Logs saves a copy of the current task logs.
The TrueCloud Backup Tasks screen lists all tasks configured on the system.
The TrueCloud Backup Tasks open_in_new on the widget title or visibility View Details on a task opens the TrueCloud Backup Tasks screen.
play_arrowRun Now starts and runs the backup task outside of the scheduled time.
deleteDelete opens a confirmation dialog before the system deletes the task.
Select any task to see details for the configured task, such as the schedule, path to the dataset or directories, snapshots, and other task options.
Snapshots Widget
The Snapshots widget lists existing TrueCloud snapshots for the selected backup task.
It contains options to restore from or delete an existing snapshot.
deleteDelete opens a confirmation dialog before the system deletes the snapshot.
Restore from Snapshot Screen
The Restore from Snapshot screen shows the date and time of the selected snapshot.
It shows Remote and Local configuration options to restore the TrueCloud snapshot.
Remote Settings specify all data in the backup or exclude some data from a restoration.
Additional settings show depending on the Include/Exclude selection.
Settings
Description
Include Everything
Select to restore all backed-up data from the remote snapshot to the selected local path.
Include from subfolder
Select to restore data from a subfolder within the backed-up data.
Subfolder
Shows when Include from subfolder is selected. Enter or browse to the subfolder within the snapshot with the data to restore.
Included Paths
Shows when Include from subfolder is selected. Select files and directories to include from the backup. Leave empty to include everything in the selected subfolder.
Select paths to exclude
Select to exclude only certain paths from the data to restore.
Excluded Paths
Shows when Select paths to exclude is selected. Enter or select files and directories to exclude from the backup. Select as many checkboxes as desired to select multiple paths or separate multiple entries with a comma.
Exclude by pattern
Select to exclude files and directories matching defined glob patterns.
Pattern
Shows when Exclude by pattern is selected.
Local Settings
Use Local settings to select the target mount point on the current (local) system where files are restored.
Be cautious when setting the restore target to avoid overwriting existing files.
Target settings allow entering the path to the dataset or directory or browse to the location to populate the field with the local directory where files are restored.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
create_new_folder Create Dataset opens a dialog to name and create a new dataset at the selected target.
Save starts restoring data from the snapshot.
Add and Edit TrueCloud Backup Task Screen
The Add TrueCloud Backup Task and Edit TrueCloud Backup Task screens contain options to configure a new backup task.
The edit screen opens populated with the existing task settings.
Each screen shows the Local, Remote, Task Settings, and Control settings.
The Advanced and Advanced Remote Options are for advanced users.
Local settings set the dataset or directory used in the task. Selecting the dataset populates the Source Path field.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Enter or browse to select the dataset or directory with the data to send to the cloud backup provider set in the task. Click the arrow_right arrow to the left of the /mnt folder to expand and show datasets and directories within that folder. This is the dataset or directory location with the data the TrueCloud backup task sends to the cloud storage provider. Click the arrow_right arrow to the left of the /mnt folder again to collapse the directory tree.
Remote Settings
The Remote settings specify the TrueCloud credential and destination storage locations.
Settings
Description
Credential
Select an existing Storj iX credential from the dropdown list. TrueNAS automatically validates the selected credential. Select Add New to open the Cloud Credentials screen. This is the same configuration screen that opens when you click Add on the Credentials > Backup Credentials screen.
Bucket
Displays after selecting the Storj credential. Select a pre-configured Storj bucket. Only TrueNAS-compatible Storj buckets are selectable. Select Add New to create a new Storj bucket from the TrueNAS UI.
New Bucket Name
Displays when Add New is selected in the Bucket field. Enter a name for the new bucket. Only lowercase letters, numbers, and hyphens are allowed.
Folder
Enter or browse to select the dataset or directory to receive the backed-up data. Click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task. Enter /name, where name is a folder that does not exist, to create a new folder in the bucket.
Task Settings
Task Settings specify the task name, snapshot retention policy, and password for the backup repository.
Settings
Description
Name
Enter a name for the TrueCloud backup task.
Keep Last
Enter a number for the past snapshot copies to retain before removing older snapshots.
Password
Enter a password for the backup repository. Record this password in a secure location. Required to recreate the task using the same bucket/folder, such as in a new TrueNAS install or system, or to restore data from the existing snapshots in another TrueNAS system.
Control Settings
Control settings establish a schedule for when to run the backup task.
Settings
Description
Schedule
Select a schedule preset or choose Custom to open the advanced scheduler.
Enabled
Select to enable the TrueCloud task. Leave clear to disable the task without deleting it and keep the configuration available without allowing the specified schedule to run the task. The toggle in the Enable column on the TrueCloud Backup Tasks widget enables/disables the task.
Advanced Scheduler
Choosing a Presets option populates 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.
The TrueNAS UI does not have a Minutes field, but you can specify minutes within the Hours field using the CRON syntax described below.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
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 and 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.
Advanced Options Settings
Advanced Options settings are intended for advanced users.
(For advanced users only) Enter a script to execute before running the task. See the Managing TrueCloud Backup Tasks tutorial for more information. See Script Environment Variables below for a list of variables for scripts.
Post-Script
(For advanced users only) Enter a script to execute after running the task. See the Managing TrueCloud Backup Tasks tutorial for more information. See Script Environment Variables below for a list of variables for scripts.
Exclude
Enter a list of files and directories to exclude from the backup. Separate entries by pressing Enter. See restic exclude patterns for more information about the --exclude option and proper syntax.
Use Absolute Paths
Select to ensure that restic backups will contain absolute paths. If you don’t check this box, the restic backup will contain relative paths.
Take Snapshot
Select to set the TrueCloud Backup Task to take a snapshot of the dataset before a push.
Script Environment Variables
The following environment variables can be used in pre and post-scripts.
CLOUD_BACKUP_ID
CLOUD_BACKUP_DESCRITPION
CLOUD_BACKUP_PASSWORD
CLOUD_BACKUP_KEEP_LAST
CLOUD_BACKUP_TRANSFER_SETTING
CLOUD_BACKUP_ACCESS_KEY_ID
CLOUD_BACKUP_FOLDER
CLOUD_BACKUP_BUCKET
CLOUD_BACKUP_FAST_LIST (always zero (0) for false, planned removal in Fangtooth)
Advanced Remote Options
Advanced Remote Options settings are intended for advanced users.
Settings
Description
Transfer Settings
Select the option from the dropdown list to set the number of simultaneous file transfers to allow. Options:
Default - Select to use the Restic PACK_SIZE of 16 Mib and READ_CONCURRENCY to two files.
Perfromance - Select to set the Restic PACK_SIZE to 29 MiB and READ_CONCURRENCY to two files.
Fast Storage - Select to set the Restic PACK_SIZE to 58 MiB and READ_CONCURRENCY to 100 files.
Scrub Tasks Screens
The Data Protection screen Scrub Task widget displays a list of scrub tasks configured on the system. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts.
TrueNAS generates a default scrub task when you create a new pool and sets it to run every Sunday at 12:00 AM.
Add opens the Add Scrub Task screen.
Each task is a link that opens the Edit Scrub Task Screen.
The delete icon opens a delete confirmation dialog.
Add and Edit Scrub Task Screen
The Add Scrub Task and Edit Scrub Task screens display the same settings that specify the pool, threshold, and schedule for when to run the ZFS scan on the data in a pool.
Setting
Description
Pool
Select the pool to scrub from the dropdown list.
Threshold days
Enter the number of days before a completed scrub is allowed to run again. This controls the task schedule. For example, scheduling a scrub to run daily with Threshold days set to 7 means the scrub attempts to run daily. When the scrub succeeds, it continues to check daily but does not run again until seven days elapse. Using a multiple of seven ensures the scrub always occurs on the same weekday.
Description
Enter a description for this scrub tasks.
Schedule
Select a preset from the dropdown list that runs the scrub task according to that schedule time. Select Custom to use the advanced scheduler.
Enabled
Select to enable the scrub task to run. Leave checkbox clear to disable the task without deleting it.
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.
The TrueNAS UI does not have a Minutes field, but you can specify minutes within the Hours field using the CRON syntax described below.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
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 and 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.
Scrub/Resilver Priority Screen
The settings specify times when new resilver tasks can start, and run, at a higher priority or when a resilver task cannot run at a lower priority.
Select Enabled, then use the dropdown lists to select a start time in Begin and time to finish in End to define a priority period for the resilver.
To select the day(s) to run the resliver, use the Days of the Week dropdown to select when the task can run with the priority given.
A resilver process running during the time frame defined between the beginning and end times likely runs faster than during times when demand on system resources is higher.
We advise you to avoid putting the system under any intensive activity or heavy loads (replications, SMB transfers, NFS transfers, Rsync transfers, S.M.A.R.T. tests, pool scrubs, etc) during a resilver process.
Cloud Sync Tasks Screens
The Cloud Sync Tasks widget on the Data Protection screen shows configured cloud sync tasks, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS SCALE and a cloud storage provider.
Cloud sync tasks are an effective method to back up data to a remote location, or to perform cloud-storage-migration through a provider.
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
Each task includes five icons for various functions:
The editEdit icon opens the Edit Cloud Sync Task screen populated with with the settings for that task.
The play_arrowRun Now icon starts the cloud sync, running it outside of the scheduled time.
The loopDry Run icon performs the same function as the Dry Run button on the add and edit configuration screens. It performs a test of the configured settings.
When doing a dry run, you can close the window and monitor the task using the Jobs option on the top toolbar.
The restoreRestore icon creates a new cloud sync task from an existing task.
The new task has the same settings but reverses the data transfer.
The deleteDelete icon opens a confirmation dialog before the system deletes the task.
State displays the status of the next cloud sync task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Expand any task to see details on the configured task, such as the cloud sync provider, direction, transfer mode, path to the dataset or directories, and other options for that task.
Buttons for these task options perform the same functions as the icons on the widget:
Run Now starts the task outside of the scheduled period.
Dry Run performs a test of the configuration.
This is the same function as the Dry Run button on the Edit Cloud Sync Task screen and the Advanced Options for the Cloudsync Task Wizard.
Restore opens the Restore Cloud Sync Task window where you can create a new cloud sync task from an existing task with the same options but the new task reverses the transfer from PUSH to PULL and vice-versa.
Delete opens a dialog where you confirm the action before the system deletes the task.
Cloudsync Task Wizard
The Cloud Sync Task wizard screens simplify the task creation process.
It includes two screens, Provider and What and When.
Provider Wizard Screen
The Provider wizard screen allows you to select the cloud sync provider with the Credentials dropdown.
Select the provider from the dropdown list to show the additional credential settings that the provider requires to establish a connection.
Select Add New to open the Cloud Credentials screen. This is the same configuration screen as when you click Add on the Credentials > Backup Credentials screen.
Advanced Options opens a screen with the same settings as the Edit Cloud Sync Task screen.
Verify Credentials tests the settings before you advance to the settings on the What and When wizard screen.
What and When Wizard Screen
The What and When screen sets the direction (PUSH or PULL), transfer mode (move, copy, or sync), the datasets or directories source and destination, and sets the schedule for the transfer.
The Bucket field displays for providers that use buckets to hold transferred files, folders, etc.
The Advanced Options button shows at the bottom of this screen as well.
Advanced Options and Edit Cloud Sync Task Screens
The Advanced Options accessed from the Cloudsync Task Wizard and Edit Cloud Sync Task display the same settings.
Settings are grouped into Transfer, Remote, Control, and Advanced Options.
Transfer settings change the cloud sync task direction (PUSH or PULL), data transfer method (COPY, MOVE, or SYNC), and allow selecting the dataset or directory to use in the task. Selecting the dataset or file populates the Directory/Files field.
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Select a direction option from the dropdown list. PUSH sends data to cloud storage. PULL receives data from cloud storage and is the default setting.
Transfer Mode
Select the transfer mode type from the dropdown list. There are three options:
COPY - Select to duplicate each source file into the destination. If files with the same names are present on the destination, they are overwritten.
MOVE - Select to transfer files from the source to the destination and delete source files. Copies files from the source to the destination and then deletes them from the source. Files with the same names on the destination are overwritten.
SYNC - Select to change files on the destination to match those on the source. If a file does not exist on the source, it is also deleted from the destination.
Directory/Files
Enter or click the arrow_right arrow to the left of /mnt folder to expand and show datasets and directories within that folder. When you locate the dataset or directory location to send to the cloud for push syncs, or as the destination to write to for pull syncs. Be cautious with pull destinations to avoid overwriting existing files. Click the arrow_right arrow to the left of /mnt folder again to collapse the directory tree.
Remote Settings
The Remote settings specify the cloud sync provider and destination storage locations.
The option selected in Credential changes settings displayed in the Remote settings area.
The Manage Credentials link opens the Backup Credentials screen where you can add a new provider credential.
Settings
Description
Credential
Select an existing backup cloud storage provider credential from the dropdown list. A Bucket setting displays after selecting a credential that uses S3, like Amazon S3. TrueNAS automatically validates the selected credential.
Bucket
Select the pre-defined bucket S3 to use. For Storj-iX credentials, select Add New to open the Add Bucket screen and create a new bucket on your Storj account from the TrueNAS UI.
Folder
Enter or click the arrow_right arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task.
Add Bucket Screen
The Add Bucket screen opens when Add New is selected from the Bucket dropdown in Remote Settings.
It is only available for Storj-iX provider credentials.
Click Save on the Add bucket screen to create the remote bucket on Storj and then return to the Cloud Sync Task Wizard.
Control Settings
Control settings establish a schedule for when the cloud sync task occurs.
Settings
Description
Schedule
Select a schedule preset or choose Custom to open the advanced scheduler.
Enabled
Select to enable this cloud sync task. Leave clear to disable the task without deleting it and keep the configuration available without allowing the specified schedule to run the task. You can use the toggle in the Enable column on the Cloud Sync Tasks widget to enable or disable the task.
Advanced Scheduler
Choosing a Presets option populates 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.
The TrueNAS UI does not have a Minutes field, but you can specify minutes within the Hours field using the CRON syntax described below.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
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 and 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.
Advanced Options Settings
Advanced Options settings are for advanced users.
Selecting Push in Direction adds the Take Snapshot option in Advanced Options.
Displays if Direction is set to Push. Select to take a snapshot before transferring data to the cloud storage provider.
Create empty source dirs on destination after sync
Select to create an empty source directory in the cloud storage provider folder when pushing data to the cloud provider location, or in TrueNAS if pulling data from the cloud storage provider.
Follow Symlinks
Select to follow symbolic links (symlinks) and copy the items to which they link.
Pre-Script
For advanced users. Enter a script to execute before running sync. See the Cloud Sync tutorial for more information.
Post-Script
For advanced user. Enter a script to execute after running sync. See the Cloud Sync tutorial for more information.
Exclude
Enter a list of files and directories to exclude from sync. Separate entries by pressing Enter. Examples of proper syntax to exclude files/directories are:
photos</code> excludes a file named photos
/photos> excludes a file named photos from root directory (but not subdirectories)
photos/ excludes a directory named *photos
/photos/ excludes a directory named photos from root directory (but not subdirectories).
See rclone filtering for more details about the --exclude option.
Advanced Remote Options
The Advanced Remote Options settings are for advanced users to configure remote encryption and transfer bandwidth speed and limit.
Select to use rclone crypt encryption during pull and push transfers. Selecting PUSH in Direction encrypts files before transfer and stores the encrypted files on the remote system. Files are encrypted using the encryption password and encryption salt values. Selecting PULL decrypts files stored on the remote system before the transfer. Transferring the encrypted files requires entering the same encryption password and encryption salt used to encrypt the files. Additional details about the encryption algorithm and key derivation are available in the rclone crypt File formats documentation. Selecting Remote Encryption shows the Filename Encryption, Encryption Password, and Encryption Salt settings.
Filename Encryption
Not recommended (see below). Shows after selecting Remote Encryption. When selected, transfers encrypt and decrypt file names with the rclone Standard file name encryption mode. The original directory structure of the files is preserved. When enabled, file names are encrypted, file names are limited to 143 characters, directory structure is visible, and files with identical names have identical uploaded names. File names can use sub-paths, single-copy files, and shortcuts to shorten the directory recursion. When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, and you can use sub-paths, and copy single files.
Encryption Password
Shows after selecting Remote Encryption. Enter the password to encrypt and decrypt remote data. Warning: Always securely back up this password! Losing the encryption password results in data loss.
Encryption Salt
Shows after selecting Remote Encryption. Enter a long string of random characters for use as salt for the encryption password. Warning: Always securely back up the encryption salt value! Losing the salt value results in data loss.
Transfers
Select the option for the number of simultaneous file transfers based on the available bandwidth and destination system performance from the dropdown list. Options: Low Bandwidth(4), Medium Bandwidth (8), High Bandwidth(16), and Custom. See rclone –transfers.
Bandwidth limit
Enter a single bandwidth limit or bandwidth limit schedule in rclone format. For example: 08:00,512 12:00,10MB 13:00,512 18:00,30MB 23:00,off. Separate entries by pressing Enter. You can specify units with the beginning letter b, k (default), M, or G. See rclone –bwlimit.
We do not recommend enabling Filename Encryption for any cloud sync tasks that did not previously have it enabled.
Users with existing cloud sync tasks that have this setting enabled must leave it enabled on those tasks to be able to restore those existing backups.
Do not enable file name encryption on new cloud sync tasks!
Rsync Tasks Screens
The Rsync Task widget on the Data Protection screen shows configured rsync tasks configured on the TrueNAS system, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS SCALE and an rsync backup server.
Rsync tasks are an effective method to back up data to a remote location.
Rsync Task Widget
The Rsync Tasks widget shows a list of tasks configured on the system.
Each task includes three icons for various functions:
The editEdit icon opens the Edit Rsync Task screen populated with with the settings for that task.
The play_arrowRun Now icon starts the rsync, running it outside of the scheduled time.
The deleteDelete icon opens a confirmation dialog before the system deletes the task.
State displays the status of the next cloud sync task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Each task shows details about the configured task and the same icon buttons found on the Rsync Task widget to run the task outside of the scheduled time, edit, or delete the task.
Add and Edit Rsync Task Screens
The Add Rsync Task and Edit Rsync Task screens display the same settings.
Source and Remote Options
Source settings specify the location of the stored data to sync with a remote server, sets the user that performs the task, and the direction of the task (send or receive data).
The Remote settings specify the mode for the task and remote host connection information.
Settings change base on the Rsync Mode selected (Module or SSH).
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
(Required) Enter or browse to the dataset or directory to sync with a remote server. Use the arrow_right to the left of /mnt folder to expand the folder tree, then click on the name to select and populate the Path field. Linux file path limits apply. Other operating systems can have different limits which might affect how to use them as sources or destinations.
User
(Required) Select the user to run the rsync task. Select a user that has permissions to write to the specified directory on the remote host. If setting Rsync Mode to SSH, the user must have an SSH private key in their home directory if Connect using is set to SSH private key stored in user’s home directory.
Direction
(Required) Select the direction of the flow of data to the remote host. Options are:
Push - During a push, the dataset copies data to the remote module.
Pull - During a pull, the dataset stores data copied from the remote system.
Description
(Optional) Enter a description of the rsync task.
Rsync Mode
Select the mode from the dropdown list. Options are:
Module - Select to use a custom-defined remote module from the rsync server.
SSH - Select to use an SSH configuration for the rsync task. The remote system must have SSH enabled. The host system needs an established SSH connection to the remote for the rsync task. SSH displays more settings.
Remote Host
(Required) Enter the IP address or host name and domain of the remote system. Use the format username@remote_host if the user name differs on the remote host.
Remote Module Name
(Required) If Rsync Mode is set to Module, specify the name of the module on the remote rsync server. Define at least one module per rsyncd.conf(5) on the remote rsync server. Enter the Module Name exactly as it appears on the remote system.
Connect using
(Required) If Rsync Mode is set to SSH, select the connection method from the dropdown list. Options are:
SSH private key stored in user’s home directory - If selected, the user entered in User must have an SSH private key added and stored in the home directory for the user. Create the SSH connection and keypair, download the keys, then add the private key to the user in the UI and to the home directory either from the Shell using Linux CLI commands or while in an SSH session with the system.
SSH connection from the keychain - Requires creating an SSH connection and keypair before setting up the rsync task.
Remote SSH Port
(Required) If Rsync Mode is set to SSH, enter the SSH port number of the remote system. By default, 22 is reserved in TrueNAS.
Remote Path
Enter an existing path on the remote host. Maximum path length is 255 characters.
Validate Remote Path
Shows when Rsync Mode is set to SSH. Select to automatically create the defined Remote Path if it does not exist.
Schedule and More Options
Schedule defines when the remote sync task occurs.
The More Options specify other settings related to when and how the rsync occurs.
Select a schedule preset or choose Custom to open the advanced scheduler.
Recursive
Select to include all subdirectories of the specified directory. When cleared, only the specified directory is included.
Enabled
Select to enable this rsync task. Clear to disable this rsync task without deleting it.
Advanced Scheduler
Choosing a Presets option populates 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.
The TrueNAS UI does not have a Minutes field, but you can specify minutes within the Hours field using the CRON syntax described below.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
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 and 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.
More Options Settings
Setting
Description
Times
Select to preserve modification times of files.
Compress
Select to reduce the size of data to transmit. Recommended for slow connections.
Archive
Select to preserve symlinks, permissions, modification times, group and special files. When selected, rsync runs recursively. When run as root, owner, device files, and special files are also preserved. Equal to passing the flags -rlptgoD to rsync.
Delete
Select to delete files in the destination directory that do not exist in the source directory.
Quiet
Select to suppress informational messages from the remote server.
Preserve Permissions
Select to preserve original file permissions. Useful when the user is set to root.
Preserve Extended Attributes
Select to preserve extended attributes, but this must be supported by both systems.
Delay Updates
Select to save a temporary file from each updated file to a holding directory until the end of the transfer. All transferred files renamed once the transfer is complete.
Auxiliary Parameters
Enter additional rsync(1) options to include. Separate entries by pressing Enter. Note: You must escape the * character with a backslash (\*.txt) or inside single quotes ('*.txt').
Periodic Snapshot Tasks Screens
The Data Protection screen Periodic Snapshot Task widget displays periodic snapshot tasks created on the system.
A periodic snapshot task allows scheduling the creation of read only versions of pools and datasets at a given point in time.
Periodic snapshot tasks display the machine time, browser time, or both depending on individual user timezone settings. Users can update timezone settings by utilizing the General Settings screen.
Periodic Snapshot Task Widget
The Periodic Snapshot Task widget displays a list of tasks configured on the system.
If a periodic snapshot task is not yet configured No Periodic Snapshot Task configured displays in the widget.
VMware Snapshot Integration opens the VMware Snapshots screen.
Snapshots opens the Snapshots screen.
Each task listed is a link that opens the Edit Periodic Snapshot Task screen populated with with the settings for that task. Click on the Description, Frequency, or Next Run column entry to open the edit task screen.
State displays the status of the next cloud sync task. While on the widget, click on the state for the task to display a Logs window for that task. Click Download Logs to save a copy of the current task logs.
The deleteDelete icon opens a simple delete dialog where you confirm before the system deletes the saved periodic snapshot task.
Periodic Snapshot Task List Screen
Periodic snapshot tasks display on both the Data Protection widget and Periodic Snapshot Tasks list screen.
Click Here for More Information
Click on the Periodic Snapshot Task header to open the Data Protection > Periodic Snapshot Task list screen.
If a task is not added, the list view displays Add Periodic Snapshot Tasks which opens the Add Periodic Snapshot Task screen.
Columns displays a dropdown list of options to customize the list view. Options are Select All, Recursive, Naming Schema, When, Frequency, Next Run, Keep snapshot for, VMWare Sync, Enabled, State, and Reset to Defaults.
The State on the list view does not link to the log file or anything else. It just displays the current state of the task.
Click the expand_more expand icon at the right of the task to open the details for the selected task.
Delete opens the delete dialog that removes the task from the system.
Add and Edit Periodic Snapshot Screens
The Add Periodic Snapshot Task and Edit Periodic Snapshot Task display the same settings.
Dataset Options
The Dataset setting options display on both the add and edit configuration screens.
Click Here for More Information
Setting
Description
Dataset
Select a pool, dataset, or zvol.
Exclude
Exclude specific child datasets from the snapshot. Use with recursive snapshots. List paths to any child datasets to exclude. Example: pool1/dataset1/child1. A recursive snapshot of pool1/dataset1 includes all child datasets except child1. Separate entries by pressing Enter.
Recursive
Select to take separate snapshots of the dataset and each of its child datasets. Leave checkbox clear to take a single snapshot only of the specified dataset without child datasets.
Schedule Options
These Schedule setting options display on both the add and edit configuration screens.
Click Here for More Information
Setting
Description
Snapshot Lifetime
Enter the length of time to retain the snapshot on this system using a numeric value and a single lowercase letter for units. Examples: 3h is three hours, 1m is one month, and 1y is one year. Does not accept minute values. After the time expires, the snapshot is removed during the next snapshot scheduled execution finds the snapshot lifetime is expired. Snapshots replicated to other systems are not affected.
Naming Schema
Snapshot name format string. The default is auto-%Y-%m-%d_%H-%M. Must include the strings %Y, %m, %d, %H, and %M, which are replaced with the four-digit year, month, day of month, hour, and minute as defined in strftime(3). For example, snapshots of pool1 with a Naming Schema of customsnap-%Y%m%d.%H%M have names like pool1@customsnap-20190315.0527.
Schedule
Select a presets from the dropdown list. Select Custom to open the advanced scheduler.
Begin
Displays when Schedule is set to Hourly. Enter the hour and minute when the system can begin taking snapshots.
End
Displays when Schedule is set to Hourly. Enter the hour and minute the system must stop creating snapshots. Snapshots already in progress continue until complete.
Allow Taking Empty Snapshots
Select to Create dataset snapshots even when there are no changes to the dataset from the last snapshot. Recommended for long-term restore points, multiple snapshot tasks pointed at the same datasets, or compatibility with snapshot schedules or replications created in TrueNAS 11.2 and earlier. For example, you can set up a monthly snapshot schedule to take monthly snapshots and still have a daily snapshot task taking snapshots of any changes to the dataset.
Enabled
Select to activate this periodic snapshot schedule. To disable this task without deleting it, leave the checkbox cleared.
VMWare Snapshots Screen
Use the VMware Snapshot Integration option on the Data Protection > Periodic Snapshot Tasks widget to create snapshots when you are using TrueNAS SCALE as a VMWare datastore.
See Creating VMWare Snapshots for a detailed tutorial.
VMware Snapshot Integration opens the VMWare Snapshots screen.
Enter the IP address or host name of the VMWare host. When clustering, enter the vCenter server for the cluster.
Username
Enter the user on the VMWare host with permission to snapshot virtual machines.
Password
Enter the password associated with the user entered in Username.
Datastore
Select a VMFS datastore to synchronize with the host from the dropdown list of options. Click Fetch DataStores to populate this list with options from the VMWare host. You must click Fetch Datastores before you click in this field or the creation process fails. Selecting a datastore also selects any mapped datasets.
ZFS Filesystem
Select a TrueNAS ZFS dataset from the dropdown list of options. This field does not populate until you click Fetch Datastores. You must click Fetch Datastores before clicking in this field or the creation process fails.
Click Fetch DataStores to connect TrueNAS SCALE to the VMWare host.
This synchronizes TrueNAS SCALE with the VMWare host and populates the ZFS Filesystem and Datastore dropdown lists with the information from TrueNAS and the VMWare host response.
Configured snapshots show on the VMware Snapshots screen.
The Data Protection screen S.M.A.R.T. Tests widget displays the S.M.A.R.T. tests configured on the system and provides access to create or edit S.M.A.R.T. tests.
S.M.A.R.T. Tests Task Widget
The S.M.A.R.T. Tests widget displays No S.M.A.R.T. Tests configured when no tests are configured on the system.
Click on S.M.A.R.T. Tests widget header to open the S.M.A.R.T. Tests list screen.
S.M.A.R.T. Tests Task List Screen
Use Columns to display options to customize the information displayed in the list screen. Options are Unselect All, Description, Frequency, Next Run, and Reset to Defaults.
Add opens the Add S.M.A.R.T. Test configuration screen.
The more_vert for each test has two options, Edit and Delete.
Edit opens the Edit S.M.A.R.T. Test configuration screen and Delete opens a Delete confirmation dialog.
The delete delete icon on the widget also opens the Delete dialog for the selected S.M.A.R.T. test. Click Confirm to activate Delete.
Add and Edit SMART Test Screens
The Add S.M.A.R.T. Test and Edit S.M.A.R.T. Test configuration screens displays the same settings.
Name
Description
Disks
Select the disks to monitor from the dropdown list.
All Disks
Select to monitor every disk on the system with S.M.A.R.T. enabled. Leave clear to choose individual disks on the Disks dropdown list to include in the test.
Type
Select the test type from the dropdown list. Options are LONG, SHORT, CONVEYANCE or OFFLINE. See smartctl(8) for descriptions of each type. Some types degrade performance or take disks offline.
Description
Enter information about the S.M.A.R.T. test.
Schedule
Select a preset test schedule from the dropdown list. Select Custom to open the advanced scheduler and define a new schedule for running the test.
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.
The TrueNAS UI does not have a Minutes field, but you can specify minutes within the Hours field using the CRON syntax described below.
An asterisk (*) means match all values.
You can set specific time ranges by entering hyphenated number values.
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 and 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.
Replication Task Screens
The Replication Task widget on the Data Protection screen lists replication tasks configured on the TrueNAS system.
Replication tasks work with periodic snapshot tasks to complete the replication.
After scheduling a replication task, the Periodic Snapshot Task widget shows a new task for the newly added replication task.
The delete Delete icon opens a delete confirmation dialog.
State displays the status of the replication task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet.
Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
Replication Tasks Screen
The Replications Tasks screen lists the replication tasks configured on the system.
Columns displays a list of options to customize the list view to add or remove information to the table.
Options are Select All, Name, Direction, Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, Auto, Last Run, State, Enabled, Last Snapshot, and Reset to Defaults.
Before adding replication tasks this screen displays No Replication Tasks and the Add Replication Tasks option that opens the Replication Task Wizard.
Enter a new name for the task and select the location to store the data, then click Restore.
The system creates the new file and displays the task on both the widget and list screen with the PENDING status.
Download encryption keys Option
When a replication task involves a key-encrypted source or destination, the icon shows in the task options.
This downloads any encryption keys to your local system.
Delete Option
The deleteDelete icon opens a delete confirmation dialog.
There are two ways to add a replication task, the wizard and the advanced creation screen.
These two methods share many settings that are described below. The Edit Replication Task screen shows the same settings.
Shared settings are documented in these sections:
Add, or if no replication task exist, Add Replication Tasks opens the wizard.
Replication Task Wizard
The wizard has two screens:
What and Where settings specify the task name, data source and destinations, the type of replication (local or remote), transport options (SSH connection), schema or regular expression that names the snapshot created by the task, and if selected, sets up encryption on the data transfer.
When settings specify when to run the task and how long to retain the replicated snapshots.
Advanced Replication Creation opens the Add Replication Task screen with the same settings found in the wizard and more advanced settings.
What and Where Wizard Screen
The What and Where screen shows settings for both the source and destination information (path to the dataset), the source and destination transfer direction, encryption settings for the data transfer, remote replication SSH connections, naming schema to apply to the snapshot taken through the replication task, and the name for the task.
The Encryption and SSH Connection options show when the source or destination is set to On a Different System.
Encryption applies another layer of protection to the data transfer, it is not the encryption of the data stored or the dataset.
You can use an existing SSH connection created using the Credentials > Backup Credentials > SSH Connection screen or create a new connection through the replication task wizard or screens.
SeeConfigure SSH for more information on adding a Backup Credential SSH credentials.
Settings showing on the wizard screen change based on the Source Location and Destination Location option selected.
On this System (local replication) and On a Different System (remote replication) show settings that apply to or are needed to set up that type of replication.
Browsing to select a path
Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories.
A solid folder icon shows for datasets and an outlined folder for directories.
A selected dataset or directory folder and name shows in blue.
Setting Source Location to On This System and Destination Location to On a Different System and making naming schema choices changes the wizard screen to show all available settings.
Shows a list of previous replication tasks that, when selected, loads settings from the saved replication task. Select an existing snapshot to populate the Source Location, Destination Locations, Source, and Destination fields. Also populates Task Name with a name that is a combination of the source-destination for the selected task.
Source Location
Select the storage location of the original replicated snapshots. Options:
On this System (local replication) - Allows setting On a Different System to a local or remote destination.
On a Different System (remote replication) - When set to On a Different System, the Destination Location automatically changes to On this System and the Destination field displays the path to the snapshot location. For more information on these setting options see Source Location Setting Options.
Source
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Location
Select the storage location for the replicated snapshots. Options are On this System or On a Different System but if Source is set to On a Different System, the Destination Location automatically changes to On this System, and the Destination field displays.
Destination
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree and browse to the dataset location with the snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Destination field and then select another dataset or directory. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
SSH Connection
Shows a list of existing SSH connections saved on the system and the option to add a new SSH connection. Select an existing SSH connection to a remote system or select Create New to open the New SSH Connection window to configure a new SSH connection to a remote system. Shows the Use Sudo for ZFS Commands dialog to enable sudo for SSH sessions.
Use Sudo For Zfs Commands
Select if setting up remote replication tasks when logged in as an admin user.
Recursive
Select to also replicate all snapshots contained within the selected source dataset snapshots. Leave clear to only replicate the selected dataset snapshots.
Replicate Custom Snapshots
Shows after setting Source Location to On this System. Select to replicate snapshots that are not created by an automated snapshot task. After selecting, shows the Also include snapshots with the name setting options. This setting requires setting a naming schema for the custom snapshots through one of the two methods: Naming Schema or Snapshot Name Regular Expression.
Also include snapshots with the name
Select the option to set the snapshot naming pattern as either a naming schema or regular expression. Options:
Naming Schema and Snapshot Name Regular Expression.
Naming Schema
Shows after selecting Naming Schema under Also include snapshots with the name. Enter the pattern of naming custom snapshots to replicate. Enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Naming schema must include %Y, %m, %d, %H and %M. Separate entries by pressing Enter. The number of snapshots matching the patterns displayed on the screen.
Snapshot Name Regular Expression
Shows after selecting Snapshot Name Regular Expression under Also include snapshots with the name. Enter the regular expression the replicated snapshot(s) should match. This option replicates all snapshots with names matching the specified regular expression. Performance on systems with large numbers of snapshots is lower as this process reads snapshot metadata to determine snapshot creation order. Naming of regular expressions include name followed this pattern, *“auto-[0-9-]+
SSH Transfer Security
Shows after selecting Replicate Custom Snapshots. Applies data transfer security. Shows two options: Encryption (more secure, but slower) and No Encryption (less secure, but faster). The connection is authenticated with SSH. Encryption is recommended but can be disabled for increased speed on secure networks.
Encryption
Select to apply an extra layer of encryption on the data transfer when replicating data. For more information on all options see Encryption below.
Task Name
Shows the name the system adds from the source and destination options or enter a different name for this replication configuration to overwrite the automatically populated task name. By default, the system populates Task Name with the source-destination names selected or loaded by selecting a task in Load Previous Replication Tasks. The system prompts you to change the name if a task uses the name. Changing the name can be as simple as adding an iteration number such as 2 or 3 to the default name.
Encryption Options
The Encryption option shows additional settings on the Add Replication Task screen and the What and Where wizard screen below the Destination settings.
Select to apply an extra layer of encryption when replicating data to a remote server. Shows additional encryption settings Encryption Key Format and Store Encryption key in Sending TrueNAS database options.
Inherit Encryption
Select for the target dataset to inherit encryption from its parent dataset.
Encryption Key Format
Select the encryption option from the dropdown list. Hex (base 16 numeral) or Passphrase (alphanumeric) style encryption key. Selecting Hex displays the Generate Encryption Key option. Selecting Passphrase displays the Passphrase option.
Generate Encryption Key
Displays after selecting Hex in Encryption Key Format. Selected by default. Clearing the checkbox displays the Encryption Key field.
Encryption Key
Displays after clearing the Generate Encryption key checkbox. Use to import a custom hex key.
Passphrase
Displays when Encryption Key Format is set to Passphrase. Enter the alphanumeric passphrase to use as an encryption key.
Store Encryption key in Sending TrueNAS database
Displays after selecting Encryption. Selected by default. Select to store the encryption key in the TrueNAS database. Clearing the checkbox displays the Encryption Key Location in Target System field.
Encryption Key Location in Target System
Displays after clearing the Store Encryption key in sending TrueNAS database checkbox. Enter a temporary location for the encryption key that decrypts replicated data.
New SSH Connection
The New SSH Connection window opens after selecting Create New in the SSH Connection field.
It allows you to set up a new SSH connection for the remote system.
(Required) Enter a unique name for this SSH connection.
Setup Method
Select how to configure the connection from the dropdown list. Options:
Manual - Select to configure authentication on the remote system. This option can include copying SSH keys and modifying the root user account on that system.
Semi-Automatic - Select when configuring an SSH connection with a remote TrueNAS system. This method uses the URL and login credentials of the remote system to connect with and exchange SSH keys. This option only works when the other system is a TrueNAS system.
TrueNAS URL
(Required) Ener the host name or IP address of the remote system. A valid URL scheme is required. For example, https://10.235.12.20.
Admin Username
(Required) Enter the user name for logging into the remote system via the UI.
Admin Password
(Required) Enter the password for logging into the remote system.
One-Time Password (if necessary)
Enter the one-time password if two-factor authentication is enabled.
Username
(Required) Enter the user name for logging into the remote system via SSH.
Private Key
(Required) Select a saved SSH keypair or Generate New to create a new keypair to use for this connection.
Connect Timeout
Enter the time (in seconds) before the system stops attempting to establish a connection with the remote system.
When Wizard Screen
The When wizard screen sets the schedule for running the task and the retention period for keeping the replicated snapshots.
Replication Schedule and Destination Snapshot Lifetime options change the setting displayed on the screen.
Replication Schedule Options
The Replication Schedule options set when to run the task based on the schedule defined in Schedule or to run it one time.
Displays the Schedule option where you select a preset time or select Custom to use the advanced scheduler.
Run Once
Runs the replication task after you click Start Replication. Displays the Make Destination Dataset Read-only? option. Removes the Schedule option.
Schedule
Displays after selecting the Run On a Schedule radio button. Select a preset time or can select Custom to use the advanced scheduler.
Make Destination Dataset Read-only?
Displays after selecting the Run Once radio button. Select to change the destination dataset to be read-only. To continue using the default or existing dataset read permissions, leave this checkbox cleared.
Destination Snapshot Lifetime Options
The Destination Snapshot Lifetime setting determines how long the replicated snapshot is retained on the destination server.
Select to use the configured snapshot Lifetime value from the source dataset periodic snapshot task.
Never Delete
Select to never delete snapshots from the destination system.
Custom
Select to define how long the snapshot remains on the destination system. Displays the number of and measure of time fields to set the schedule.
Number of
Enter a numeric value to work with the measure of time selection to set the custom lifetime of the snapshot.
Measure of time
Select the option for Hours, Days, Weeks, Months, or Years to work with the number-of field to set the custom lifetime of the snapshot.
Add and Edit Replication Task Screens
Advanced Replication Creation opens the Add Replication Task screen. Click before or after adding values to any setting on the wizard screens.
The Edit icon button opens the Edit Replication Task screen. Both screens show the same setting options.
General and Transport Options Settings
The settings in General and Transport Options specify the name of the task, the direction of the data transfer, the transport connection type, and method settings for each type.
The Transport setting changes options displayed in the Transport Options area (SSH is the default setting).
All three Transport field options share the two settings displayed for Local, and the SSH Connection field displays for both the SSH and SSH+NETCAT transport selections.
(Required) Enter a descriptive name for the replication.
Direction
Select the direction for the replication from the dropdown list. Push sends snapshots to a destination system. Pull connects to a remote system and retrieves snapshots matching the value specified in Naming Schema.
Transport
Select the method of connecting to a remote system for exchanging data from the dropdown list. Options:
SSH - Default option that is supported by most systems. It requires a previously created SSH connection on the system.
SSH+NETCAT - Uses SSH to establish a connection to the destination system, then uses py-libzfs to send an unencrypted data stream for higher transfer speeds. This only works when replicating to a FreeNSAS, TrueNAS, or other systems with py-libzfs installed.
LOCAL - Efficiently replicates snapshots to another dataset on the same system without using the network. Removes Transport Options SSH setting options from the screen.
Use Sudo For Zfs Commands
Select if setting up remote replication tasks when logged in as an admin user.
Number of retries for failed replications
Enter the number of times the replication is attempted before stopping and marking the task as failed.
Logging Level
Select the level of message verbosity in the replication task log from the dropdown list. Options are Default, Debug, Info, Warning, and Error.
Enabled
Select to enable the replication schedule.
Transport Options Settings - Local Transport Option
These settings display for all three Transport options.
Inactive by default and if the system does not support large block transfers. Allows replication to send large data blocks. The destination system must also support large blocks. This setting cannot be changed after it is enabled and the replication task is created. See sfs(8) for more information.
Allow Compressed WRITE Records
Selected by default. If enabled, allows using compressed write records to make the stream more efficient. The destination system must also support compressed write records. See zfs(8).
Transport Options Settings - SSH Transport Option
These setting options display in addition to the two options displayed when Transport is set to SSH.
Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Stream Compression
Select a compression algorithm from the dropdown list to reduce the size of the data being replicated. Only appears when SSH is chosen as the Transport type.
Limit (Examples: 500 KiB, 500M, 2 TB)
Enter the number of bytes per second to limit replication speed to this number of bytes per second.
Transport Options Settings - SSH+NETCAT Transport Option
These setting options display in addition to the two options displayed when Transport is set to SSH+NETCAT.
Select a connection created and saved in Credentials > Backup Credentials > SSH Connections. If a connection does not display on the dropdown list, exit the task creation screen. Open Credentials > Backup Credentials and add an SSH connection.
Netcat Active Side
Select the option for the system that opens ports from the dropdown list. Options are Local or Remote. Establishing a connection requires that one of the connection systems has open TCP ports. Consult your IT department to determine which systems are allowed to open ports.
Netcat Active Side Listen Address
Enter the IP address on which the connection Active Side listens. Defaults to 0.0.0.0.
Netcat Active Side Min Port
Enter the lowest port number of the active side listen address that is open to connections.
Netcat Active Side Max Port
Enter the highest port number of the active side listen address that is open to connections. The first available port between the minimum and maximum is used.
Netcat Active Side Connect Address
Enter the host name or IP address used to connect to the active side system. When the active side is Local, this defaults to the SSL_CLIENT environment variable. When the active side is Remote, this defaults to the SSH connection host name.
Advanced Source Options
The settings in Source specify the location of files you push or pull in the replication task, and the properties applied to the replicated data.
The Source setting options change based on selections made in Recursive and Replicate Specific Snapshots and each displays additional setting options.
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. To enter multiple datasets, enter a comma (,) after each path in the Source field and then select another dataset. Click the arrow_drop_down at the /mnt to collapse the dataset tree.
Recursive
Select to replicate all child dataset snapshots. When selected, Exclude Child Datasets displays.
Exclude Child Datasets
Displays after selecting Recursive. Enter the specific child dataset snapshots from the replication. Separate each entry by pressing Enter.
Include Dataset Properties
Select to include ZFS dataset properties with the replicated snapshots. For more information on ZFS dataset properties see ZFS manpages.
Full Filesystem Replication
Select to completely replicate the selected dataset. The target dataset gets all the properties of the source dataset, child datasets, clones, and snapshots that match the specified naming schema. Hides the Recursive and Include Dataset Properties options.
Properties Override
Enter properties to replace existing dataset properties within the replicated files.
Properties Exclude
Enter any existing dataset properties to remove from the replicated files.
Advanced Destination Options
The settings in Destination specify the location of files you push or pull in the replication task, and the properties applied to the replicated data.
The destination setting options change based on selections made in Encryption and Snapshot Retention Policy which display additional setting options.
(Required) Enter or use arrow_right to the left of the /mnt folder and at each dataset to expand the dataset tree to browse to the dataset location that has snapshots to replicate. Click on the dataset or directory name, folder icon, or checkbox to select the dataset or directory. Selecting a location defines the full path to that location as the destination. Appending a name to the path creates a new zvol at that location. For example, selecting pol1/dataset1 stores snapshots in dataset 1, but adding /zvol1 after dataset1 creates zvol1 for snapshot storage. Click the arrow_drop_down at the /mnt folder to collapse the dataset tree.
Destination Dataset Read-Only Policy
Select the policy from the dropdown list. Options:
Set that changes all destination datasets to readonly=on after finishing the replication.
Require stops replication unless all existing destination datasets have the property readonly=on.
Ignore disables checking the readonly property during replication.
Encryption
Select to use encryption when replicating data. For more information on all options see Encryption.
Replication from scratch
Select if the destination system has snapshots but they do not have any data in common with the source snapshot, destroy all data destination snapshots and do a full replication. WARNING! Enabling this option can cause data loss or excessive data transfer if the replication is misconfigured.
Snapshot Retention Policy
Select the policy from the dropdown list to apply when replicated snapshots are deleted from the destination system. Options are Same as Source, Custom, and None. When selecting Same as Source use the Snapshot Lifetime from the source periodic snapshot task. When selecting Custom define a Snapshot Lifetime for the destination system. Also displays the Snapshot Lifetime and Unit options. When selecting None never delete snapshots from the destination system.
Snapshot Lifetime
Use to enter a numeric value to work with the measure of time field below to specify how long a snapshot remains on the destination system.
Unit
Select the measure of time from the dropdown list to work with the numeric value in Snapshot Lifetime. Options are Hour(s), Day(s), Week(s), Month(s), and Year(s).
Various Snapshot Options
The snapshot settings below change options displayed based on selections made.
Select the snapshot schedule for this replication task from the dropdown list. Select from previously configured periodic snapshot tasks. This replication task must have the same Recursive and Exclude Child Dataset values as the selected periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
Replicate Specific Snapshots
Select to only replicate snapshots that match a defined creation time. Selecting this option displays the By snapshot creation time field. Select the preset schedule or Custom to use the advanced scheduler.
Begin
Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created before this selected time are not included in the replication.
End
Displays after selecting Hourly in By snapshot creation time. Select a time range for the specific periodic snapshots to replicate, in 15-minute increments. Periodic Snapshots created after this selected time are not included in the replication.
Also include snapshots with the name
These radio buttons change the naming schema setting option below it. See Snapshot Naming in the wizard section for details on this option and the radio buttons.
Matching naming schema
Displays the Also Include Naming Schema setting.
Matching regular expression
Displays the Matching regular expression setting.
Also Include Naming Schema
Displays after selecting the Matching naming schema radio button. Enter the pattern of naming custom snapshots to include in the replication with the periodic snapshot schedule. Enter the strftime(3) strings that match the snapshots to include in the replication. When a periodic snapshot is not linked to the replication, enter the naming schema for manually created snapshots. Has the same %Y, %m, %d, %H, and %M string requirements as the Naming Schema in a Add Periodic Snapshot Task. Separate entries by pressing Enter.
Matching regular expression
Displays after selecting the Matching regular expression radio button. Enter the regular expressions snapshot should match. Using this option replicates all snapshots with names matching the specified regular expression. This process reads snapshot metadata to determine the snapshot creation order. This slows regular performance on the systems with a large number of snapshots.
Save Pending Snapshots
Select to prevent source system snapshots that have failed replication from being automatically removed by the Snapshot Retention Policy.
Replication Schedule Advanced Options
These schedule setting options are common to both the Replication Task Wizard and Add Replication Task screens.
Select to start this replication task immediately after the linked periodic snapshot task completes.
Schedule
Select to create a replication schedule if not selecting Run Automatically. Displays the Frequency and Only Replicate Snapshots Matching Schedule options.
Frequency
Displays after selecting Schedule. Select a preset schedule or choose Custom to use the advanced scheduler.
Begin
Displays after selecting Hourly in Frequency. Select the start time for the replication task.
End
Displays after selecting Hourly in Frequency. Select the end time for the replication task. A replication that is already in progress can continue to run past this time.
Only Replicate Snapshots Matching Schedule
Displays after selecting Schedule. Select to use the Schedule in place of the Replicate Specific Snapshots time frame. The Schedule values are read over the Replicate Specific Snapshots time frame.
Network
The SCALE Network screen has network configuration and settings options, in widgets, for active interfaces, static routes, and the global configuration.
The Network screen also displays OpenVPN information and IPMI channels. IPMI only displays on systems with physical hardware and not on virtual machine deployments.
Click the buttons or on an existing widget entry to view configuration options on side panels.
Networking Tour Video
This video demonstrates configuring networking settings.
Network Interface Screens: Provides information on the Network screen Interfaces widget and configuration screens.
Global Configuration Screens: The Global Configuration widget displays the general TrueNAS network settings not specific to any interface.
Static Routes Widget: The Static Routes widget displays existing static routes or sets up new ones.
IPMI Screens: Provides information on the Network screen IPMI widget and configuration screen.
Network Interface Screens
The Interfaces widget on the Network screen shows interface port names and IP addresses configured on your TrueNAS system and their upload/download rates.
Use Add to open the Add Interface configuration screen.
Click on an interface to open the Edit Interface configuration screen.
Click the edit icon next to an interface to open the Edit Interface configuration screen.
Click the refresh icon next to a physical interface to reset configuration settings for that interface.
Click the delete icon next to any other interface to delete that interface.
TrueNAS Enterprise
High Availability (HA) Enterprise systems cannot reset or delete interfaces while failover is enabled.
On systems with HA failover enabled, the refresh or delete icons are disabled.
Go to System > Failover to disable failover before attempting to modify interfaces on HA systems.
Add/Edit Interface Configuration Screens
The fields on the Add Interface and Edit Interface configuration screens are almost identical.
The Type field only shows on the Add Interface configuration screen.
Type is a required field, and after selecting the interface type additional configuration fields show based on the selected type.
Apply saves setting changes.
Interface Settings
These settings are common to all interface types. The Type setting is only available and required on the Add Interface configuration screen.
Setting
Description
Type
(Required) Select the type of interface from the dropdown list, Options are:
Bridge - Select to create a logical link between multiple networks.
Link Aggregation - Select to combine multiple network connections into a single interface.
VLAN - Select to partition and isolate a segment of the connection.
Each type of interface shows additional configuration settings for that type. The Type field does not display on the Edit Interface screen.
Name
(Required) Enter a name for the interface. Use the format bondX, vlanX, or brX where X is a number representing a non-parent interface. Assign the first interface of any type the appropriate name plus zero, for example, br0 for the first bridge interface created. You cannot change the interface name after clicking Apply. After saving, Name becomes a read-only field when editing an interface.
Description
Enter a description for the interface.
DHCP
Select to enable DHCP. Leave the checkbox clear to create a static IPv4 or IPv6 configuration. Only one interface can be configured using DHCP.
Autoconfigure IPv6
Select to automatically configure the IPv6 address with rtsol(8). Only one interface can be configured this way.
Bridge Settings
Bridge Settings only shows after selecting Bridge in Type.
Setting
Description
Bridge Members
Select the network interfaces to include in the bridge from the dropdown list of options.
Link Aggregation Settings
Link aggregation settings only show after selecting Link Aggregation as the Type.
Additional settings show based on the selection in Link Aggregation Protocol.
Click here for LACP settings
Setting
Description
Link Aggregation Protocol
Select the protocol to use from the dropdown list of options. The protocol determines the outgoing and incoming traffic ports.
LACP - Select if the network switch is capable of active LACP (this is the recommended protocol). LACP shows additional settings.
Failover - Select if the network switch does not support active LACP. This is the default protocol choice and is only used if the network switch does not support active LACP. Failover uses only the Link Aggregation Interfaces setting.<br
Loadbalance - Select to set up loadbalancing. Loadbalance does not use any other link aggregation settings.
Transmit Hash Policy
Shows when the protocol is set to LCAP or Loadbalance. Select the hash policy from the dropdown list of options, LAYER2, LAYER2+3 the default, or LAYER3+4.
LACPDU Rate
Shows only when the protocol is set to LCAP. Select either Slow or Fast from the dropdown list of options.
Link Aggregation Interfaces
(Required) Shows when protocol is set to LACP, Failover or Loadbalance. Select the interfaces to use in the aggregation. Warning! Link Aggregation creation fails if any of the selected interfaces are manually configured!
Click here for Failover settings
Setting
Description
Link Aggregation Protocol
Select the protocol to use from the dropdown list of options. The protocol determines the outgoing and incoming traffic ports. Options are:
LACP - Select if the network switch is capable of active LACP (this is the recommended protocol). LACP Shows additional settings.
Failover - Select if the network switch does not support active LACP. This is the default protocol choice and is only used if the network switch does not support active LACP. Failover uses only the Link Aggregation Interfaces setting.
Loadbalance - Select to set up loadbalancing. Loadbalance does not use any other link aggregation settings.
Link Aggregation Interfaces
(Required) Select the interfaces to use in the aggregation. Warning! Link Aggregation creation fails if any of the selected interfaces are manually configured!
Click here for Loadbalance settings
Setting
Description
Link Aggregation Protocol
Select the protocol to use from the dropdown list of options. The protocol determines the outgoing and incoming traffic ports.
LACP - Select if the network switch is capable of active LACP (this is the recommended protocol). LACP shows additional settings.
Failover - Select if the network switch does not support active LACP. This is the default protocol choice and should be only used if the network switch does not support active LACP. Failover uses only the Link Aggregation Interfaces setting.
Loadbalance Select to set up loadbalancing. Loadbalance does not use any other link aggregation settings
Transmit Hash Policy
Select the hash policy from the dropdown list of options, LAYER2, LAYER2+3 the default, or LAYER3+4.
Link Aggregation Interfaces
Required. Select the interfaces to use in the aggregation. Warning! Link Aggregation creation fails if any of the selected interfaces have been manually configured!
VLAN Settings
Link aggregation settings only display after you select VLAN as the Type.
Setting
Description
Parent Interface
Select the VLAN parent interface from the dropdown list of options. This is usually an Ethernet card connected to a switch port configured for the VLAN. New link aggregations are not available until you restart the system.
VLAN Tag
(Required) Enter the numeric tag configured in the switched network. Request this from your IT department if you are not the network administrator for your systems.
Priority Code Point
Select the class of service from the dropdown list of options. The available 802.1p class of service ranges from Best effort (default) to Network control (highest).
Other Settings
Other Settings show for all types of interfaces.
Setting
Description
MTU
Maximum Transmission Unit (MTU), or the largest protocol data unit that can be communicated. The largest workable MTU size varies with network interfaces and equipment. 1500 and 9000 are standard Ethernet MTU sizes. Leaving blank restores the field to the default value of 1500.
Aliases
Add the right of Aliases shows fields to define an alias IP address and netmask (CIDR) for the interface on the TrueNAS controller. The alias can be an IPv4 or IPv6 address.
Users can also select the CIDR bits that are a part of the network address from the dropdown list of options.
Testing Changes
The option to test network changes shows when creating a new or changing an existing network interface that can affect access to the UI.
Test Changes starts the 60-second timer.
Revert Changes discards changes made within the 60-second period.
Save Changes makes changes permanent. Shows in the new browser window opened as part of the esting Network Interface Changes process.
Global Configuration Screens
The Global Configuration widget displays the general TrueNAS networking settings not specific to any interface.
Use Settings to display the Global Configuration screen where you can add or change global network settings.
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.
Hostname and Domain Settings
Many of these fields have default values, but users can change them to meet local network requirements.
TrueNAS displays the Hostname and Domain in the DashboardSystem Information widget.
Some fields only display in the Global Configuration screen when the appropriate hardware is present.
Enter the system host name. The default value is truenas. Some applications require setting this to a value other than truenas.
Inherit domain from DHCP
When selected, the domain is inherited from DHCP.
Hostname (TrueNAS Controller 2)
System host name for a second controller that shows only for High Availability (HA) systems where there is a second TrueNAS controller. A name can consist of upper and lower case alphanumeric and allowed special characters dot (.) and/or dash (-).
Hostname (Virtual)
Virtual host name that shows when using a virtual host. Also used as the Kerberos principal name. Enter the fully qualified host name plus the domain name. A name can consist of upper and lower case alphanumeric and allowed special characters dot (.) and/or dash (-).
Domain
Enter a system domain name, for example, example.com.
Additional Domains
Enter additional domains to search. Separate entries by pressing Enter. Adding search domains can cause slow DNS lookups.
Service Announcement Settings
Setting
Description
NetBIOS-NS
Select to use legacy NetBIOS name server. Advertises the SMB service NetBIOS name. Might be required for legacy SMB1 clients to discover the server. When advertised, the server appears in Network Neighborhood.
mDNS
Select to multicast DNS. Uses the system host name to advertise enabled and running services. For example, this controls if the server appears under Network on MacOS clients.
WS-Discovery
Select to use the SMB Service NetBIOS name to advertise the server to WS-Discovery clients. Can cause the computer to appear in the Network Neighborhood of modern Windows operating systems.
Select to allow any system service to communicate externally.
Deny All
Select to restrict this system so it cannot communicate externally.
Allow Specific
Select to specify a limited set of system services to allow to communicate externally. All other external traffic is restricted. If selected, a dropdown list shows where you select the services to allowed to communicate externally.
Enter additional hosts to append to /etc/hosts. Separate entries by pressing. Separate entries by pressing Enter. Use the format IP_address space hostname where multiple hostnames can be used if separated by a space. Hosts defined here are still accessible by name even when DNS is not available. See hosts for additional information.
Static Routes Widget
The Static Routes widget on the Network screen displays static IP addresses configured as static routes. Use this to manually enter routes to network destinations outside the TrueNAS network so the router can send packets to a destination network.
TrueNAS does not have defined static routes by default.
If you need a static route to reach portions of the network, add the route by going to Network and clicking Add in the Static Routes window.
Setting
Description
Destination
Enter the destination IP address using the format A.B.C.D/E where E is the CIDR mask. This is a required field.
Gateway
Enter the IP address of the gateway. This is a required field.
Description
Enter notes or an identifier describing the route.
Use Save to add the static route.
IPMI Screens
The IPMI widget on the Network screen shows the available IPMI channels.
IPMI requires a compatible motherboard with IPMI support.
Refer to your hardware documentation to determine compatibility.
Select to use DHCP to assign IPv4 network values. Clear the checkbox to manually configure a static IPv4 connection.
IPv4 Address
Enter the IPMI web interface static IPv4 address.
IPv4 Netmask
Enter the IPv4 address subnet mask.
IPv4 Default Gateway
Enter the IPv4 connection default gateway.
VLAN ID
Enter the VLAN identifier of the IPMI out-of-band management interface is not on the same VLAN as management networking.
Password
Enter an 8-16 character password for connecting to the IPMI interface from a web browser. The password must include at least one upper case letter, one lower case letter, one digit, and one special character (punctuation, e.g. ! # $ %, etc.).
Save
Save the configuration.
Manage
Opens the IPMI manager in a new browser tab where users can communicate with the server without having direct access to the hardware.
Flash Identify Light
Flashes the system IPMI light on the compatible connected hardware.
Stop Flashing
Stops flashing the system IPMI light on the compatible connected hardware.
Credentials
SCALE Credential options are collected in this section of the UI and organized into a few different screens:
Contents
Users Screens: Provides information on the Users screens and settings and information on settings for the TrueNAS SCALE Shell screen.
Groups Screens: Provides information on the Groups screens and settings.
Directory Services Screens: Describes the screens and fields in the TrueNAS SCALE Directory Services section.
Backup Credentials: Information on backup credential screens and settings to integrate TrueNAS SCALE with cloud storage providers by setting up SSH connections and keypairs.
Certificates: Information about the Certificates screen and widgets.
KMIP Screen: Describes the fields in the KMIP Key Status screen on TrueNAS SCALE Enterprise.
Users Screens
The Credentials > Users screen displays a list of user accounts added to the system.
By default built-in users, except for root, are hidden until you make them visible.
Toggle Build-In Users displays either the Show Built-In Users or Hide Built-in Users dialogs based on the current Users list view.
If hidden, the Show Built-in Users dialog opens. Click Show to display the list of users.
Click on a user row to show the user details screen.
User Details Screen
The expanded view of each user includes details for that user, including the home directory location, shell, Samba authentication, SSH key, and sudo command access (if assigned).
It provides the option to edit or delete the user, and access user audit logs.
Edit opens the Edit User screen. Delete opens a delete confirmation dialog.
Add or Edit User Screens
The Add User and Edit User configuration screens display the same setting options.
Built-in users (except the root user) do not include the Home Directory Permissions settings, but all new users created, such as those for an SMB share like the smbguest user, do.
Identification Settings
Identification settings specify the name, user name, password, and user email.
Required. Enter a description for the user, such as a first and last name.
Username
Required. Enter a user name of up to 16 characters in length. When using NIS or other legacy software with limited user name lengths, keep names to eight characters or less for compatibility. Do not begin the user name with a hyphen (-), and do not include a space, tab, the comma (,), plus (+), ampersand (&), percent (%), carat (^), open or close parenthesis ( ), exclamation mark (!), at symbol (@), tilde (~), question mark (?), greater or less than symbols (<)(>), or equals (+) in the name. You can use the dollar sign ($) as the last character of the user name.
Disable Password
Use the toggle to disable the password for the selected user. At least one user with administrative privileges must have a password enabled.
Password
Required. Enter a user password unless you set Enable Password login to No. A password cannot contain a question mark (?). The Edit User screen displays New Password.
Confirm Password
Required. Re-enter the value entered in Password. The Edit User screen displays Confirm New Password.
Email
Enter the email address of the new user. This email address receives notifications, alerts, and messages based on the settings configured.
Required. Enter a number greater than 1000 for user accounts. System accounts use an ID equal to the default port number used by the service.
Primary Group
Select a group from the dropdown list. New users are not assigned su permissions if wheel is their primary group.
Auxiliary Groups
Select group(s) from the dropdown list to add this new user to additional groups. To assign a pre-defined administrator role, scroll down the list to select the desired role.
Create New Primary Group
Select to create a new primary group with the same name as the user. Clear to select an existing group from the Primary Group dropdown list.
Directories and Permissions settings
Directory and Permissions settings specify the user home directory and the permissions for that home directory.
Enter or browse to enter the path to the home directory for this user. If the directory exists and matches the Username, it is set as the home directory for the user. When the path does not end with a subdirectory matching the username, a new subdirectory is created if Create Home Directory is selected (enabled). The full path to the user home directory displays in this field on the Edit User screen for this user. The default location is /var/empty.
Home Directory Permissions
Select the permissions in Read, Write, and Execute for each role (User, Group, and Other) to set access control for the user home directory. Built-in users are read-only and can not modify these settings.
Create Home Directory
Select to create a home directory for the user when the home directory path for this user does not end in the user name. Creates a home directory for the user within the selected path.
Authentication settings
Authentication settings specify authentication methods, the public SSH key, user administration access, and enable/disable password authentication.
The add and edit user screens grant access to a shell option, but the privilege screen Web Shell Access setting determines the ability to see the System > Shell screen.
Enter or paste the downloaded SSH public key of the user for any key-based authentication. Use Download Authorized Keys to obtain a public key text file. Keep a backup copy of the public key! Do not paste the private key in this field!
Upload SSH Key
Browse to the public key text file.
Shell
Select the shell to use for local and SSH logins from the dropdown list. Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh.
Lock User
Select to prevent the user from logging in or using password-based services until you clear this checkbox. Locking an account is only possible when Disable Password is set to No and the account has a created password in Password.
Allowed sudo commands
Use to list specific sudo commands allowed for this user. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands. Using sudo prompts the user for their account password.
Allow all sudo commands
Select to give this user permission to use all sudo commands. Using sudo prompts the user for their account password.
Allowed sudo commands with no password
Use to list specific sudo commands allowed for this user with no password required. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for this user when using these commands. Exercise caution when allowing sudo commands without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks.
Allow all sudo commands with no password
Select to give this user administrator permissions and the ability to use all sudo commands with no password required. This is not recommended.
SMB User
Select to allow this user to authenticate to and access data share with SMB samba shares.
Download Authorized Keys
Click to generate and download a public key text file. Displays on the Edit User screen.
Shell Options
You can set a specific shell for the user from the Shell dropdown list options.
Shell
Description
nologin
Use when creating a system account or to create a user account that can authenticate with shares but that cannot log in to the TrueNAS system using SSH. In rare cases where a CORE user has /etc/netcli set as the user shell, then migrates to SCALE the user shell changes to /user/sbin/nologin as the default.
Use to open Shell in the CLI. Eliminates the need to enter cli at the Shell system prompt to enter the TrueNAS CLI. Enter ls to see the list of namespaces.
TrueNAS Console
Use to open Shell in the Console Setup menu. Eliminates the need to enter menu. Displays the console setup menu options. This option provides the user with access to the Linux and TrueNAS CLI shells.
Groups Screens
Groups Screen
The Credentials > Groups screen displays a list of groups configured on the screen. By default, built-in groups are hidden until you make them visible.
To see built-in groups, click the Show Built-In Groups toggle.
The toggle turns blue and all built-in groups display. Click the Show Built-In Groups toggle again to show only non-built-in groups on the system.
The Credentials > Groups screen displays the No groups screen if no groups other than built-in groups are configured on the system.
Required. Enter a unique number for the group ID (GID) TrueNAS uses to identify a Unix group. Enter a number above 1000 for a group with user accounts (you cannot change the GID later). If a system service uses a group, the group ID must match the default port number for the service.
Name
Required. 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 (=). You can only use the dollar sign ($) as the last character in a user name.
Privileges
Attaches administrator role privileges to the group. Using custom administrator roles aside from the defaults is an experimental feature and is not supported. Do not modify the local administrator or default admin user privileges! Only use if you need users in this group to access limited areas of the web UI or authentication for TrueNAS API calls.
Allowed sudo commands
Use to list specific sudo commands allowed for group members. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Using sudo prompts the user for their account password.
Allow all sudo commands
Select to give group members permission to use all sudo commands. Using sudo prompts the user for their account password.
Allowed sudo commands with no password
Use to list specific sudo commands allowed for group members with no password required. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. /usr/bin/ is the default location for commands. Grants limited root-like permissions for group members when using these commands. Exercise caution when allowing sudo commands without password prompts. It is recommended to limit this privilege to trusted users and specific commands to minimize security risks.
Allow all sudo commands with no password
Not recommended. Select to give group members the ability to use all sudo commands with no password required.
SMB Group
Select to allow this group to authenticate to and access data shares with SMB samba shares.
Allow Duplicate GIDs
Not recommended. Select to allow more than one group to have the same group ID. Use only if absolutely necessary, as duplicate GIDs can lead to unexpected behavior.
Edit Group Screen
Click Edit on an expanded group in the Groups screen to open the Edit Group screen.
To add user accounts to the group, select users and then click the right arrow .
To remove user accounts from the group, select users and then click the left arrow .
Select multiple users by holding Ctrl while clicking each entry.
Click Save.
Privileges Screen
The Privileges feature is an early release experimental feature.
Use the Privileges screens to view default administrator groups and roles, or define customized groupings of roles for different local or Directory Service-imported account groups.
Only the Readonly Admin, Sharing Admin, and Full Admin roles are supported in the Web UI.
Users can experiment with defining a new privilege but should NOT edit the existing predefined administrator roles!
Editing the unrestricted administrator account privilege can result in lost access to the system!
Click on a listed privilege to expand the row and show details on the privilege.
Edit opens the Edit Privilege screen.
The new and edit privilege screens show the same settings but not all settings are editable.
Setting
Description
Name
Enter a name for the new privilege. Names can include the dash (-) or underscore(_) special characters, and upper and lowercase alphanumeric characters. Enter a descriptive name for the privilege.
Groups
Click in the field to see a dropdown list of available groups to apply the privilege to. Do not add the predefined administrator or builtin groups! Only select new user groups created if you experiment with this function.
Directory Services Groups
Click in the field to see a dropdown list of available groups to apply the privilege to.
Roles
Click in the field to see a dropdown list of all available roles available to assign to the new privilege.
Web Shell Access
Select to allow a user assign the new privilege access to the System > Shell screen.
Assigned administrator roles display on the Users Screen.
Directory Services Screens
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
The Directory Services screen contains configuration options set up access to directory servers with domain and account settings, and can set up Id mapping or Kerberos authentication and authorization service.
The screen shows the status of Active Directory and LDAP services when neither is configured, or if either is configured but disabled.
Only one directory service can be configured at a time.
Three options show by default:
Configure Active Directory opens the Active Directory configuration screen.
Configure LDAP opens the LDAP configuration screen. Use to configure access to LDAP-based service such as FreeIPA.
Advanced Settings opens a warning dialog before showing configuration options for [ID mapping] (/scaleuireference/credentials/directoryservices/idmap/ and Kerberos.
After configuring Active Directory or LDAP, the Directory Services screen includes the widgets for each option, and adds the Show button to the right of Advanced Settings. Show opens the warning dialog stating incorrectly configuring advanced settings is dangerous.
Advanced Settings, before configuring either Active Directory or LDAP, shows a warning dialog stating incorrectly configuring advanced settings is dangerous.
Continue closes the dialog and then show the Idmap, Kerberos Settings, Kerberos Realms, and Kerberos Keytabs configuration widgets.
Active Directory Screens: Provides information on the **Active Directory** configuration screens and settings.
LDAP Screens: Provides information on the **LDAP** screen and widget settings.
Idmap Screens: Provides information on the **Idmap** screen and widget settings.
Kerberos Settings Screen: Provides information on the **Kerberos Settings** widget and configuration screen settings.
Kerberos Realms Screens: Provides information on the **Kerberos Realms** widget and configuration screen settings.
Kerberos Keytab Screens: Provides information on the **Kerberos Keytabs** screen and widget settings.
Active Directory Screens
The Directory Services screen and widgets provide access to TrueNAS settings to set up access to directory services and advanced authentication systems deployed in user environments.
TrueNAS does not configure Active Directory domain controllers or LDAP directory servers, nor does it configure Kerberos authentication servers or ID mapping systems.
Refer to documentation for these services and systems for information on how to configure each to suit your use case.
Active Directory Widget
The Active Directory widget displays after you configure TrueNAS to access your Active Directory domain controller.
The widget shows Status, Domain Name, and Domain Account Name.
Settings opens the Active Directory edit screen that shows the settings you can edit.
Active Directory - Add and Edit Screens
The Active Directory configuration screen opens showing the Basic Options as the default view.
Advanced Options shows additional advanced setting options.
After configuring TrueNAS to access Active Directory, Settings opens the Active Directory screen showing the few basic options you can edit and the option to access advanced settings.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or if there are fewer users than expected available in the permissions editors.
Leave Domain shows after configuring Active Directory access, and disconnects the TrueNAS system from the Active Directory server.
Active Directory - Basic Options
The edit version of the Basic Options screen only shows options you can edit, which are the Domain Name and Enable options.
Basic Options settings also show on the Advanced Options screen.
(Required) Enter the Active Directory domain name (example.com) or child domain (sales.example.com) if configuring TrueNAS with access to a limited portion of your configuration. This is the name of the domain with all the user and group objects TrueNAS accesses. Editable after saving.
Domain Account Name
(Required) Enter the bindname TrueNAS should use as the account name. The default value is Administrator. TrueNAS creates this account after domain joins. Not editable after saving.
Domain Account Password
(Required) Enter the bindpw password for the account. Required the first time you configure a domain. After initial configuration, the password is not needed to edit, start, or stop the service. After the initial configuration or joining, TrueNAS uses the Kerberos Principal instead of the password.
NetBIOS Name
Enter the hostname of the TrueNAS system, found on the Edit Global Configuration screen in the Hostname field. The default value is TRUENAS. The name must not exceed 15 characters, including spaces, and must differ from the Workgroup name. The Workgroup name is a label used to identify a group of computers on a local network that share resources and are part of a peer-to-peer networking model.
Enable (requires password or Kerberos principal)
Select to enable the Active Directory service in TrueNAS. TrueNAS populates the Kerberos Realm and Kerberos Principal fields with what it discovers in AD. Clear to disable Active Directory. After disabling Active Directory, the Directory Services screen returns to the default and shows the options to configure AD or LDAP. TrueNAS creates a Kerberos realm and keytab from what it detects in Active Directory, then populates the Kerberos Realm and Kerberos Principal settings on the Advanced Options screen.
Active Directory - Advanced Options
The Advanced Options screen shows both the basic and advanced option settings on the add and edit versions of the Active Directory screen.
Enter the relative distinguished name (RDN) of the site object in the AD server. This is the first component of the distinguished name in AD. For more info, read Configuring Active Directory.
Kerberos Realm
Select an existing realm from the dropdown list of options. Options are those configured in Kerberos Realms. After selecting Enable (requires password or Kerberos principal), SCALE populates the Kerberos Realm and Kerberos Principal fields with what it discovered in AD.
Kerberos Principal
Select the location of the principal in the keytab created in Directory Services > Kerberos Keytabs. After selecting Enable (requires password or Kerberos principal), SCALE populates the Kerberos Realm and Kerberos Principal fields with what it discovered in AD.
Computer Account OU
The organizational unit (OU) where new computer accounts are created. The OU string includes the distinguished name (DN) of the Computer Account OU that includes the hierarchical location of the OU within the directory structure. For example, OU=Computers,DC=example,DC=com. The OU string is read from top to bottom without relative distinguished names (RDNs). Slashes (/) are used as delimiters, as in Computers/Servers/NAS. Backslashes () are used to escape characters but not as a separator. Backslashes are interpreted at multiple levels and might require doubling or even quadrupling to take effect. When this field is blank, new computer accounts are created in the Active Directory default OU.
AD Timeout
Enter the number of seconds before timeout. To view the AD connection status, go to *Task Manager > History to open the Jobs screen.
DNS Timeout
Enter the number of seconds before a timeout. Increase this value if AD DNS queries time out.
Winbind NSS Info
Winbind NSS specifies the method used by Winbind to retrieve user and group information. Select the schema to use when querying AD for user/group info. Options:
TEMPLATE - (default) Select to use a template to construct user and group entries based on attributes. Other options:
rfc2307 - Select to use the RFC 2307 schema, Windows 2003 R2 schema support.
sfu - Select to use the Service for Unix 3.0 or 3.5 schema to access Unix attributes in Active Directory.
sfu20 - Select to use the Service for Unix 2.0 schema to access Unix attributes in Active Directory.
NetBIOS Alias
Alternative names that SMB clients can use when connecting to this NAS. Names must not exceed 15 characters.
Enable (requires password or Kerberos principle)
Select to enable AD service. The first time you select this option you must enter the password for the domain admin account. After selecting Enable (requires password or Kerberos principal), SCALE populates the Kerberos Realm and Kerberos Principal fields with what it discovered in AD.
Verbose Logging
Select to increase logging verbosity related to the Active Directory service in /var/log/midlewared.log.
Allow Trusted Domains
Select if you want to allow clients to access the TrueNAS server if they are members of domains that have a trust relationship with the domain to which TrueNAS is joined. This requires valid idmap backend configuration for all trusted domains.
Use Default Domain
AD users and groups by default have a domain name prefix (DOMAIN\). In some edge cases, this might cause erratic behavior from some clients and applications that are poorly designed and cannot handle the prefix. Select only if required for a specific application or client. Note that using this setting is not recommended as it may cause collisions with local user account names.
Allow DNS Updates
Select to enable Samba to do DNS updates when joining a domain. Selected by default.
Disable AD User/Group Cache
TrueNAS maintains a cache of users and groups for API consumers (including the WebUI). This is a convenience feature that might be disabled if the domain contains large numbers of users and groups, or if caching generates excessive load on the domain controller. Select to disable caching AD users and groups.
Restrict PAM
Select to restrict SSH access in certain circumstances to members in BUILTIN\Administrators. Pluggable Authentication Module (PAM) enables systems to authenticate users against AD credentials.
LDAP Screens
Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel).
Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.
LDAP Widget
The LDAP widget displays after you configure SCALE settings for your LDAP instance.
The widget includes Status, and the Hostname and Base DN and Bind DN you configured.
Settings opens the LDAP screen.
LDAP - Add and Edit Screens
The LDAP configuration screen has two screens, Basic Options the default view, and Advanced Options.
After configuring LDAP, the edit LDAP screen includes both the basic and advanced options.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or there are fewer users than expected are available in the permissions editors.
LDAP Screen - Basic Options
The settings on the Basic Options also display on the Advanced Options screen.
Basic Option Settings
Setting
Description
Hostname
Enter the LDAP server hostnames/IP addresses. Separate entries with Space. You can enter multiple hostnames/IP addresses to create an LDAP failover priority list. If a host does not respond, TrueNAS tries the next host until it establishes a connection.
Base DN
Enter the top level of the LDAP directory tree to use when searching for resources. Example: dc=test,dc=org.
Bind DN
Enter the administrative account name for the LDAP server. Example: cn=Manager,dc=test,dc=org.
Bind Password
Enter the password for the administrative account (in Bind DN).
Enable
Select to activate the configuration. Select to clear and disable the configuration without deleting it. You can re-enable it later without reconfiguring it. The Directory Services screen returns to the default and provides the options to configure AD or LDAP.
LDAP Screen - Advanced Options
The settings on the Advanced Options screen include the Basic Options screen.
Advanced Option Settings
Setting
Description
Allow Anonymous Binding
Select to enable the LDAP server to disable authentication and allow read and write access to any client.
Encryption Mode
Select the options for encrypting the LDAP connection from the dropdown list.
Select OFF to not encrypt the LDAP connection. Select ON to encrypt the LDAP connection with SSL on port 636. Select START_TLS to encrypt the LDAP connection with STARTTLS on the default LDAP port 389.
Certificate
Select the certificate to use when performing LDAP certificate-based authentication. To configure LDAP certificate-based authentication, create a Certificate Signing Request for the LDAP provider to sign. TrueNAS does not need a certificate when using username/password or Kerberos authentication.
Validate Certificates
Select to verify certificate authenticity.
Disable LDAP User/Group Cache
Select to disable caching LDAP users and groups in large LDAP environments. When caching is disabled, LDAP users and groups do not appear in drop-down menus but are still accepted when manually entered.
Kerberos Realm
Select an existing realm from Kerberos Realms.
Kerberos Principal
Select the location of the principal in the keytab created in Kerberos Keytab.
LDAP Timeout
Enter the number of seconds for the LDAP timeout. Increase this value if a Kerberos ticket timeout occurs.
DNS Timeout
Enter the number of seconds for the DNS timeout. Increase this value if DNS queries timeout.
Auxiliary Parameters
(Optional - only experienced users) Specify additional options for nslcd.conf.
Schema
Select the LDAP NSS schema from the dropdown list. Options are RFC2307 or RFC2307BIS.
Idmap Screens
Idmap in Linux is essentially a translation of a range of IDs into another or the same range of IDs.
Only administrators experienced with configuring Id mapping should attempt to add new or edit existing idmaps.
Misconfiguration can impact system operation.
Idmap Widget
The Idmap widget in the Advanced Settings on the Directory Services screen displays idmaps added to SCALE.
Add opens the Add Idmap configuration screen.
Click on any instance to open the Edit Idmap screen.
The Idmap widget header opens the Idmap screen.
Idmap Screen
The Idmap screen displays a list view of idmaps configured on your SCALE system.
Add opens the Add Idmap screen.
Click on an Idmap on the widget to open the screen for the selected idmap.
Add and Edit IDMAP Screens
The settings on the Add Idmap and Edit Idmap change based on the selection made in both the Name and Idmap Backend fields.
Add Idmap Screen (Default and Custom Value)
Setting
Description
Name
(Required) Select an option from the dropdown list, SMB - Primary Domain or Custom Value. SMB - Primary Domain reduces the fields displayed on the Add Idmap screen. Selecting Custom Value adds The Custom Name field.
Custom Name
Displays below the Name field after selecting Custom Value in the Name field. Enter the pre-Windows 2000 domain name.
Idmap Backend
(Required) Select the backend plugin interface for Winbind to use to store SID to UID/GID mapping tables. The correct setting depends on the environment you deployed the NAS in. Options are AD for Active Directory, LDAP for an LDAP environment. AUTORID is similar to RID but it can automatically assign IDs for different domains. NSS provides a means to map Unix users and groups to Windows accounts. RFC2307 provides a way for Winbind to read ID mappings from records in an LDAP server defined in RFC 2307. RID provides a way to use an algorithmic mapping scheme to map UIDs/GIDs and SIDs. TDB is similar to RID but it is an allocating backend, which means it needs to allocate new users and group IDs in order to create new mappings. The selected option changes the settings displayed on the Add Idmap screen.
DNS Domain Name
Enter the DNS name of the domain.
Range Low
(Required) Enter a value for the least number of members. Works with the Range High to establish the range of UID/GID numbers the Idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it.
Range High
(Required) Enter a value for the greatest number of members. Works with the Range Low to establish the range of UID/GID numbers the Idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it.
Options Settings
The Options settings change based on the selected Name and Idmap Backend fields.
Setting
Description
Unix Primary Group
Select to fetch the primary group membership from the LDAP attributes (gidNumber). If unselected, the primary group membership is calculated via the primaryGroupID LDAP attribute.
Unix NSS Info
Select sets Winbind to retrieve the login shell and home directory from the LDAP attributes. If unselected, when the AD LDAP entry lacks the SFU attributes the smb4.conf parameters template shell and template homedir are used.
Support for LDAP Schema Mode for SMB shares is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel).
Before updating to 24.10 or later, Administrators using this legacy feature should stop using SMB shares (continue using LDAP), convert directory users to local TrueNAS accounts (stop using LDAP), or convert to Active Directory (stop using LDAP).
Add Idmap Screen for SMB - Primary Domain
The settings for Add Idmap displays a subset of those on the default screen.
Settings for SMB - Primary Domain
Setting
Description
Name
Displays SMB - Primary Domain.
DNS Domain Name
Enter the DNS name of the domain.
Range Low
(Required) Works with the Range High to establish the range of UID/GID numbers the idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it.
Range High
(Required) Works with the Range Low to establish the range of UID/GID numbers the idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it.
Options only as the Read Only which, when selected, makes the module read-only. No new ranges are allocated or new mappings created in the idmap pool.
Add Idmap Screen with Idmap Backend as AD
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to AD shares the same settings as the default screen but it includes DNS Domain Name.
Idmap Backend - AD Settings
Setting
Description
DNS Domain Name
Enter the domain name of the DNS server.
Add Idmap Screen with Idmap Backend as AUTORID
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to AUTORD shares the some of the same settings on the AD screen but the Options settings are different.
Idmap Backend - AUTORID Options Settings
Setting
Description
Range Size
Enter the number of UIDs/GIDs available per domain range. The minimum number is 2000. The recommended default is 100000.
Read Only
Select to make the module read-only. No new ranges are allocated or new mappings created in the idmap pool.
Ignore Builtin
Select to ignore mapping requests for the BUILTIN domain.
Add Idmap Screen with Idmap Backend as LDAP
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to LDAP shares the some of the same settings on the AD screen but it adds the Certificate option, and the Options settings are different.
Idmap Backend - LDAP Settings
Setting
Description
Certificate
Select the certificate of the Active Directory server if SSL connections are used. When no certificates are available, move to the Active Directory server and create a Certificate Authority and certificate. Import the certificate to SCALE using the Credentials > Certificates screen widgets.
Manage Certificates
Opens the Credentials > Certificates screen. When finished on the Certificates screen, navigate back to Directory Services, click Show and confirm to display the Idmap widget again. Click Add to begin the configuration again.
Options
The LDAP settings in Options are different from other Idmap Backend options except the RFC2307 option.
Setting
Description
Read Only
Select to make the module read-only. No new ranges are allocated or new mappings created in the idmap pool.
Base DN
(Required) Enter the directory base suffix to use for SID to UID/GID mapping entries. Examples, dc=test, dc=org. When undefined, idmap_ldap defaults to using the LDAP idmap suffix option from smb.conf.
LDAP User DN
(Required) Enter the user distinguished name (DN) to use for authentication.
LDAP User DN Password
Enter the password associated with the LDAP user DN.
URL
(Required) Enter the URL for the LDAP server to use for SID to UID/GID mapping. For example, ldap://ldap.netscap.com/o=Airus.com.
Encryption Mode
(Required) Select the encryption mode to use with LDAP from the dropdown list. Options are On, Off, or StartTLS.
Add Idmap Screen with Idmap Backend as NSS
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to NSS shares the same settings as the AD screen. There is only one Options setting.
Idmap Backend - NSS Settings
Setting
Description
Linked Service
(Required) Select the option that specifies the auxiliary directory service ID provider from the dropdown list. Options are Local Account, LDAP, or NIS.
Add Idmap Screen with Idmap Backend as RFC2307
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to RFC2307 shares the same settings as the LDAP screen, and some of the same Options settings.
Idmap Backend - RFC2307 Settings
The RFC2307 settings in Options share the Idmap Backend settings as the LDAP option, but includes more configuration settings.
Setting
Description
LDAP User DN
(Required) Enter the user distinguished name (DN) to use for authentication.
LDAP User DN Password
Enter the password associated with the LDAP user DN.
URL
(Required) Enter the URL for the LDAP server to use for SID to UID/GID mapping. For example, ldap://ldap.netscap.com/o=Airus.com.
Encryption Mode
(Required) Select the encryption mode to use with LDAP from the dropdown list. Options are On, Off, or StartTLS.
LDAP Server
Select the type of LDAP server to use. This can be the LDAP server provided by the Active Directory server or a stand-alone LDAP server.
LDAP Realm
Enter the realm that performs authentication from an LDAP server.
User Bind Path
Enter the search base where user objects are found in the LDAP server.
Group Bind Path
Enter the search base where group objects are found in the LDAP server.
User CN
Enter the user common name (CN) to query the CN instead of the uid attribute for the user name in LDAP.
CN Realm
Append @realm to the CN in LDAP queries for both groups and users when you set the User CN.
LDAP Domain
Enter the domain to access the Active Directory server when using the LDAP server inside the Active Directory server.
Add Idmap Screen with Idmap Backend as RID
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to RID shares the same settings as the AD screen. There is only one Options setting.
Idmap Backend - RID Settings
Setting
Description
SSSD Compat
Select to generate the idmap low range based on the same algorithm that SSSD uses by default.
Add Idmap Screen with Idmap Backend as TDB
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to TDB shares the same settings as the AD screen. There is only one Options setting.
Idmap Backend - TDB Settings
Setting
Description
Read Only
Select to make the module read-only. No new ranges are allocated or new mappings created in the idmap pool.
Kerberos Settings Screen
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory in SCALE, SCALE 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 SCALE does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Settings Widget
The Kerberos Settings widget in the Advanced Settings on the Directory Services screen displays current settings.
Settings opens the Kerberos Settings configuration screen.
Kerberos Settings Screen
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
The Kerberos Settings screen includes two fields used to configure auxiliary parameters.
If you do not understand Kerberos auxiliary parameters, do not attempt to configure new settings!
Setting
Description
Appdefaults Auxiliary Parameters
Additional Kerberos application settings. See the appdefaults section of krb.conf(5) for available settings and usage syntax.
Libdefaults Auxiliary Parameters
Additional Kerberos library settings. See the libdefaults section of krb.conf(5) for available settings and usage syntax.
Kerberos Realms Screens
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory in SCALE, SCALE 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 SCALE does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Realm Widget
The Kerberos Realms widget in the Advanced Settings on the Directory Services screen displays currently configured realms.
Add opens the Add Kerberos Realm configuration screen.
Click on any instance to open the Edit Kerberos Realm screen.
Click on the Kerberos Realms widget header to open the Kerberos Realms screen.
Kerberos Realms Screen
The Kerberos Realms screen displays a list view of realms configured on your SCALE system.
Actions includes the option to Add a new realm. Add opens the Add Kerberos Realm screen.
The more_vert button opens the actions options for the selected realm. Options are Edit which opens the Edit Kerberos Realm screen for the selected realm, and Delete that opens a delete confirmation dialog.
Add and Edit Kerberos Realm Screens
The settings found on the Add Kerberos Realm and Edit Kerberos Realm screens are the same.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Setting
Description
Realm
(Required) Enter the name of the realm as a domain name, For example, example.com. AD configured SCALE systems pre-populate this field with the required information.
KDC
Enter the name of the Key Distribution Center (KDC).The KDC acts as as the third-party authentication service for Kerberos. Separate multiple values by pressing Enter. For example, kdc1.example.com press Enter then kdc2.example.com.
Admin Server
Define the server that performs all database changes. Separate multiple values by pressing Enter.
Password Server
Define the server that performs all password changes. Separate multiple values by pressing Enter.
Kerberos Keytab Screens
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).
If you configure Active Directory in SCALE, SCALE 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 SCALE does not automatically add the realm or key tab for these services.
After AD populates the Kerberos realm and keytabs, do not make changes. Consult with your IT or network services department, or those responsible for the Kerberos deployment in your network environment for help.
For more information on Kerberos settings refer to the MIT Kerberos Documentation.
Kerberos Keytab Widget
The Kerberos Keytab widget in the Advanced Settings on the Directory Services screen displays added keytabs.
Add opens the Add Kerberos Keytab configuration screen.
Click on any instance to open the Edit Kerberos Keytab screen.
The Kerberos Keytab widget header opens the Kerberos Keytabs screen.
Kerberos Keytab Screen
The Kerberos Realms screen displays a list view of realms configured on your SCALE system.
Actions includes the option to Add a new keytab. Add opens the Add Kerberos Keytab screen.
The more_vert button opens the actions options for the selected keytab. Options are Edit which opens the Edit Kerberos Keytab screen for the selected keytab, and Delete that opens a delete confirmation dialog.
Add and Edit Kerberos Keytab Screens
The settings found on the Add Kerberos Keytab and Edit Kerberos Keytab screens are the same.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it.
Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages.
Do not attempt configure or make changes if you do not know what you are doing!
Setting
Description
Name
Enter a name for this Keytab. If configured, SCALE populates this field with what it detects in Active Directory.
Kerberos Keytab
Browse to the keytab file to upload.
Backup Credentials
TrueNAS stores cloud backup services credentials, SSH connections, and SSH key pairs configured using the widgets on the Backup Credentials screen.
Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
BackupCredentialsAllCloudSSH—
title: “SSH Screens”
description: “Provides information on the SSH Connections and SSH Keypairs screens, widgets, and settings.”
weight: 20
tags:
ssh
credentials
key pair
key pairs
The Backup Credentials screen displays the SSH Connections and SSH Keypairs widgets.
You must also configure and activate the SSH Service to allow SSH access.
SSH Connection and Keypairs Widgets
The SSH Connections and SSH Keypairs widgets display a list of SSH connections and key pairs configured on the system.
Cloud Credentials Screens
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
The Cloud Credentials configuration screen opens pre-populated with Storj-iX as the provider.
It shows settings to add or edit cloud credentials TrueNAS uses to integrate with cloud storage providers.
Provider shows a list of available providers.
Select the name of a cloud provider to populate the configuration screen with credential settings for that provider.
Verify Credentials uses the credentials entered to verify access the cloud storage provider account.
Name and Provider Settings
The selection in Provider changes the Authentication settings.
Setting
Description
Provider
(Required) Default is set to Storj. Select the cloud storage provider from the options on the dropdown list.
Name
Enter a name for this cloud credential. For example, cloud1 or amazon1.
Storj iX Credential
Storj authentication includes going to the Storj iX sign-in screen to either create a new Storj iX account or log into an existing Storj iX account.
After configuring the Storj account in the Storj-iX portal return to SCALE to enter the S3 credentials provided by Storj.
Enter the alphanumeric key that is between 5 and 20 characters for the Amazon Web Services Key ID. Find this on Amazon AWS by going through My account > Security Credentials > Access Keys (Access Key ID and Secret Access Key).
Secret Access Key
Enter the alphanumeric key that is between 8 and 40 characters for the Amazon Web Services password. If you cannot find the Secret Access Key, go to My Account > Security Credentials > Access Keys and create a new key pair.
Amazon S3 Advanced Authentication Options
This section provides information on Amazon S3 advanced authentication settings for endpoints. The basic authentication settings are required when using the advanced settings.
Enter a value to define the maximum number of chunks for a multipart upload. Setting a maximum is necessary if a service does not support the 10,000 chunk AWS S3 specification.
Endpoint URL
(Optional) When using AWS, you can leave the endpoint field empty to use the default endpoint for the region and automatically fetch available buckets, or enter an S3 API endpoint URL. Refer to the AWS Documentation for a list of Simple Storage Service Website Endpoints.
Region
(Optional) Enter an AWS resources in a geographic area. Leave empty to detect the correct public region for the bucket. Entering a private region name allows interacting with Amazon buckets created in that region. For example, enter us-gov-east-1 to discover buckets created in the eastern AWS GovCloud region.
Disable Endpoint Region
Select to prevent automatic detection of the bucket region. Select only if your AWS provider does not support regions.
Use Signature Version 2
Select to force using Signature Version 2 to sign API requests. Select only if your AWS provider does not support default version 4 signatures.
BackBlaze B2 Credential
This section provides information on the BackBlaze B2 authentication settings.
Enter or copy and paste the alphanumeric Backblaze B2 Application Key ID string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.
Application Key
Enter or copy and paste the alphanumeric Backblaze B2 Application Key string into this field. To generate a new application key, log in to the Backblaze account, go to the App Keys page, and add a new application key.
OAuth and Access Token Authentication Credentials
Several cloud storage providers use OAuth authentication and a required access token to authenticate the cloud storage account.
Providers using these methods are Box, Dropbox, Google Photo, pCloud, and Yandex.
Use Login to Provider to enter the account username and password.
Setting
Description
OAuth Client ID
Enter the public identifier for the cloud application.
OAuth Client Secret
Enter the secret phrase known only to the cloud application and the authorization server.
Token
Enter a User Access Token for Box. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
Hostname
(Optional) pCloud only. Enter the host name to connect to.
FTP and SFTP Credentials
FTP and SFTP cloud storage providers use host name, port, and user credentials to authenticate accounts. SMTP uses SSH hosts, port, and user credentials and also uses a private key.
Enter the FTP host name or for SFTP the SSH host name to connect. For example, ftp.example.com.
Port
Enter the FTP or for SFTPP, the SSH port number. Leave blank to use the default port 21 for FTP or 22 for SFTP.
Username
Enter a username on the FTP or for the SFTP host system the SSJ user name. This user must already exist on the host.
Password
Enter the password for the user account.
Private Key ID
(SFTP only) Import the private key from an existing SSH keypair or, if no keypairs exist on the system, select Add on the SSH Keypairs widget to open the SSH Keypairs screen. Enter a name, and then click Generate New to create a new SSH key for this credential.
Use Choose File to browse to the file location on the server. Opens a file browser to select the Google service account key credential file generated by by the Google Cloud Platform Console to authenticate the account.
Preview JSON Service Account Key
Shows the json file downloaded to the system server from Google Cloud Storage and uploaded with Choose File.
Google Drive Credential
Google Drive also uses OAuth authentication, a required access token, and a team drive ID to authenticate accounts.
Google Drive adds one additional authentication setting to the general OAuth settings.
Enter an endpoint. For example, blob.core.usgovcloudapi.net.
OpenStack Swift Credential
OpenStack Swift uses several required settings to authenticate credential accounts.
The AuthVersion setting selection changes setting options displayed in Advanced Options.
(Required) Enter the Openstack API key or password. This is the OS_PASSWORD from an OpenStack credentials file.
Authentication URL
(Required) Enter the authentication URL for the server. This is the OS_AUTH_URL from an OpenStack credentials file.
AuthVersion
Select the authentication version from the dropdown list if your auth URL has no version (rclone documentation).
OpenStack Authentication Advanced Options
The Authentication Advanced Options screen shows different options based on the AuthVersion setting.
Auto(vX), v1, and v2 use the same advanced authentication settings.
(Optional for v1 auth) Enter the tenant ID Enter the tenant ID. For more information see rclone documentation.
Auth Token
(Optional) Enter the auth token from alternate authentication. For more information see rclone documentation.
Region Name
(Optional) Enter the region name. For more information see rclone documentation.
Storage URL
(Optional) Enter the storage URL. For more information see rclone documentation.
Endpoint Type
Select service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended. For more information see rclone documentation.
V3 Authentication Settings
Setting AuthVersion to v3 shows additional authentication settings.
Required for v2 and v3. Enter the tenant ID. For more information see rclone documentation.
Tenant Domain
(Optional) Enter the tenant domain. For more information see rclone documentation.
Auth Token
(Optional) Enter the auth token from alternate authentication. For more information see rclone documentation.
Region Name
(Optional) Enter the region name. For more information see rclone documentation.
Storage URL
(Optional) Enter the storage URL. For more information see rclone documentation.
Endpoint Type
Select service catalog option from the Endpoint Type dropdown. Options are Public, Internal and Admin. Public is recommended. For more information see rclone documentation.
WebDAV Credential
WebDAV uses a URL, service type and user credentials to authenticate account cloud account credentials.
(Required) Enter the URL of the HTTP host to connect to.
WebDAV Service
(Required) Select the name of the WebDAV site, service, or software used from the dropdown list. Options are NEXTCLOUD, OWNCLOUD, SHAREPOINT, or OTHER.
Username
(Required) Enter the WebDAV account user name.
Password
(Required) Enter the WebDAV account password.
BackupCredentialsAllCloudSSH—
title: “SSH Screens”
description: “Provides information on the SSH Connections and SSH Keypairs screens, widgets, and settings.”
weight: 20
tags:
ssh
credentials
key pair
key pairs
The Backup Credentials screen displays the SSH Connections and SSH Keypairs widgets.
You must also configure and activate the SSH Service to allow SSH access.
SSH Connection and Keypairs Widgets
The SSH Connections and SSH Keypairs widgets display a list of SSH connections and key pairs configured on the system.
The SSH Connections widget allows users to establish Secure Socket Shell (SSH) connections.
The SSH Keypairs widget allows users to generate SSH key pairs required to authenticate the identity of a user or process that wants to access the system using SSH protocol.
Add in the SSH Connections widget opens the SSH Connections configuration window.
The connection name on the widget is a link that opens the SSH Connections configuration screen already populated with the saved settings for the selected connection.
SSH Connections Screens
The settings on the SSH Connections configuration screens are the same whether you add a new connection or edit an existing connection.
(Required) Enter a unique name for this SSH connection. For example, use ssh and a server name or number like sshsys1 or sshtn121 where sys1 or tn121 are server designations.
Setup Method
Select the setup method to use from the dropdown list of options. Options are:
Semi-automatic (TrueNAS only) - Select to simplify setting up an SSH connection with another TrueNAS or FreeNAS system without logging into that system to transfer SSH keys. The default is set to Semi-automatic (TrueNAS only).
Manual - Select to enter all settings when setting up an SSH connection with a non-TrueNAS server. Displays other setting options required to manually configure an SSH connection. Requires copying a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.
Authentication - Semi-Automatic Method Settings
These authentication settings show when Setup Method is Semi-automatic (TrueNAS only).
(Required) Enter the host name or IP address of the remote system. Use a valid URL scheme for the remote TrueNAS URL. IP address example of https://10.231.3.76.
Admin Username
Enter the user name for logging into the remote system. The default is set to root but change this to the name of the system administrator for the remote system for this connection.
Admin Password
(Required) Enter the administrator user account password for logging into the remote system.
One-Time Password (if necessary)
One-time password if two-factor authentication is enabled.
Username
(Required) Username on the remote system used to log in via SSH.
Private Key
(Required) Select a saved SSH key pair, import the private key from a previously created SSH key pair, or select Generate New to create a new key pair to use for the connection to this remote system.
Authentication - Manual Method Settings
These authentication settings show when Setup Method is Manual. You must copy a public encryption key from the local system to the remote system.
A manual setup allows a secure connection without a password prompt.
(Required) Enter the host name or IP address of the remote system. A valid URL scheme is required. An IP address example is https://10.231.3.76.
Port
(Required) Enter the port number on the remote system to use for the SSH connection.
Username
(Required) Enter the user name for logging into the remote system.
Private Key
(Required) Select a saved SSH key pair or select Generate New to create a new key pair to use for the connection to this remote system.
Remote Host Key
Enter the remote system SSH key for this system to authenticate the connection. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate this field.
Discover Remote Host Key
Click to connect to the remote system and attempt to copy the key string to the related TrueNAS field.
The name of the key pair listed on the widget is a link that opens the SSH Keypairs configuration screen.
The download icon, and the more_vert at the bottom of the SSH Keypairs configuration screen, download the public and private key strings as text files for later use.
The delete delete icon opens the delete dialog. Click Confirm and then Delete to remove the stored key pairs from the system.
SSH Keypairs Screen
The SSH Keypairs configuration screen displays the same settings for both add and edit options. Click Add to open a new configuration form, or click on an existing key pair to open the configuration screen populated with the settings for the selected key pair.
Required. Enter a unique name for this SSH key pair. Automatically generated key pairs are named after the object that generated the key pair with key appended to the name.
Generate Keypair
Click to have TrueNAS SCALE automatically generate a new key pair and populate the Private Key and Public Keys fields with these values.
Save adds the key pair to the widget and activates the more_vert with options to Download Private Key and Download Public key.
Certificates
The Certificates screen displays widgets for Certificates, Certificate Signing Requests (CSRs), Certificate Authorities (CA), and ACME DNS-Authenticators that each provice access to all the information for certificates, certificate signing requests (CSRs), certificate authorities (CA), and ACME DNS-authenticators respectively.
Each 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.
Contents
Certificates Screens: Provides information on the Certificates screens and settings.
The Certificates widget on the Credentials > Certificates screen displays certificates added to SCALE and allows you to add new certificates, or download, delete, or edit the name of an existing certificate. Each TrueNAS has an internal, self-signed certificate that enables encrypted access to the web interface.
The download icon downloads the certificate to your server.
delete deletes the certificate from your server.
Each certificate listed on the widget is a link that opens the Edit Certificate screen.
The Add Certificate wizard screens guide users through configuring a new certificate on TrueNAS SCALE.
The wizard has five different configuration screens, one for each step in the certificate configuration process:
Before you create a new certificate, configure a new CA if you do not already have one on your system. Creating an internal certificate requires a CA to exist on the system.
The Identifier and Type options specify the certificate name and choose whether to use it for internal or local systems or import an existing certificate. Users can also select a predefined certificate extension from the Profiles dropdown list.
Click Here for More Information
The selection in Type changes setting options on this screen, the Certificate Options and Extra Constraints screens, and determines if the Certificate Subject screen displays at all.
Setting
Description
Name
Required. Enter a descriptive identifier for this certificate.
Type
Select the certificate type from the dropdown list. Internal Certificate uses system-managed CAs for certificate issuance. Import Certificate allows you to import an existing certificate onto the system. Import Certificate removes the Profiles field and changes other screens and fields displayed on other wizard screens.
Profile
Select a predefined certificate extension. Options are HTTPS RSA Certificate or HTTPS ECC Certificate. Choose a profile that best matches your certificate usage scenario.
Certificate Options
Certificate Options settings choose the signing certificate authority (CSR), the type of private key type to use (as well as the number of bits in the key used by the cryptographic algorithm), the cryptographic algorithm the certificate uses, and how many days the certificate authority lasts.
The Certificate Options settings change based on the selection in Type on the Identifier and Type screen.
Certificate Options - Internal Certificate
The Key Type selection changes fields displayed. RSA is the default setting in Key Type.
The Signing Certificate Authority field requires you to have a CA already configured on your system.
If you do not have a Certificate Authority (CA) configured on your system, exit the Add Certificate wizard and add the required CA.
Click Here for More Information
Setting
Description
Signing Certificate Authority
Required. Select a previously imported or created CA from the dropdown list.
Required. Displays when Key Type is set to RSA. The number of bits in the key used by the cryptographic algorithm. For security reasons, a minimum key length of 2048 is recommended.
EC Curve
Displays when Key Type is set to EC. Select the Brainpool or SECP curve that fits your scenario. Brainpool curves can be more secure than SECP curves but SECP curves can be faster. Options are BrainpoolP512R1, BrainpoolP384R1, BrainpoolP256R1, SECP256R1, SECP384R1, SECP521R1, and ed25519. See Elliptic Curve performance: NIST vs Brainpool for more information.
Digest Algorithm
Required. Select the cryptographic algorithm to use from the dropdown list. Options are SHA1, SHA224, SHA256, SHA384 or SHA512. Only change the default SHA256 if the organization requires a different algorithm.
Lifetime
Required. Enter the number of days for the lifetime of the CA.
Certificate Options - Import Certificate
Setting Type on the Identifier and Type screen to Import Certificate changes the options displayed on the Certificate Options configuration screen.
Click Here for More Information
Setting
Description
Certificate
Required. Paste the certificate for the CA into this field.
CSR exists on this system
Select if importing a certificate for which a CSR exists on this system. Displays the Certificate Signing Request dropdown.
Certificate Signing Request
Select the existing CSR from the dropdown list.
Private Key
Required. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
Passphrase
Enter the passphrase for the private key.
Confirm Passphrase
Re-enter the passphrase for the private key.
Certificate Subject Options
The Certificate Subject step lets users define the location, name, and email of the organization using the certificate. Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
The Certificate Subject screen does not display when Type on Internal Certificate is set to Import Certificate.
Click Here for More Information
Setting
Description
Country
Required. Select the country of the organization from the dropdown list.
State
Required. Enter the state or province of the organization.
Locality
Required. Enter the location of the organization. For example, the city.
Organization
Required. Enter the name of the company or organization.
Organizational Unit
Enter the organizational unit of the entity.
Email
Required. Enter the email address of the person responsible for the CA.
Required. Enter additional domains to secure for multi-domain support. Separate each domain by pressing Enter. For example, if the primary domain is example.com, entering www.example.com* secures both addresses.
Extra Constraints Options
The Extra Constraints step contains certificate extension options.
Basic Constraints limits the path length for a certificate chain.
Authority Key Identifier provides a means of identifying the public key corresponding to the private key used to sign a certificate.
Key Usage defines the purpose of the public key contained in a certificate.
Extended Key Usage further refines key usage extensions.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
Extra Constraints - Internal Certificate
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that the option needs.
Click Here for More Information
Setting
Description
Basic Constraints
Select to activate this extension to identify whether the certificate subject is a CA and the maximum depth of valid certification paths that include this certificate. Options are CA or Critical Extension. Selecting Basic Constraints displays the Path Length and Basic Constraints Config fields.
Path Length
Displays after selecting Basic Constraints. Enter a value of 0 or greater to set how many non-self-issued intermediate certificates can follow this certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Value cannot be less than 0.
Basic Constraints Config
Select the option to specify whether to use the certificate for a Certificate Authority and whether this extension is critical. Clients must recognize critical extensions to prevent rejection. Web certificates typically require you to disable CA and enable Critical Extension in Basic Constraints.
Authority Key Identifier
Select to activate this extension. The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a certificate. This extension is used where the issuer has multiple signing keys (either due to multiple concurrent key pairs or due to changeover). The identification might be based on either the key identifier (the subject key identifier in the issuer certificate) or on the issuer name and serial number. See RFC 3280, section 4.2.1.1 for more information. Displays the Authority Key Config field.
Authority Key Config
Displays after selecting Authority Key Identifier. Select the option to specify whether the issued certificate should include authority key identifier information and whether the extension is critical. Critical extension must be recognized by the client or be rejected. Options are Authority Cert Issuer and or Critical Extension. Multiple selections display separated by a comma (,).
Extended Key Usage
Select to activate this certificate extension. The Extended Key Usage extension identifies and limits valid uses for this certificate, such as client authentication or server authentication. See RFC 3280, section 4.2.1.13 for details. Displays the Usages field.
Usages
Displays after selecting Extended Key Usage. Select the option to identify the purpose of this public key from the dropdown list. Typically used for the end entity certificates. You can select multiple usages that display separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CERTIFICATE_TRANSPARENCY, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_IKE, KERBEROS_PKINIT_KDC, OCSP_SIGNING, SERVER_AUTH, SMARTCARD_LOGON or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. The purpose of the certificate must be consistent with both extensions when using both Extended Key Usage and Key Usage extensions. See [RFC 3280, section 4.2.1.13 for more details.
Critical Extension
Select to identify this extension as critical for the certificate. The certificate-using system must recognize the critical extensions to prevent this certificate from being rejected. The certificate-using system can ignore extensions identified as not critical and still approve the certificate.
Key Usage
Select to activate this certificate extension. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that can be used for more than one operation is to be restricted. For example, when an RSA key should be used only to verify signatures on objects other than public key certificates and CRLs, the Digital Signature bits are asserted. Likewise, when an RSA key should be used only for key management, the Key Encipherment bit is asserted. See RFC 3280, section 4.2.1.3 for more information. Displays the Key Usage Config field.
Key Usage Config
Displays after selecting Extended Key Usage or Key Usage. Select the option that specifies valid key usages for this certificate. Options are Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. Web certificates typically need at least Digital Signature and possibly Key Encipherment or Key Agreement, while other applications might need other usages.
Import Certificate Options
When Type on Identifier and Type is set to Import Certificate the Import Certificate options screen displays.
Click Here for More Information
Setting
Description
Certificate
Required. Paste the certificate for the CA into this field.
CSR exists on this system
Select if importing a certificate for which a CSR exists on this system. Displays the Certificate Signing Request dropdown.
Certificate Signing Request
Select an existing CSR from the dropdown list.
Private Key
Required. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
Passphrase
Enter the passphrase for the private key.
Confirm Passphrase
Re-enter the passphrase for the private key.
Confirm Options
The final step screen is the Confirm Options that displays the certificate Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and any configured Usages.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
Edit Certificate Screen
The certificate listed on the Certificates widget is a link that opens the Edit Certificate screen.
The Edit Certificate screen displays the fixed Subject settings, the type, path, and other details about that certificate that are not editable.
You can enter an alphanumeric name for the certificate in Identifier if you want to rename the certificate. You can use underscore (_) and or dash (-) characters in the name.
View/Download Certificate opens a window with the certificate string. Use the assignment clipboard icon to copy the certificate to the clipboard or Download to download the certificate to your server. Keep the certificate in a secure area where you can back up and save it.
View/Download Key opens a window with the certificate private key. Use the assignment clipboard icon to copy the public key to the clipboard or Download to download the key to your server. Keep the private key in a secure area where you can back up and save it.
Certificates Authorities Screens
The Certificate Authorities widget on the Credentials > Certificates screen displays certificate authorities(CAs) added to SCALE, and allows you to add new CAs, or download, delete, or edit the name of an existing CA.
The download icon downloads the CA to your server.
delete deletes the CA from your server.
Each CA listed on the widget is a link that opens the Edit CA screen.
Add opens the Add CA wizard that steps you through setting up a certificate authority (CA) that certifies the ownership of a public key by the named subject of the certificate.
Add CA Wizard Screens
The Add CA wizard screens step users through configuring a new certificate authority on TrueNAS SCALE.
The wizard has five different configuration screens, one for each step in the CA configuration process:
The Identifier and Type options specify the CA name and choose whether to create a new CA or import an existing CA. Users can also select a predefined certificate extension from the Profiles dropdown list.
Click Here for More Information
The selection in Type changes setting options on this screen, the Certificate Options and Extra Constraints screens, and determines if the Certificate Subject screen displays at all.
Setting
Description
Name
Required. Enter a descriptive identifier for this certificate authority(CA).
Type
Select the type of CA from the dropdown list. Options are Internal CA, Intermediate CA, and Import CA. Internal CA functions like a publicly trusted CA to sign certificates for an internal network. They are not trusted outside the private network. Intermediate CA lives between the root and end entity certificates and its main purpose is to define and authorize the types of certificates you can request from the root CA. Import CA allows you to import an existing CA onto the system. For more information see What are Subordinate CAs and Why Would You Want Your Own?.
Profiles
Displays if Internal CA or Intermediate CA are set in Type. Select a predefined certificate extension from the dropdown list. Choose a profile that best matches your certificate usage scenario. Options are Openvpn Root CA and CA.
Certificate Options
The Certificate Options settings specify the type of private key to use (as well as the number of bits in the key used by the cryptographic algorithm), the cryptographic algorithm the CA uses, and how many days the CA lasts.
The Certificate Options settings do not display if Type on the Identifier and Type screen is set to Import CA.
The Key Type selection changes fields displayed. RSA is the default setting in Key Type.
Click Here for More Information
Displays when EC is selected in Key Type. Select the curve type from the dropdown list. Options are BrainpoolP512R1, BrainpoolP384R1, BrainpoolP256R1, SECP256K1, SECP384R1, SECP521R1, and ed25519. Brainpool curves can be more secure while SECP curves can be faster. See Elliptic Curve performance: NIST vs Brainpool for more information.
Key Length
Required. Displays when RSA is selected in Key Type. Select the number of bits in the key used by the cryptographic algorithm from the dropdown list. Options are 1024, 2048 or 4096. For security reasons, a minimum key length of 2048 is recommended.
Digest Algorithm
Select the cryptographic algorithm to use from the dropdown list.Options are SHA1, SHA224, SHA256, SHA384 and SHA512. Only change the default SHA256 if the organization requires a different algorithm.
Lifetime
Enter the number of days for the lifetime of the CA.
Certificate Subject Options
The Certificate Subject settings define the location, name, and email for the organization using the certificate. Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
The Certificate Subject settings do not display if Type on the Identifier and Type screen is set to Import CA.
Click Here for More Information
Setting
Description
Country
Required. Select the country of the organization from the dropdown list.
State
Required. Enter the state or province of the organization.
Locality
Required. Enter the location of the organization. For example, the city.
Organization
Required. Enter the name of the company or organization.
Organizational Unit
Enter the organizational unit of the entity.
Email
Required. Enter the email address of the person responsible for the CA.
Required. Enter additional domains to secure for multi-domain support. Separate each domain by pressing Enter. For example, if the primary domain is example.com, entering www.example.com secures both addresses.
Extra Constraints Options
The Extra Constraints options contain certificate extension options.
Basic Constraints that when enabled limits the path length for a certificate chain.
Authority Key Identifier that when enabled provides a means of identifying the public key corresponding to the private key used to sign a certificate.
Key Usage that when enable defines the purpose of the public key contained in a certificate.
Extended Key Usage that when enable to further refines key usage extensions.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
Extra Constraints - Internal or Intermediate CA
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that option needs.
Click Here for More Information
Setting
Description
Basic Constraints
Select to activate this extension.
Path Length
Displays after selecting Basic Constraints. Enter the number of non-self-issued intermediate certificates that can follow this certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Value cannot be less than 0.
Basic Constraints Config
Select the option to specify the extension type from the dropdown list. Options are CA and Critical Extension. The basic constraints extension identifies whether the subject of the certificate is a CA and the maximum depth of valid certification paths that include this certificate. See RFC 3280, section 4.2.10 for more information.
Authority Key Identifier
Select to activate this extension. Displays the Authority Key Config field.
Authority Key Config
Displays after selecting Authority Key Identifier. Select the option to specify whether the authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a certificate. Options are Authority Cert Issuer and or Critical Extension. This extension is used where an issuer has multiple signing keys (either due to multiple concurrent key pairs or due to changeover). The identification might be based on either the key identifier (the subject key identifier in the issuer certificate) or on the issuer name and serial number. See RFC 3280, section 4.2.1.1 for more information.
Extended Key Usage
Select to activate this certificate extension. Displays the Usages field.
Usages
Displays after selecting Extended Key Usage. Select the option to identify the purpose of this public key from the dropdown list. Typically used for the end entity certificates. You can select multiple usages that display separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, OCSP_SIGNING, SERVER_AUTH, or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. Using both Extended Key Usage and Key Usage extensions requires that the purpose of the certificate is consistent with both extensions. See RFC 3280, section 4.2.13 for more details.
Critical Extension
Displays after selecting Extended Key Usage. Select to identify this extension as critical for the certificate. The certificate-using system must recognize critical extensions or this certificate is rejected. T he certificate-using system can ignore the extensions identified as not critical and still approve the certificate.
Key Usage
Select to activate this certificate extension. Displays the Key Usage Config field.
Key Usage Config
Displays after selecting Extended Key Usage or Key Usage. Select the key usage extension from the dropdown list. Options are Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that could be used for more than one operation is to be restricted. For example, when an RSA key should be used only to verify signatures on objects other than public key certificates and CRLs, the Digital Signature bits would be asserted. Likewise, when an RSA key should be used only for key management, the Key Encipherment bit would be asserted.
When Type on Identifier and Type is set to Import CA the Import Certificate screen displays.
Click Here for More Information
Setting
Description
Certificate
Required. Paste the certificate for the CA into this field.
Private Key
Required. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
Passphrase
Enter the passphrase for the private key.
Confirm Passphrase
Re-enter the passphrase for the private key.
Confirm Options
The final step screen is the Confirm Options that displays the CA Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and any configured Usages.
For Import CA type, the screen displays Type and Certificate.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
Certificate Signing Requests Screens
The Certificates screen includes the Certificate Signing Requests widget that displays a list of certificate signing requires (CSRs) configured on the system.
Each CSR listed is a link that opens the Edit CA screen for the selected CSR.
The download icon downloads the CSR to your server.
delete deletes the CSR from your server.
Each CSR listed on the widget is a link that opens the Edit CSR screen.
Add opens the Add CSR wizard that steps you through setting up a CSR that certifies the ownership of a public key by the named subject of the certificate.
The Certificate Signing Requests section allows users to configure the message(s) the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
Add CSR Wizard Screens
The Add CSR wizard screens step users through configuring a new certificate signing request (CSR) on TrueNAS SCALE.
The wizard has five different configuration screens, one for each step in the CA configuration process:
The Identifier and Type settings specify the certificate signing request (CSR) name and whether to create a new CSR or import an existing CSR. Users can also select a predefined certificate extension from the Profile dropdown list.
Click Here for More Information
The selection in Type changes setting options on this screen, the Certificate Options and Extra Constraints screens, and determines if the Certificate Subject screen displays at all.
Setting
Description
Name
Required. Enter a descriptive identifier for this certificate.
Type
Select the type of CSR from the dropdown list. Options are Certificate Signing Request and Import Certificate Signing Request. Certificate Signing Requests control when an external CA issues (signs) the certificate. Typically used with ACME or other CAs that most popular browsers trust by default. Import Certificate Signing Request lets you import an existing CSR onto the system. Typically used with ACME or internal CAs. Selecting Import Certificate Signing Request removes the Profile field.
Profile
Displays if Certificate Signing Request is set in Type. Select a predefined certificate extension from the dropdown list. Choose a profile that best matches your certificate usage scenario. Options are HTTPS RSA Certificate and HTTPS ECC Certificate.
Certificate Options
The Certificate Options settings specify the type of private key type to use, the number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.
There are no Certificate Options settings if Type on the Identifier and Type screen is set to Import Certificate Signing Request.
The Key Type selection changes fields displayed. RSA is the default setting in Key Type.
Click Here for More Information
Displays when EC is selected in Key Type. Select the curve type from the dropdown list. Options are BrainpoolP512R1, BrainpoolP384R1, BrainpoolP256R1, SECP256K1, SECP384R1, SECP521R1, and ed25519. Brainpool curves can be more secure while SECP curves can be faster. See Elliptic Curve performance: NIST vs Brainpool for more information.
Key Length
Required. Displays when RSA is selected in Key Type. Select the number of bits in the key used by the cryptographic algorithm from the dropdown list. Options are 1024, 2048 or 4096. For security reasons, a minimum key length of 2048 is recommended.
Digest Algorithm
Select the cryptographic algorithm to use from the dropdown list. Options are SHA1, SHA224, SHA256, SHA384 and SHA512. Only change the default SHA256 if the organization requires a different algorithm.
Lifetime
Enter the number of days for the lifetime of the CA.
Certificate Subject Settings
The Certificate Subject settings lets users define the location, name, and email for the organization using the certificate.
Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
The Certificate Subject settings do not display if Type on the Identifier and Type screen is set to Import Certificate Signing Request.
Click Here for More Information
Setting
Description
Country
Required. Select the country of the organization from the dropdown list.
State
Required. Enter the state or province of the organization.
Locality
Required. Enter the location of the organization. For example, the city.
Organization
Required. Enter the name of the company or organization.
Organizational Unit
Enter the organizational unit of the entity.
Email
Required. Enter the email address of the person responsible for the CA.
Required. Enter additional domains to secure for multi-domain support. Separate each domain by pressing Enter. For example, if the primary domain is example.com, entering www.example.com secures both addresses.
Extra Constraints Settings
The Extra Constraints settings contains certificate extension options:
Basic Constraints that when enabled limits the path length for a certificate chain.
Authority Key Identifier that when enabled provides a means of identifying the public key corresponding to the private key used to sign a certificate.
Key Usage that when enabled defines the purpose of the public key contained in a certificate.
Extended Key Usage that when enabled further refines key usage extensions.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
Extra Constraints - Certificate Signing Request Type
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that option needs.
Click Here for More Information
Setting
Description
Basic Constraints
Select to activate this extension. Basic Constraints extension identifies whether this certificate subject is a CA and the maximum depth of valid certification paths that include this certificate.
Path Length
Displays after selecting Basic Constraints. Enter how many non-self-issued intermediate certificates that can follow this certificate in a valid certification path. Entering 0 allows a single additional certificate to follow in the certificate path. Value cannot be less than 0.
Basic Constraints Config
Select the option to specify the extension type from the dropdown list. Options are CA and Critical Extension. Specify whether to use the certificate for a Certificate Authority and whether this extension is critical. Clients must recognize critical extensions to prevent rejection. Web certificates typically require you to disable CA and enable Critical Extension.
Extended Key Usage
Select to activate this certificate extension. The Extended Key Usage extension identifies and limits valid uses for this certificate, such as client authentication or server authentication. See RFC 3280, section 4.2.1.13 for more details. Displays the Usages field.
Usages
Displays after selecting Extended Key Usage. Select the option to identify the purpose of this public key from the dropdown list. Typically used for the end entity certificates. You can select multiple usages that display separated by a comma (,). Options are ANY_EXTENDED_KEY_USAGE, CERTIFICATE_TRANSPARENCY, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_IKE, KERBEROS_PKINIT_KDC, OCSP_SIGNING, SERVER_AUTH, SMARTCARD_LOGON, or TIME_STAMPING. Do not mark this extension critical when set to ANY_EXTENDED_KEY_USAGE. Using both Extended Key Usage and Key Usage extensions requires that the purpose of the certificate is consistent with both extensions. See RFC 3280, section 4.2.13 for more details.
Critical Extension
Displays after selecting Extended Key Usage. Select to identify this extension as critical for the certificate. Critical extensions must be recognized by the certificate-using system or this certificate is rejected. Extensions identified as not critical can be ignored by the certificate-using system and the certificate still approved.
Key Usage
Select to activate this certificate extension. Displays the Key Usage Config field. The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that could be used for more than one operation is to be restricted. For example, when an RSA key should be used only to verify signatures on objects other than public key certificates and CRLs, the Digital Signature bits are asserted. Likewise, when an RSA key should be used only for key management, the Key Encipherment bit is asserted. See RFC 3280, section 4.2.13 for more information.
Key Usage Config
Displays after selecting Extended Key Usage or Key Usage. Select the key usage extension from the dropdown list. Options are Digital Signature, Content Commitment, Key Encipherment, Data Encipherment, Key Agreement, Key Cert Sign, CRL Sign, Encipher Only, Decipher Only or Critical Extension. Web certificates typically need at least Digital Signature and possibly Key Encipherment or Key Agreement, while other applications may need other usages.
Import Certificate Signing Request Type Options
When Type on Identifier and Type is set to Import Certificate Signing Request the Import Certificate screen displays.
Click Here for More Information
Setting
Description
Signing Request
Required. Paste the certificate for the certificate signing request into this field.
Private Key
Required. Paste the private key associated with the certificate when available. Provide a key at least 1024 bits long.
Passphrase
Enter the passphrase for the private key.
Confirm Passphrase
Re-enter the passphrase for the private key.
Confirm Options
The final step screen is the Confirm Options that displays the CA Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and Basich Constraints Config.
For Import Certificate Signing Request type, the screen displays Type, Signing Request and Private Key.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
ACME DNS-Authenticators Screens
The Certificates screen includes the ACME DNS-Authenticators widget that displays a list of configured authenticators.
The Automatic Certificate Management Environment (ACME) DNS-Authenticators screen allows 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.
Required. Enter an internal identifier for the authenticator.
Authenticator
Select a DNS provider from the dropdown list and configure any required authenticator attributes. Options are cloudflare, Amazon route53, OVH, and shell.
Cloudflare
cloudflare activates the Cloudflare Email, API Key, and API Token fields.
Enables users to pass an authenticator script, such as acme.sh, to shell and add an external DNS authenticator. shell activates the Authenticator script, Running user, Timeout, and Propagation delay fields.
The shell authenticator option is meant for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.
Enter the path to an ACME DNS authenticator script on the system.
Running user
Enter the username of the account that initiates the script, usually admin.
Timeout
Enter a timeout length (in seconds) for generated certificates.
Propagation delay
Enter a DNS propagation delay time (in seconds) for ISP domain caching.
KMIP Screen
TrueNAS Enterprise
KMIP on TrueNAS SCALE Enterprise is used to integrate the system within an existing centralized key management infrastructure and use a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
The KMIP screen has two areas, KMIP Key Status that displays keys synced between a KMIP server and TrueNAS database and KMIP Server with the KMIP configuration settings.
The KMIP Key Status area of the KMIP screen lists ZFS/SED keys synced between a KMIP server and the TrueNAS database.
Sync Keys synchronizes keys issued by the KMIP server with the TrueNAS database. This button is active when a KMIP key sync is pending.
Clear Sync Keys cancels a pending synchronization. This button is active when a KMIP key sync is pending or in progress but not completed.
KMIP Server Settings
Setting
Description
Server
Enter the host name or IP address of the central key server.
Port
Enter the connection port number on the central key server. Default value 5696 is the kmip.truenas.com port number.
Certificate
Select an existing certificate or enter a new one to use for key server authentication. Requires a valid certificate to verify the key server connection. Warning: for security reasons, protect the certificate used for key server authentication.
Certificate Authority
Select an certificate authority (CA) or enter a new one to use for connecting to the key server. Requires a valid CA public certificate to authenticate the connection. Warning: for security reasons, protect the certificate authority used for key server authentication.
Manage SED Passwords
Select to manage self-encrypting drive (SED) passwords with KMIP. Enabling this option allows the key server to manage creating or updating the global SED password, creating or updating individual SED passwords, and retrieving SED passwords when SEDs are unlocked. Disabling this option leaves SED password management with the local system.
Manage ZFS Keys
Select to use the KMIP server to manage ZFS encrypted dataset keys. The key server stores, applies, and destroys encryption keys whenever an encrypted dataset is created, when an existing key is modified, an encrypted dataset is unlocked, or an encrypted dataset is removed. Disabling this option leaves all encryption key management with the local system.
Enabled
Select to activate KMIP configuration and begin syncing keys with the KMIP server.
Change Server
Select to move existing keys from the current key server to a new key server. To switch to a different key server, enable key synchronization, then select this setting, update the key server connection configuration, and click Save.
Validate Connection
Select to test the server connection and verify the chosen certificate chain. To test, configure the Server and Port values, select a Certificate and Certificate Authority, select this setting, and click Save.
Force Clear
Select to cancel any pending key synchronization.
Virtualization
The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) and VM devices.
The No Virtual Machines screen displays if there are no VMs configured on the system or if you delete all VMs on the system.
Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.
The screen displays a list of VMs configured on the TrueNAS SCALE system.
The State toggle displays and changes the state of the VM.
Autostart, when selected, automatically starts the VM if the system reboots, otherwise you must manually start the VM.
Click on a VM to expand it and open the details screen with details on that VM and options for a VM.
Click Start to start the VM and show additional options.
Create Virtual Machine Wizard Screens
The Create Virtual Machine configuration wizard displays all settings to set up a new virtual machine.
Use Next and Back to advance to the next or return to the previous screen to change a setting.
Use Save to close the wizard screens and add the new VM to the Virtual Machines screen.
Operating System Screen
The Operating System settings specify the VM operating system type, the time the VM system clock uses, the boot method, and display type.
Required. Select the VM operating system type from the dropdown list. Options are Windows which adds the Enable Hyper-V Enlightenments option. Linux, and FreeBSD.
Enable Hyper-V Enlightenments
Only displays when Guest Operating System is set to Windows. This emulates a Hyper-V-compatible hypervisor for the Windows guest operating system and makes some Hyper-V-specific features available.
Name
Required. Enter an alphanumeric name for the virtual machine.
Description
(Optional) Enter a description of your choosing. For example, the type of OS for the VM or the VM use.
System Clock
Select the method to use to set the system the VM from the dropdown list. Options are Local which uses the TrueNAS SCALE system clock setting, or UTC to use the Coordinated Universal Time clock. The default is Local.
Boot Method
Select the boot method option from the dropdown list. Options are UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout
Enter the time in seconds the system waits for the VM to cleanly shut down. During system shutdown, the system initiates power-off for the VM after the shutdown timeout entered expires.
Start on Boot
Select to start the VM when the system boots. Selected by default.
Enable Display
Enables a display (Virtual Network Computing) remote connection. Requires UEFI booting. Selected by default.
Bind
Displays when Enable Display is selected. Select an IP address to use for remote VNC sessions. Note that this setting only applies if you are using a VNC client other than the TrueNAS WebUI.
Password
Displays when Enable Display is selected. Enter a password for the VNC display to use to securely access the VM.
CPU and Memory Screen
The CPU and Memory settings specify the CPU mode, model, and memory size. They also let you specify the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.
(Required) Enter the number of virtual CPUs to allocate to the virtual machine. The maximum is 16, or fewer if the host CPU limits the maximum. The VM operating system might impose operational or licensing restrictions on the number of CPUs. Default setting changes with the option selected in Guest OS, for Windows it is 2, for Unix-type it is 1.
Cores
(Required) Enter the number of cores per virtual CPU socket. The product of vCPUs, cores, and threads must not exceed 16.
Threads
(Required) Enter the number of threads per core. A single CPU core can have up to two threads per core. A dual-core could have up to four threads. The product of vCPUs, cores, and threads must not exceed 16.
Optional: CPU Set (Examples: 0-3,8-11)
Specify the logical cores that the VM can use. Better cache locality can be achieved by setting the CPU set based on CPU topology. E.g. to assign cores: 0,1,2,5,9,10,11 you can write: 1-2,5,9-11
Pin vcpus
When the number of vCPUs equals the number of CPUs in CPU Set, vCPUs can be automatically pinned into CPU Set. Pinning is done by mapping each vCPU into a single CPU number following the order in CPU Set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Select the CPU mode attribute from the dropdown list to allow your guest VM CPU to be as close to the host CPU as possible. Select Custom to make it so a persistent guest virtual machine sees the same hardware no matter what physical machine the guest VM boots on. It is the default if the CPU mode attribute is not specified. This mode describes the CPU presented to the guest. Select Host Model to use this shortcut to copy the physical host machine CPU definition from the capabilities XML into the domain XML. As the CPU definition copies just before starting a domain, a different physical host machine can use the same XML while still providing the best guest VM CPU each physical host machine supports. Select Host Passthrough when the CPU visible to the guest VM is the same as the physical host machine CPU, including elements that cause errors within libvirt. The downside of this is you cannot reproduce the guest VM environment on different hardware.
CPU Model
Select a CPU model to emulate.
Memory Size
Allocate RAM for the VM. The minimum value is 256 MiB. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to bytes.
Minimum Memory Size
(Optional) When not specified, the guest system is given a fixed amount of memory specified in Memory Size. When minimum memory is specified, the guest system is given memory within a range between minimum and fixed as needed. Enter a value smaller than the Memory Size to enable a variable RAM amount as needed within a range between this value and the one entered in Memory Size.
Optional: NUMA nodeset (Example: 0-1)
Node set allows setting NUMA nodes for multi NUMA processors when CPU set was defined. To achieve better memory locality, setting nodeset based on assigned cpuset. For example, if CPUs 0,1 belong to NUMA node 0, then setting nodeset to 0 improves memory locality.
Disks Screen
The Disks settings allow specifying how virtual disks are added. Options are to create a new zvol on an existing dataset for a disk image or use an existing zvol or file for the VM. You also specify the disk type, zvol location, and size.
Select to create a new zvol on an existing dataset to use as a virtual hard drive for the VM.
Use existing disk image
Select to use an existing zvol or file for the VM. Displays the Select Disk Type and Select Existing Zvol dropdown list fields.
Select Disk Type
Displays after selecting Use existing disk image. Select the desired disk type. Options are AHCI or VirtIO. Select AHCI for Windows VMs. VirtIO requires a guest OS that supports VirtIO paravirtualized network drivers.
Select Existing Zvol
(Required) Displays after selecting Use existing disk image. Select an existing zvol from the dropdown list.
Zvol Location
(Required) Displays after selecting Use existing disk image. Select a dataset for the new zvol from the dropdown list of datasets on the system.
Size
(Required) Displays after selecting Use existing disk image. Allocate space for the new zvol. (Examples: 500 KiB, 500M, 2 TB). Units smaller than MiB are not allowed.
Network Interface Screen
The Network Interface settings specify the network adapter type, mac address, and physical network interface card associated with the VM.
Select the adapter type from the dropdown list. Options are:
Intel e82545 (e1000) emulates the same Intel Ethernet card and provides compatibility with most operating systems.
VirtIO provides better performance when the operating system installed in the VM supports VirtIO para-virtualized network drivers.
Mac Address
Enter the desired address into the field to override the randomized MAC address.
Attach NIC
Select the physical interface to associate with the VM from the dropdown list.
Trust Guest Filters
Select to enable and allow the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to yes has security risks because it allows the virtual server to change its MAC address and so receive all frames delivered to this address. Disabled by default.
Installation Media Screen
The Installation Media settings specify the operation system installation media image on a dataset or upload one from the local machine.
Enter the path or browse to the location where you want to install the image file.
Choose File
Click to save the path populated in the ISO save location field.
Upload
Click to upload the file selected in the ISO save location field.
GPU Screen
The GPU settings specify the graphic processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.
Select to enable the VM to hide the GPU from the Microsoft Reserved Partition (MSR).
Ensure Display Device
Select to ensure that the guest always has access to a video device. Required for headless installations like Ubuntu server for the guest to operate properly. Leave the checkbox clear for cases where you want to use a graphic processing unit (GPU) passthrough without adding a display device.
GPUs
Select a physical GPU on your system from the dropdown list to use for the VM.
Confirm Options Screen
The Confirm Options screen displays a summary of settings for the VM. It shows the number of CPUs, cores, threads, memory, name of the VM, and the disk size.
Click Save to add the VM to the Virtual Machines screen. Click Back to return to the previous screens to make changes.
Virtual Machine Details Screen
Expand any VM on the Virtual Machines screen to show the details and options for a VM.
Details include the basic information on the number of virtual CPUs, cores, and threads, the amount of memory, boot load and system clock types, the display port number, and the shutdown timeout in seconds.
Starting the VM shows additional options for the VM.
VM Options
Operation
Icon
Description
Start
Starts a VM. The toggle turns blue when the VM switches to running. Toggles to Stop. Clicking Start shows the Restart,Power Off, Display, and Serial Shell buttons.
Restart
replay
Restarts the VM.
Power Off
power_settings_new
Powers off and halts the VM, similar to turning off a computer power switch.
Stop
stop
Stops a running VM. Because a virtual machine does not always respond well to STOP or the command might time out if the VM does not have an OS. Use Power Off instead.
Edit
mode_edit
Opens the Edit Virtual Machine that displays editable VM settings. You cannot edit a VM while it is running. Stop the VM and then you can edit the properties and settings.
Delete
delete
Deletes a VM. Opens a delete dialog that allows you to remove the VM from your system. You cannot delete a virtual machine that is running. You must first stop the VM and then you can delete it.
Devices
device_hub
Opens the Virtual Machine Devices screen for the selected VM. Shows a list of configured devices for the VM. By default, all VMs show the Disks, NIC, and Display devices.
Clone
Makes an exact copy or clone of the VM. Opens the Clone dialog that allows you to clone the selected VM. Enter a name for the cloned VM. Naming the clone VM is optional. The cloned VM displays on the Virtual Machines list with the extension _clone0. If you clone the same VM again the extension for the second clone is clone1.
Display
settings_ethernet
Opens the SPICE login screen in a browser window and allows you to connect to the remote desktop.
Serial Shell
keyboard_arrow_right
Opens the TrueNAS VM Serial Shell screen.
Download Logs
content_paste
Downloads a .log file to the system.
Delete Virtual Machine Dialog
Delete removes the VM configuration from your system.
Select to remove the data associated with this virtual machine. Deleting a VM results in data loss if the data is not backed up. Leave unselected to keep the VM data intact.
Force Delete
Select to ignore the virtual machine status during the delete operation. Leave unselected to prevent deleting the VM when it is still active or has an undefined state.
Enter vmname below to confirm
Enter the name of the VM to confirm you want to delete the selected VM.
Clone Virtual Machine Window
The Clone dialog allows you to create an exact duplicate of the VM using the name entered.
Naming the clone VM is optional. The cloned VM displays on the Virtual Machines list with the extension _clone0.
If you clone the same VM again the extension for the second clone is clone1.
VM Serial Shell Screen
Click Serial Shell to open the VM Serial Shell screen where you can enter commands for the selected virtual machine.
Click Virtual Machines in the header to return to the Virtual Machine screen.
Edit Virtual Machine Screen
The Edit VM screen settings are a subset of those found on the Create Virtual Machine screens.
It only includes the general settings found on the wizard Operating System screen, CPU and Memory, and GPUs screen settings.
To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.
Edit General Settings
The Edit screen General Settings specify the basic settings for the VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.
Required. Enter an alphanumeric name for the virtual machine.
Description
Enter a description (optional).
System Clock
Select the VM system time from the dropdown list. Options are Local or UTC. The default is Local.
Boot Method
Select the boot method option from the dropdown list. Select UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout
Enter the time in seconds the system waits for the VM to cleanly shut down. During system shutdown, the system initiates power-off for the VM after the shutdown timeout entered expires.
Start on Boot
Select to start this VM when the system boots.
Enable Hyper-V Enlightenments
Shows for VMs set for Windows OS. KVM implements Hyper-V Enlightenments for Windows guests. These features make Windows think they are running on top of a Hyper-V-compatible hypervisor and use Hyper-V-specific features. In some cases enabling these enlightenments might improve the usability and performance on the guest.
To edit display type or bind address after VM creation (click to expand)
Go to Virtualization > Virtual Machines and locate the VM you want to modify.
Click anywhere on the VM entry on the Virtual Machines widget to expand it.
Click device_hubDevices to open the devices screen associated with the VM.
From this screen, click the more_vert icon at the right of the display device and select Edit to open the Edit Display Device screen.
Use the Bind dropdown to select a new IP address.
Edit CPU and Memory Settings
The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.
(Required) Enter the number of virtual CPUs to allocate to the virtual machine. The maximum is 16, or fewer if the host CPU limits the maximum. The VM operating system might impose operational or licensing restrictions on the number of CPUs. Default setting changes with the option selected in Guest OS, for Windows it is 2, for Unix-type it is 1.
Cores
(Required) Enter the number of cores per virtual CPU socket. The product of vCPUs, cores, and threads must not exceed 16.
Threads
(Required) Enter the number of threads per core. A single CPU core can have up to two threads per core. A dual-core could have up to four threads. The product of vCPUs, cores, and threads must not exceed 16.
Optional: CPU Set (Examples: 0-3,8-11)
Specify the logical cores that the VM can use. Better cache locality can be achieved by setting the CPU set based on CPU topology. E.g. to assign cores: 0,1,2,5,9,10,11 you can write: 1-2,5,9-11
Pin vcpus
When the number of vCPUs equals the number of CPUs in CPU Set, vCPUs can be automatically pinned into CPU Set. Pinning is done by mapping each vCPU into a single CPU number following the order in CPU Set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode
Select the CPU mode attribute from the dropdown list to allow your guest VM CPU to be as close to the host CPU as possible. Select Custom to make it so a persistent guest virtual machine sees the same hardware no matter what physical machine the guest VM boots on. It is the default if the CPU mode attribute is not specified. This mode describes the CPU presented to the guest. Select Host Model to use this shortcut to copy the physical host machine CPU definition from the capabilities XML into the domain XML. As the CPU definition copies just before starting a domain, a different physical host machine can use the same XML while still providing the best guest VM CPU each physical host machine supports. Select Host Passthrough when the CPU visible to the guest VM is the same as the physical host machine CPU, including elements that cause errors within libvirt. The downside of this is you cannot reproduce the guest VM environment on different hardware.
CPU Model
Select a CPU model to emulate.
Memory Size
Allocate RAM for the VM. The minimum value is 256 MiB. This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to bytes.
Minimum Memory Size
(Optional) When not specified, the guest system is given a fixed amount of memory specified in Memory Size. When minimum memory is specified, the guest system is given memory within a range between minimum and fixed as needed. Enter a value smaller than the Memory Size to enable a variable RAM amount as needed within a range between this value and the one entered in Memory Size.
Optional: NUMA nodeset (Example: 0-1)
Node set allows setting NUMA nodes for multi NUMA processors when CPU set was defined. To achieve better memory locality, setting nodeset based on assigned cpuset. For example, if CPUs 0,1 belong to NUMA node 0, then setting nodeset to 0 improves memory locality.
Edit GPU Settings
The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.
Select to enable the VM to hide the GPU from the Microsoft Reserved Partition (MSR).
Ensure Display Device
Select to ensure that the guest always has access to a video device. Required for headless installations like Ubuntu server for the guest to operate properly. Leave the checkbox clear for cases where you want to use a graphic processing unit (GPU) passthrough without adding a display device.
GPUs
Select a physical GPU on your system from the dropdown list to use for the VM.
Devices Screens
The Devices screen displays a list of VM devices configured on your system.
By default, every VM displays three devices: Disks, NIC, and Display.
Add opens the Add Device screen. Settings change based on the various device types.
Device Actions
Each device listed on the Devices screen has the same three options, accessed by clicking the more_vert at the right of the device row:
Edit opens the Edit type Device screen where type is the device type selected.
Settings vary based on the type of device selected in Device Type. See Add Device screen.
Device Type only displays on the Add Device screens.
Delete opens a dialog. Delete Device confirms you want to delete the device.
Details opens an information dialog that lists the port, type, bind IP, and other details about the device.
Click Close to close the dialog.
Devices Add Screens
The Add Device screen displays different settings based on the Device Type selected.
Add CD-ROM Device Type Settings
Select CD-ROM in Device Type to see the CD-ROM settings.
Select the device type from the dropdown list. CD-ROM is the default setting.
CD-ROM Path
Use the to the left of /mnt to browse to the location of the CD-ROM file on the system.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add NIC Device Type Settings
Select NIC in Device Type to see the VM network interface card settings.
Required. Select the emulator type from the dropdown list. Emulating an Intel e82545 (e1000) Ethernet card provides compatibility with most operating systems. Change to VirtIO to provide better performance on systems with VirtIO paravirtualized network driver support.
MAC Address
Displays the default auto-generated random MAC address the VM receives. Enter a custom address to override the default.
Generate
Click to add a new randomized address in MAC Address.
NIC To attach
Select a physical interface from the dropdown list to associate with the VM.
Trust Guest Filters
Default setting is not enabled. Set this attribute to allow the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to “yes” has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add Disk Device Type Settings
Select Disk in Device Type in the Add device screen to see the disk settings including disk location, drive type, and disk sector size.
Select the drive type from the dropdown list. Options are AHCI or VirtIO.
Disk sector size
Select the disk sector size from the dropdown list or leave set as Default. Options are Default, 512 or 4096.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add Display Device Type Settings
Remote clients can connect to VM display sessions using a SPICE client, or by installing a 3rd party remote desktop server inside your VM.
SPICE clients are available from the SPICE Protocol site.
Select Display in Device Type in the Add device screen to see the display device settings.
Select the device type from the dropdown list. Display is the default setting.
Port
Enter the port number. You can assign 0, leave it empty for TrueNAS to assign a port when the VM is started, or set it to a fixed preferred port number.
Resolution
Select a screen resolution to use for VM display sessions.
Bind
Select an IP address to use for display sessions or use the default 0.0.0.0.
Password
Enter a password of no more than eight characters in length to automatically pass to the remote display session.
Web Interface
Select to enable connecting to the SPICE web interface.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls. If you want the CD-ROM to be the first device checked assign it a lower number.
Add Raw File Device Type Settings
Select Raw File in Device Type in the Add device screen to see the raw file settings that include location, size of the file, disk sector size, and type.
Enter or use the to the left of /mnt to browse to the location of the file on the system.
Disk sector size
Select the disk sector size from the dropdown list or leave set as Default. Options are Default, 512 or 4096.
Mode
Select the drive type from the dropdown list. Options are AHCI or VirtIO.
Raw filesize
Enter the size of the file in GiB.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add PCI Passthrough Device Type Settings
Select PCI Passthrough Device in Device Type in the Add device screen to see the PCI passthrough device settings.
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 might experience inconsistent or degraded behavior when starting or stopping the VM.
Determine if you want to proceed with this action in such an instance.
Enter or select the device from the dropdown list of options. Enter as (bus#/slot#/fcn#).
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Add USB Passthrough Device Type Settings
Select USB Passthrough Device in Device Type in the Add device screen to see the USB passthrough device settings.
Enter or select the device from the dropdown list of options. If Specify custom is chosen, enter the required Vendor ID and Product ID.
Device Order
Enter the number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.
Apps
The TrueNAS Applications Market is your new resource for the latest details about apps available within TrueNAS.
Discover which apps are widely used or recently added, filter the entire catalog to find the perfect app, and learn specifics that can help you deploy an app.
The website updates daily, so you’ll always have the latest info about TrueNAS applications!
TrueNAS Apps Support Timeline for 24.04 and 24.10
Summary:
Applications added to the TrueNAS Apps catalog before December 24, 2024, require updates to enable host IP port binding.
These updates roll out on June 1, 2025, and require TrueNAS 25.04 (or later).
Due to breaking changes involved in enabling host IP port binding, June 1, 2025 is the deadline for automatic apps migration on upgrade.
Migrate from 24.04 to 24.10 before June 1, 2025, to ensure automatic app migration.
Additionally, existing applications installed on 24.10 do not automatically update after June 1, 2025.
Upgrade to 25.04 before June 1 to continue receiving regular app updates.
Users who do not wish to upgrade to 25.04 before June 1 must manually uninstall and redeploy affected applications after that date to resume app updates.
Timeframe
App Migration 24.04 → 24.10
App Updates in 24.10
App Migration 24.10 → 25.04
App Updates in 25.04
Before June 1, 2025
✅ Supported
✅ Supported
✅ Supported
✅ Supported
After June 1, 2025
❌ Not Supported
⚠️ Action required
✅ Supported
✅ Supported
Read More
Application host IP port binding is being developed for all applications in the TrueNAS Apps catalog, starting with TrueNAS 25.04.
This feature allows per-app selection of any IP address from the available aliases assigned to an interface to bind the WebUI port to.
It includes port bind mode options to publish the port for external access or expose it for inter-container communication.
A small but growing list of applications currently support this functionality in TrueNAS 24.10 or later.
However, applications that were in the TrueNAS Apps catalog before implementation of this feature require OS-level changes to enable support.
Catalog updates to provide host IP port functionality to these applications are scheduled for June 1, 2025.
Applications that currently support host IP port binding
The following applications currently support host IP port binding.
calibre-web
esphome
handbrake-web
homearr
invoiceninja
it-tools
jelu
lyrion-music-server
minecraft-bedrock
romm
satisfactory-server
steam-headless
terreria
tianji
umami
urbackup
zigbee2mqtt
emby
All future applications, as well as those added to the TrueNAS Apps catalog after December 24, 2024, support this feature.
Applications that do not currently support host IP port binding
actual-budget
adguard-home
audiobookshelf
autobrr
bazarr
briefkasten
calibre
castopod
chia
clamav
dashy
ddns-updater
deluge
distribution
dockge
drawio
eclipse-mosquitto
filebrowser
filestash
firefly-iii
flame
flaresolverr
freshrss
frigate
fscrawler
gaseous-server
gitea
grafana
handbrake
homepage
homer
immich
invidious
ipfs
jellyfin
jellyseerr
jenkins
joplin
kapowarr
kavita
komga
lidarr
linkding
listmonk
logseq
mealie
metube
minecraft
mineos
mumble
n8n
navidrome
netbootxyz
nginx-proxy-manager
node-red
odoo
ollama
omada-controller
open-webui
organizr
overseerr
palworld
paperless-ngx
passbolt
penpot
pgadmin
pigallery2
piwigo
planka
portainer
postgres
prowlarr
qbittorrent
radarr
readarr
redis
roundcube
rsyncd
rust-desk
sabnzbd
scrutiny
searxng
sftpgo
sonarr
tautulli
tdarr
terraria
tftpd-hpa
tiny-media-manager
transmission
twofactor-auth
unifi-controller
uptime-kuma
vaultwarden
vikunja
webdav
whoogle
wordpress
asigra-ds-system
syncthing
collabora
diskoverdata
elastic-search
emby
home-assistant
ix-app (Custom App)
minio
netdata
nextcloud
photoprism
pihole
plex
prometheus
storj
wg-easy
App Migration from 24.04 to 24.10
TrueNAS 24.10 introduced a new Docker-based TrueNAS Apps backend and automated migration for Kubernetes-based apps on upgrade.
Due to breaking changes involved in enabling host IP port binding, June 1, 2025 is the deadline for automatic apps migration on upgrade.
Any users still running TrueNAS Apps on 24.04 after June 1 must re-deploy those apps after upgrading to 24.10 or later.
App Updates in 24.10
The cutoff date for simple app updates on TrueNAS 24.10 is June 1, 2025.
Previously installed versions of these apps on TrueNAS 24.10 do not automatically update after this point.
Any users with TrueNAS Apps deployed on 24.10 after June 1 must manually redeploy apps to the new IP port binding version at that time by uninstalling and then reinstalling the application.
Ensure app user data is stored in persistent locations and note configuration settings before uninstalling existing applications to allow for easy redeployment.
No further migration is required.
Normal application update functionality resumes after manual redeployment of these apps.
App Migration from 24.10 to 25.04
Update to TrueNAS 25.04 before June 1, 2025 to continue receiving app updates without interruption, including the new IP port binding functionality.
Users who remain on 24.10 after June 1 can either manually redeploy affected applications in that version or update to 25.04 to resume app updates.
25.04 App Updates
Applications installed on TrueNAS 25.04 before June 1, 2025 automatically update to enable the new functionality.
No manual management is required.
We welcome community contributions to keep this documentation current!
Click Edit Page in the top right corner to propose changes to this article.
See Updating Content for more information.
There are two main application screens, Installed and Discover.
The Installed applications screen shows the status of installed apps, provides access to pod shell and logs screens and a web portal for the app (if available), and the ability to edit deployed app settings.
The Discover screen shows widgets for the installed catalog of apps.
The individual app widgets open app information screens with details about that application, and access to an installation wizard for the app.
It also includes options to install third-party applications in Docker containers that allow users to deploy apps not included in the catalog.
Installed Screen
The first time you go to Apps, the Installed applications screen header shows an Apps Service Not Configured status and dialog opens prompting you to choose the pool for apps to use.
You must choose the pool apps use before you can install applications. See Choose A Pool for Apps for more information.
Settings opens the Settings screen. Use to add or remove other trains to the Stable catalog of applications, adjust address pools, download NVIDIA drivers (with compatible hardware), and control whether to automatically check for docker image updates.
Choose Pool opens the Choose a pool for apps dialog. The Pool dropdown list shows a list of available pools on the system.
Choose sets the selected pool for use by applications.
The first time you open the Installed applications screen a dialog prompts you to choose the pool for apps to use for storage.
Select the pool from the dropdown list, then click Save. This starts the applications service.
If you exit out of this dialog, to set the pool, click Settings > Choose Pool to select a storage pool for apps.
If a pool is not chosen and you attempt to install an application, after clicking Install on an application information screen a dialog window prompts you to select a pool before the installation wizard shows.
Unset Pool
Unset Pool on the Configuration menu opens the Unset Pool dialog.
Click Unset to unset the pool and turn off the application service.
When complete, a Success dialog displays.
Entering characters in the Search field on the screen header filters the images list to only the Image ID or Tags entries matching the entered characters.
Pull Image
Pull Image opens a side panel with options to download specific images to TrueNAS.
Enter the full path and name for the specific image to download. Use the format registry/repository/image.
Image Tag
Enter the specific image tag string to download that specific version of the image. The default latest pulls whichever image version is most recent.
Docker Registry Authentication
Optional. Only needed for private images.
Username
User account name to access a private Docker image.
Password
User account password to access a private Docker image.
Settings
Settings opens the Settings screen showing four application train options: the option to add IP addresses and subnets for the application to use, the option to check for Docker image updates, and if the system is equipped with a GPU, the option to enable TrueNAS to update drivers for that GPU.
Select the checkbox to the left of the train name to add another train to the applications catalog.
Train options:
stable the default train for official apps
enterprise for apps verified and simplified for Enterprise users, the default for enterprise-licensed systems.
community for community-proposed and maintained apps
You must specify at least one train.
The Address Pools shows the current IP address and subnet mask for the network used by applications.
Base shows the default IP address and subnet, and Size shows the network size of each docker network that is cut off from the base subnet.
Select a predefined range from the dropdown list.
This setting replaces the Kubernetes Settings option for Bind Network in 24.04 and earlier.
Use to resolve issues where apps experience issues where TrueNAS device is not reachable from some networks.
Select the network option, or add additional options to resolve the network connection issues.
Install NVIDIA Drivers shows if the system has an NVIDIA GPU installed.
Select to enable TrueNAS to manually install drivers for this device.
When the TrueNAS Debug Kernel is enabled, NVIDIA drivers are disabled.
Systems with non-NVIDIA GPU devices do not show this option, but these GPUs are selectable in the app installation wizards in the Resources Configuration section for the app.
Check for docker image updates sets TrueNAS to check for docker image updates (default setting).
Applications Table
The Applications table on the Installed screen populates a row for each installed app that shows the current state, and the option to stop the app. Stopped apps show the option to start the app.
After installing an application, the Installed screen populates the Applications table.
When returning to the Installed screen, the first application on the list is selected by default.
Each application row shows the name, status, and update information for the application.
A yellow badge shows when an update is available. See Update Apps for more information on updating the application.
Search above the Applications table allows entering the name of an app to locate an installed application.
Selecting the checkbox to the left of Applications selects all installed apps and shows the Bulk Actions dropdown list.
Selecting the checkbox on an app row also shows the Bulk Actions) dropdown list.
Bulk Actions
The Bulk Action dropdown list allows you to apply actions to one or more applications installed and running on your system.
Select the checkbox to the left of Applications to show the Bulk Actions dropdown menu.
Menu options are Start All Selected, Stop All Selected, Upgrade All Selected, and Delete All Selected.
Installed applications have a set of widgets on the Installed screen.
Select an application row to view the information widgets for that application.
Information in the widgets changes based on the app row selected in the Applications table.
Application Info Widget
The Application Info widget shows the name, version number, date last updated, source link for the application, developer, catalog, and train name.
It includes the Edit, Delete, and Web Portal buttons for the application.
If an update is available, it also shows the Update button.
Confirm activates the Continue button. Continue initiates the delete operation.
Update Apps
Update shows on the Application Info widget after clicking Update All on the Installed applications header.
Both only show if TrueNAS SCALE detects an available update for an application.
The application widget on the Discover screen also displays an update badge.
Update opens an upgrade window for the application that includes the Images (to be updated) and Changelog options.
Click on the down arrow to see the options available for each.
Upgrade begins the process and opens a counter dialog that shows the upgrade progress.
When complete, the update badge and buttons disappear.
The Update state on the application row on the Installed screen changes to Up to date.
Workloads Widget
The Workloads widget shows the container information for the selected application.
Information includes the number of pods, used ports, number of deployments, stateful sets, and container information.
It also shows the Shell, Volume Mounts, and View Log icon buttons that provide access to the container pod shell and log screens, and mount point windows.
The option to access the log and the shell remains available for stopped applications for fully deployed application containers and applications in the crashed state.
The ShellShell button opens the Choose Shell Details window.
After selecting the container options, a shell screen for the pod opens.
The Volume Mountsfolder_open button opens the Volume Mounts dialog.
The View LogsLogs button also opens the Pod Logs screen for the app.
Choose Shell Details
The Choose Shell Details dialog lets you enter a shell command to open the Pod Shell screen. You can accept the default value in Command or specify another.
Click Installed on the breadcrumb to return to the Installed applications screen.
Volume Mounts
Volume Mounts opens a dialog showing information on the app volume mounts for current and exited volume mounts for the application container.
The app has Volume Mount options to open windows for both the running mount point and permissions - exited mount point.
Use the logs to help troubleshoot problems with your container pods.
Notes Widget
The Notes widget shows information about the apps, the location where TrueNAS Documentation Hub articles are found, and links to file bug reports and feature requests through Jira or GitHub.
Click View More to show all notes, and Collapse to return the Notes widget to the default view length.
Application Metadata Widget
The Application Metadata widget shows application capabilities unique to the application, and Run As Content shows the user and group IDs, the default user and group name, and a brief description of the application.
View More expands the widget to show more information on application settings.
Collapse hides the extra information.
The Discover screen displays application widgets for the official TrueNAS stable train by default.
Users can add the community and enterprise train applications on the Settings screen.
Custom App opens the Install iX App screen with an install wizard.
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
The Discover screen includes a search field, links to other application management screens, and filters to sort the application widgets displayed.
Show All shows all application widgets in the trains added to the Stable catalog. The links are:
Refresh Charts executes a job to refresh the catalog applications.
Filters shows a list of sort categories that alter which application widgets show. Click on a category to select and filter app widgets.
Filter information includes the Category, App Name, and Updated Date.
Category sorts the app widgets by category or functional area.
For example, Media, Monitoring, Networking, Productivity. etc.
App Name sorts app widgets alphabetically (A to Z).
Updated Date sorts the app widgets by date of update.
Install Custom App Screens
TrueNAS 24.10 or later provides two options for installing a third-party application not included in the official catalogs using a Docker image.
Custom App opens the Install iX App guided installation wizard.
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
Each application widget on the Discover screen opens an information screen with details about that application, a few screenshots of the web UI for the application, and the Install button.
Application information shows the version, the GitHub repository link for the image, and the date the image was last updated.
The application information screen shows two widgets:
Available Resources that shows CPU and memory usage the app requires, the app pool, and available space in gigabits.
Application Info that includes the application version number, link to GitHub repository for the image, and date the image was last application updated.
The screen includes small screenshots of the application website that, when clicked, open larger versions of the image.
Install opens the installation wizard for the application.
The bottom of the screen includes widgets for similar applications found in the catalog.
Application Install or Edit App Wizards
The application Install Application wizard and Edit Application screens show the same settings.
The Edit Application screen opens populated with the current settings for the application.
Settings greyed out cannot be edited.
The install and edit wizard screens include a navigation panel on the right of the screen that lists and links to the setting sections.
A red triangle with an exclamation point marks the sections with the required settings.
An asterisk marks the required fields in a section.
You can enter a new setting in fields that include a preprogrammed default.
The installation wizard configuration sections vary by application, with some including more configuration areas than others.
Click Install to review settings ahead of time to check for required settings.
Click Discover on the breadcrumb at the top of the installation wizard to exiting the screen without saving and until you are ready return and configure the app settings.
All applications include these basic setting sections:
Application Name shows the default name for the application.
If deploying more than one instance of the application, you must change the default name. Also includes the version number for the application.
Do not change the version number for official apps or those included in a SCALE catalog.
When a new version becomes available, the Installed application screen banner and application row displays an update alert, and the Application Info widget displays an update button> Updating the app changes the version shown on the edit wizard for the application.
Application Configuration shows settings that app requires to deploy.
This section can be named anything. For example, the MinIO app uses MinIO Configuration.
Typical settings include user credentials, environment variables, additional argument settings, name of the node, or even sizing parameters.
If not using the default user and group provided, add the new user (and group) to manage the application before using the installation wizard.
Network Configuration shows network settings the app needs to communicate with SCALE and the Internet.
Settings include the default port assignment, host name, IP addresses, and other network settings.
If changing the port number to something other than the default setting, refer to Default Ports for a list of used and available port numbers.
Some network configuration settings include the option to add a certificate. Create the certificate authority and certificate before using the installation wizard if using a certificate is required for the application.
Storage Configuration shows options to configure storage for the application.
Storage options include using the default ixVolume setting that adds a storage volume under the ix-applications dataset, host path where you select existing dataset(s) to use, or in some cases the SMB share option where you configure a share for the application to use.
The Add button allows you to configure additional storage volumes for the application to use in addition to the main storage volume (dataset).
If the application requires specific datasets, configure these before using the installation wizard.
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.
Resources Configuration shows CPU and memory settings for the container pod.
This section can also be named Resource Limits. In most cases, you can accept the default settings, or you can change these settings to limit the system resources available to the application.
After installing an app, you can modify most settings by selecting the app on the Installed applications screen and then clicking the Edit button on the Application Info widget for that app.
Contents
Custom App Screens: Provides information on the Install Custom App screen and configuration settings.
Custom App Screens
The TrueNAS Applications Market is your new resource for the latest details about apps available within TrueNAS.
Discover which apps are widely used or recently added, filter the entire catalog to find the perfect app, and learn specifics that can help you deploy an app.
The website updates daily, so you’ll always have the latest info about TrueNAS applications!
more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
Install iX App Screen
The Install iX App screen allows you to configure third-party applications using Docker settings.
Use the wizard to configure applications not included in the official catalog.
The panel on the right of the screen links to each setting area.
Click on a heading or setting to jump to that area of the screen.
Click in the Search Input Fields to see a list of setting links.
Enter a name for the application. The name must have lowercase alphanumeric characters, begin with an alphabet character, and can end with an alphanumeric character. The name can contain a hyphen (-) but not as the first or last character in the name. For example, use chia-1 but not -chia1 or 1chia- as a valid name.
Version
Displays the current version of iX-App. Accept the default number.
Image Configuration Settings
Image Configuration settings specify the container image details.
They define the image, tag, and when TrueNAS pulls the image from the remote repository.
(Required) Enter the Docker image repository name. For example, plexinc/pms-docker for Plex.
Tag
Enter the tag to use for the specified image. For example, public for Plex. Or accept the default latest.
Pull Policy
Select the Docker image pull policy from the dropdown list. Options are Only pull image if not present on host (default option), Always pull image even if present on host, and Never pull image even if it’s not present on host.
Container Configuration Settings
Container Configuration settings specify the entrypoint, commands, timezone, environment variables, and restart policy to use for the image.
These can override any existing variables stored in the image.
Check the documentation for the application you want to install for required entrypoints, commands, or variables.
Click Add to display a new field. Each field is an item in the ENTRYPOINT list in exec format. For example, to enter ENTRYPOINT ["top", "-b"], enter top in the first Entrypoint field. Click Add again. Enter -b in the second field.
Command
Click Add to display a new field. Each field is an item in the CMD list in exec format. For example, to enter CMD ["echo", "hello world"], enter echo in the first Command field. Click Add again. Enter hello world in the second field.
Timezone
Use the dropdown to select a timezone setting for the container or begin typing the timezone to see a narrowed list of options to select from.
Environment Variables
Click Add to display a block of environment variables. Click Add again to enter another set of environment variables.
Name
Enter the environment variable name or key. For example, enter MY_NAME.
Value
Enter the value for the variable specified in Environment Variable Name. For example, enter John Doe, John\ Doe, or John.
Restart Policy
Use the dropdown to select a restart policy to use for the container. Options are No - Does not restart the container under any circumstances., Unless Stopped - Restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed., On Failure - Restarts the container if the exit code indicates an error., and Always - Restarts the container until its removal..
Disable Builtin Healthcheck
Select to disable the built-in HEALTHCHECK defined in the image, for example to address performance or compatibility requirements.
TTY
Select to enable a pseudo-TTY (or pseudo-terminal) for the container.
Stdin
Select to keep the standard input (stdin) stream for the container open, for example for an interactive application that needs to remain ready to accept input.
Security Context Configuration Settings
Security Context Configuration settings allow you to run the container in privileged mode, grant the container Linux kernel capabilities, or define a user to run the container.
Select to run the container in privileged mode. By default, a container cannot access any devices on the host. With Privileged enabled, the container has access to all devices on the host, which allows the container nearly all the same access as processes running on the host. Be cautious if enabling privileged mode. A more secure solution is to use Capabilities to grant limited access to system processes as needed.
Capabilities
Click Add to display a container capability field. Enter a Linux capability to enable, for example, enter CHOWN. Click Add again to enter another capability.
Custom User
Select to display the User ID and Group ID fields.
User ID
Displays when Custom User is selected. Enter the numeric UID of the user that runs the container. Defaults to 568 (apps).
Group ID
Displays when Custom User is selected. Enter the numeric GID of the group that runs the container. Defaults to 568 (apps).
Network Configuration Settings
Network Configuration settings specify network, ports, and DNS servers if the container needs a custom networking configuration.
Use port forwarding to reroute container ports that default to the same port number used by another system service or container.
See Default Ports for a list of assigned ports in TrueNAS.
See the Docker Container Discovery documentation for more on overlaying ports.
By default, containers use the DNS settings from the host system.
You can change the DNS policy and define separate nameservers and search domains.
See the Docker DNS services documentation for more details.
Select to bind the container to the TrueNAS host network. When bound to the host network, the container does not have a unique IP-address, so port-mapping is disabled.
Ports
Click Add to display a block of port configuration fields to specify the port values and transfer protocol. Click again to add additional port mappings.
Container Port
Enter a port number in the container. Refer to the application documentation for default port values.
Host Port
Enter an open port number on the TrueNAS host.
Protocol
Select the protocol from the dropdown list. Options are TCP or UDP.
Nameservers
Use to add one or more IP addresses to use as DNS servers for the container. Click Add to the right of Nameservers to display a Nameserver entry field. Click again to add another name server.
Nameserver
Enter the IP address of the name server.
Search Domains
Use to add one or more DNS domains to search non-fully qualified host names. Click Add to display a Search Domain field to enter the domain you want to configure. Click again to add another search domain. See the Linux search documentation for more information.
Search Domain
Enter the search domain you want to configure. For example, mydomain.com.
DNS Options
Use to add one or more key-value pairs to control various aspects of query behavior and DNS resolution. Click Add to display an Option field. Click again to add another option. See the Linux options documentation for more information.
Option
Enter a key-value pair representing a DNS option and its value. For example, ndots:2.
Portal Configuration Settings
The Portal Configuration settings configure the web UI portal for the container.
Click Add to display the web portal configuration settings.
Enter a UI portal name to use and display in the UI. For example, MyAppPortal.
Protocol
Select the web protocol to use for the portal from the dropdown list. Options are HTTP or HTTPS.
Use Node IP
Select to use the TrueNAS node, or host, IP address to access the portal. Selected by default.
Host
Displays when Use Node IP is not selected. Enter a host name or an internal IP within your local network, for example my-app-service.local or an internal IP address.
Port
Enter the port number to use for portal access. The port number the app uses should be in the documentation provided by the application provider/developer. Check the port number against the list of Default Ports to make sure TrueNAS is not using it for some other purpose.
Path
Enter the path for portal access, for example /admin. Defaults to /. The path is appended to the host IP and port, as in truenas.local:15000/admin.
Storage Configuration Settings
The Storage Configuration settings specify persistent storage paths and share data claims separate from the lifecycle of the container.
For more details, see the Docker storage documentation.
You can mount TrueNAS storage locations inside the container with host path volumes.
Create the storage volumes in TrueNAS and set the host path volume to a dataset and directory path.
Define the path to the system storage and the container internal path for the system storage location to appear.
Alternatively, select ixVolume to allow TrueNAS to create a dataset on the apps storage pool.
Both Host Path and ixVolume attach container storage as a bind mount.
See Docker Bind Mount documentation for more information.
Users can create additional SMB share volume claims within the container to access an SMB share.
Share volumes consume space from the pool chosen for application management.
Finally, Tmpfs allows the container to utilize a temporary directory on the RAM.
See the Docker tmpfs documentation for more information.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the host path mounts inside the container.
Enable ACL
Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Host Path
(Required) Enter a path or click arrow_right to the left of /mnt to browse to the location of the dataset to populate the Host Path. Click on the dataset to select and display it in the Host Path field.
ACL Entries
Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type
Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID
Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access
Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.
Force Flag
Displays when Enable ACL is selected. Select to apply the configured ACL settings to a directory containing existing data.
ixVolume (Dataset created automatically by the system)
Use to configure a storage mount for a system created dataset on the applications pool.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the ixVolume mounts inside the container.
Enable ACL
Select to enable custom Access Control List (ACL) entries for the container mount and display ACL settings fields.
Dataset Name
Enter a name for the dataset that is created and used for storage.
ACL Entries
Displays when Enable ACL is selected. Click Add to display a block of ACL entry settings.
ID Type
Displays when Enable ACL is selected and Add is clicked. Select Entry is for a USER or Entry is for a GROUP.
ID
Displays when Enable ACL is selected and Add is clicked. Enter the numeric UID or GID, matching the selected ID Type.
Access
Displays when Enable ACL is selected and Add is clicked. Select the level of access privileges to assign to the user or group matching the ID. Options are Read Access, Modify Access, or FULL_CONTROL Access.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data.
Mount Path
(Required) Enter the path/to/directory where the share volume mounts inside the container.
Server
(Required) Enter the IP address for the SMB server, for example 192.168.1.100. This can be the TrueNAS host.
Path
(Required) Enter the name of the SMB share, for example my-share.
Username
(Required) Enter the username of an account with permission to access the SMB share.
Password
(Required) Enter the password for the account in Username.
Domain
Enter the directory services domain. Only required if the domain is something other than the TrueNAS default WORKGROUP, for example on systems with Active Directory configured.
Tmpfs (Temporary directory created on the RAM)
Use to configure a memory-backed temporary directory.
See the Docker tmpfs documentation for more information.
Select to make the mount path inside the container read-only and prevent the app from using the path to store data. Not recommended for memory-backed storage.
Mount Path
(Required) Enter the path where the memory-backed directory mounts inside the container.
Tmpfs Size Limit (in Mi)
(Required) Enter the maximum size of the temporary directory in mebibytes. Defaults to 500.
Resources Configuration Settings
Resources Configuration settings configure resources for the container.
Resource limits specify the CPU and memory limits to place on the container.
GPU Configuration settings configure GPU device allocation for application processes.
Settings only display if the system detects available GPU device(s).
See Allocating GPU for more information.
Select to enable resource limits and display the CPUs and Memory (in MB) settings.
CPUs
Enter the maximum number of CPU cores the container can access. For example, 2.
Memory (in MB)
Enter the number of megabytes you want to limit memory to. For example, 4096.
Passthrough available (non-NVIDIA) GPUs
Select to allow the passthrough of non-NVIDIA GPU devices to the container.
Select NVIDIA GPU(s)
Displays if compatible NVIDIA GPU device(s) are installed and detected.
Use this GPU
Select to allow passthrough of the specified NVIDIA device to the container.
Add Custom App Screen
The Add Custom App screen allows you to configure third-party applications using Docker Compose YAML syntax.
Use the YAML editor to configure applications not included in the official catalog.
See the Docker Compose overview from Docker for more information.
Enter a name for the application to be used in the TrueNAS UI. The name must use lowercase alphanumeric characters, start with an alphabetic character, and can end with alphanumeric character. A hyphen (-) is allowed but not as the first or last character, for example abc123, abc, abcd-1232, but not -abcd.
Custom Config
Enter a Docker Compose YAML file for the application.
Click Save to initiate app deployment.
Reporting
The Reporting screen displays graphs of system information for CPU, disk, memory, network, system functions, UPS, and ZFS.
Use the dropdown in the upper right corner to select between reporting graph display options.
The CPU report displays by default.
What does TrueNAS SCALE use for reporting?
TrueNAS SCALE uses Netdata to gather metrics, create visualizations, and provide reporting statistics.
Click Netdata from the Reporting screen to see the built-in Netdata UI.
This UI bases metrics on your local system and browser time, which might differ from the default TrueNAS system time.
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 after updating to 25.05 can install the Netdata application.
To configure a third-party reporting integration, such as Graphite, click Exporters to open the Reporting Exporters screen.
Report Graphs
The following sections provide examples of each report graph.
There are a few controls to change the default graph view:
The Auto Refresh toggle updates the graphs with the latest reporting data every few seconds.
When active, the graph resets to the chosen Reset Zoom view every time the reporting data updates.
Disable Auto Refresh before manually zooming in on any section of the graph.
Step Back () moves the graph backward in time by whatever time increment is currently active in Reset Zoom.
Step Forward () moves the graph forward in time by whatever time increment is currently active in Reset Zoom.
The default graph view is to show the latest data, which disables this button.
Zoom Out () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views.
The Reset Zoom indicator shows which time value is active for the graph.
The default 1 Hour is the default (and minimum) time period that can be active.
When Zoom Out is active, click Reset Zoom to reset the graph view to 1 Hour.
Zoom In () adjusts the time period shown in the graph between 1 Hour, 1 Day, 1 Week, 1 Month, and 6 Month views.
This is active when the graph changes from the default 1 Hour view.
To manually adjust the vertical or horizontal precision of the graph, disable Auto Refresh, then click and drag within the graph view.
A left-to-right (or vice-versa) motion increases the horizontal view precision, while an up-to-down (or vice-versa) motion increases the vertical precision.
CPU Graphs
Shows the CPU temperature, CPU usage, and system load graphs.
CPU graphs show the amount of time the CPU spends in various states such as executing user code, executing system code, and idle time.
Graphs show short-, mid-, and long-term loads, along with CPU temperature graphs.
Shows graphs for each selected system disk, and by report type.
Disk graphs show read and write statistics on I/O, percent busy, latency, operations per second, pending I/O requests, and disk temperature.
Use the Select Disks dropdown to select the disks.
Use the Select Reports dropdown to select the report types to display.
Displays all available graphs for any or all disks selected on the Disks dropdown list.
Disk Temperature
Displays the minimum, maximum, and mean temperature readings for the disk selected.
Disk I/O
Displays the disk read and write I/O stats in bytes/s.
Temperature monitoring for the disk is disabled if HDD Standby is enabled.
Check the Storage > DisksEdit Disk* configuration form for any or all disks in the system if you do not see the temperature monitoring graph.
Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits.
For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Memory Graphs
Shows both the Physical memory utilization and Swap utilization graphs.
Memory graphs show memory usage and swap graphs show the amount of free and used swap space.
Shows an Interface Traffic graph for each interface in the system.
Network graphs report received and transmitted traffic in megabytes per second for each configured interface.
Shows both the Processes and Uptime graphs.
System graphs show the number of processes grouped by state, sleeping, running, stopped, zombies and blocked, and system uptime.
Shows the UPS charging percentage, UPS runtime, UPS voltage for battery, input, and output, UPS input current, frequency, and input load, and UPS temperature.
The UPS service must be configured with a compatible Uninterruptible Power Supply (UPS) device.
Shows graphs of the ARC size, hit ratio, ARC requests demand_data, demand_metadata, prefetch_data, and prefetch_metadata with the Arc and L2 gigabytes and hits (%), and the hits, misses, and total number of requests.
ZFS graphs show compressed physical ARC size, hit ratio, demand data, demand metadata, and prefetch data and metadata.
Exporter on the Reporting screen opens the Reporting Exporter screen.
The Reporting Exporters screen displays reporting exporters configured on the system.
Exporting enables TrueNAS SCALE to send Netdata reporting metrics to another time-series database.
Exporters send Netdata reporting records as JSON objects to third-party reporting collection cloud services or applications installed on servers.
For more information, see the Netdata exporting reference guide.
Enter a unique name for the exporter configuration. If configuring multiple instances, give each a distinct name.
Type
Select the report object format. At present, GRAPHITE is the only current supported option. Selecting GRAPHITE displays the exporter configuration settings
Enable
Select to enable sending reporting data to the configured exporter. Leave the checkbox clear to disable the explorer without removing the configuration.
Additional settings populate based on the selected Type option.
(Required) Enter the IP address of the Graphite server.
Destination Port
(Required) Enter the port the Graphite server monitors.
Prefix
Enter the top level of the file hierarchy for the path to use to store exported records. For example, enter the top-level folder name for the path, and use Namespace to enter the folder for the data records. For example, enter dragonfish.
namespace
Enter the name of the folder where you store data records. Use the Prefix to define the full path. You can also enter the host name to add to all data records sent to the Graphite server. Defaults to truenas.
Update Every
(Optional) Enter the number of seconds for the interval to send data to the Graphite database. Defaults to 1.
Buffer On Failures
(Optional) Enter the number of iterations (Update Every seconds) to buffer data when the Graphite server is not available. Defaults to 10.
Send Names Instead Of Ids
(Optional) Enter true to send Netdata chart and dimension names to Graphite or false to send IDs. Defaults to true.
Matching Charts
(Optional) Enter one or more space-separated patterns in regular expression. Use the asterisk () as a wildcard to send all charts or the exclamation mark (!) to define a negative match to specify the charts to send to Graphite. Defaults to ().
Update Screens: Provides information on functions and fields on the TrueNAS SCALE Update screens.
General Settings Screen: Provides information on General system setting screen, widgets, and settings for getting support, changing console or the GUI, localization and keyboard setups, and adding NTP servers.
Advanced Settings Screen: Provides information on the System Settings > Advanced screen, widgets, and configuration screen settings.
Boot: Provides reference descriptions of the boot environment screens and settings.
Failover Screen: Provides information on the Failover screen settings and functions.
Services: Information on the Services screen and individual service articles in the Services area.
FTP Service Screen: Provides information on the FTP services screens and settings.
The TrueNAS Update screen provides users with different methods to update the system automatically or manually.
The screen can show up to four information areas:
Current train
Upgrade operation and version (only when an update is detected)
Production/non-production release information (only when an update is detected)
Update options
The screen shows the Current Train and a link to more information on the current train.
Check for Updates Daily and Download if Available sets TrueNAS to check the update server daily for updates on the specified train.
When selected, the system automatically downloads an update if one is available.
The refresh refresh button refreshes the information displayed on the screen.
The upgrade operation only displays when the system detects an update.
It includes the upgrade operation information with the current release and available update release versions.
If the current train is not a production release, the screen includes a notification.
After detecting an update, the screen shows three buttons: Download Updates, Apply Pending Updates, and Install Manual Update File.
If not detected, only the manual update option shows.
Export Password Secret Seed stores hashes of the passwords sufficient for authentication in the system. It does not store user passwords.
The secret seed is used to decrypt encrypted fields in the TrueNAS configuration database.
Various fields are encrypted because they might contain sensitive information such as cryptographic certificates, passwords (not user login passwords), or weak hashing algorithms (for example, NT hashes of SMB users). When a config file is restored without the secret seed, encrypted fields are set to empty values. This means various services can be broken due to the missing information. Examples are SMB via local accounts and apps.
Save Configuration downloads the system configuration file to your system. Keep the configuration file in a safe place that is regularly backed up.
Manual Update Screen
The Manual Update screen shows after clicking Save Configuration or Do Not Save on the save configuration settings window.
Current Version displays the SCALE release version running on your system.
Choose File opens a browse window where you can locate the downloaded update configuration file.
The Update File Temporary Storage Location dropdown list includes two options:
Memory Device that sets the mount location to one you select on the dropdown list.
A mount location on the system designating where on the system to store the upgrade file. For example, a pool or dataset path on your system.
Apply Update to start the installation.
General Settings Screen
The General Settings screen includes widgets for Support, GUI, Localization, NTP, and system Email functions. Each widget displays information about current settings and includes one or more buttons for related actions and configuration options.
The Manage Configuration dropdown provides three options to backup, restore, or reset system configuration settings.
Manage Configuration
TrueNAS SCALE allows users to manage the system configuration via uploading/downloading configurations, or resetting the system to the default configuration.
Download File
The Download File option opens the Save Configuration dialog, which allows users to download the current system configuration to the local machine.
The Export Password Secret Seed option includes encrypted passwords in the downloaded configuration file.
This option allows you to restore the configuration file to a different operating system device where the decryption seed is not already present.
Users must physically secure configuration file backups containing the seed to prevent unauthorized access or password decryption.
Upload File
The Upload File option opens the Upload Config dialog, which allows users to choose a previously saved TrueNAS SCALE configuration to replace the current system configuration.
Choose File opens a file browser window where you can locate the downloaded and saved configuration. After selecting the file, it displays in the Upload Config window.
Upload uploads the selected configuration file.
All passwords reset if the uploaded configuration file saved without Export Password Secret Seed enabled.
Reset to Defaults
The Reset to Defaults option opens the Reset Configuration dialog, which resets the system configuration to factory settings and restarts the system. Users must set a new login password.
Save the system current 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 may lose data that you did not back up, and you will not be able to revert to the previous configuration.
When prompted to reload the page, click Reload Now.
When the End User License Agreement (EULA) opens, read it thoroughly and completely, then click I AGREE.
The Support widget updates to display license and hardware information.
Select This is a production system and click Proceed to send iXsystems email notification that the system is in production.
Proactive Support Screen
Silver/Gold Coverage Customers can enable iXsystems Proactive Support. This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
Click Here for More Information
To configure Proactive Support, click Proactive Support in the Support widget.
Select a preferred color theme from the dropdown list of eight options.
GUI SSL Certificate
Select a self-signed certificate from the dropdown list. The system uses a self-signed certificate to enable encrypted web interface connections. Manage Certificates opens the Certificates screen.
Web Interface IPv4 Address
Select a recent IP address from the dropdown list to limit usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface IPv6 Address
Select a recent IPv6 address from the dropdown list to limit the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable.
Web Interface HTTP Port
Enter a port number for an HTTP connection to the web interface. Allow configuring a non-standard port to access the GUI over HTTP. Changing this setting might require changing a Firefox configuration setting.
Web Interface HTTPS Port
Enter a port number for an HTTPS connection to the web interface. This field allows configuring a non-standard port to access the GUI over HTTPS.
HTTPS Protocols
Select the Transport Layer Security (TLS) versions TrueNAS SCALE can use for connection security from the dropdown list. Cryptographic protocol for securing client/server connections.
Web Interface HTTP -> HTTPS Redirect
Select to redirect HTTP connections to HTTPS. 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.
Usage Collection
Select to enable sending anonymous usage statistics to iXsystems. For more information about what usage data is collected, see the TrueNAS Data Collection Statement.
Show Console Messages
Select to display console messages in real-time at the bottom of the browser.
Localization Settings Screen
Click Settings on the Localization widget to open the Localization Settings screen that lets users localize their system to a specific region.
Click Here for More Information
Click Settings to open the Localization Settings screen.
Select a language keyboard layout from the dropdown list.
Timezone
Select a time zone from the dropdown list.
Date Format
Select a date format from the dropdown list.
Time Format
Select a time format from the dropdown list.
Add NTP Server Screen
Click Add on the NTP Servers widget to open the Add NTP Server screen that allows users to configure Network Time Protocol (NTP) servers, which sync the local system time with an accurate external reference.
Click Here for More Information
By default, new installations use several existing NTP servers. TrueNAS SCALE supports adding custom NTP servers. Click Add to open the Add NTP Server screen.
Enter the hostname or IP address of the NTP server.
Burst
Select to use a non-public NTP server. Recommended when Max Poll is greater than 10. Only use on personal NTP servers or those under direct control. Do not enable it when using public NTP servers.
IBurst
Select to speed up the initial synchronization (seconds instead of minutes).
Prefer
Select when using highly accurate NTP servers such as those with time monitoring hardware. Only use for these highly accurate NTP servers.
Min Poll
Enter the minimum polling interval, in seconds, as a power of 2. For example, 6 means 2^6, or 64 seconds. The default is 6, and the minimum value is 4.
Max Poll
Enter the maximum polling interval, in seconds, as a power of 2. For example, 10 means 2^10, or 1,024 seconds. The default is 10, and the maximum value is 17.
Force
Select to force the addition of the NTP server, even if it is currently unreachable.
Email Options Screen
Click Settings on the Email widget to open the Email Options screen that allows users to configure the system email send method.
Click Here for More Information
An automatic script sends a nightly email to the administrator account containing important information such as the health of the disks.
Users must first configure an email address for the admin account or another administrative user in Credentials > Users.
The Email Options screen offers two options to set up email.
Select either SMTP or GMail OAuth.
The configuration settings change based on the selected radio button.
SMTP
If SMTP is selected, the screen displays the SMTP configuration fields.
The name to show in front of the sending email address, for example: TrueNAS.
Outgoing Mail Server
Host name or IP address of SMTP server to use for sending emails.
Mail Server Port
SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).
Security
Select the security option from the dropdown list. Options are Plain (No Encryption), SSL (Implicit TLS), or TLS (STARTTLS). See email encryption for more information on types.
SMTP Authentication
Select to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password.
Username
Displays after selecting SMTP Authentication. The user name for the sending email account, typically the full email address.
Password
Displays after selecting SMTP Authentication. The password for the sending email account.
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
Gmail OAuth
If GMail OAuth is selected, the screen displays Log in to Gmail to set up Oauth Credentials and the Log In To Gmail button.
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
Advanced Settings Screen
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes.
Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Console settings configure how the Console Setup menu displays, the serial port it uses and the port speed, and the banner users see when accessing it.
Select to display the console without being prompted to enter a password. Leave cleared to add a login prompt to the system before showing the console menu. Selected by default.
Enable Serial Console
Select to enable the serial console. Selected by default. Clear this if the serial port is disabled.
Serial Port
Shows the default serial port. If using a port other than the default, enter the serial console port address.
Serial Speed
Shows the default serial port speed. If not using the default speed, select the speed (in bits per second) the serial port uses from the dropdown list. Options are 9600, 19200, 38400, 57600, or 115200.
MOTD Banner
Enter the message you want to display when a user logs in with SSH. The default banner message is Welcome to TrueNAS.
Syslog Widget
The Syslog widget displays the existing system logging settings that specify how and when the system sends log messages to the syslog server.
The Syslog settings specify the logging level the system uses to record system events to the boot device.
There are also options to configure a remote syslog server for recording system events.
Select to include the fully qualified domain name (FQDN) in logs to identify systems with similar host names.
Syslog Level
Select the minimum log priority level to send to the remote syslog server. The system only sends logs at or above this level.
Syslog Server
Enter the remote syslog server DNS hostname or IP address. Add a colon and the port number to the hostname to use non-standard port numbers, like mysyslogserver:1928. Log entries are written to local logs and sent to the remote syslog server.
Syslog Transport
Enter the transport protocol for the remote system log server connection. Selecting Transport Layer Security (TLS) displays the Syslog TLS Certificate and Syslog TSL Certificate Authority fields. This setting requires preconfiguring both the server system certificate and the certificate authority (CA).
Syslog TLS Certificate
Displays after selecting TLS in Syslog Transport. Select the transport protocol for the remote system log server TLS certificate from the dropdown list. Select the default or add the certificate and CA for the server using the Credentials > Certificates screen Certificates widget.
Syslog TLS Certificate Authority
Displays after selecting TLS in Syslog Transport. Select the TLS CA for the TLS server from the dropdown list. If not using the default, create the CA for the syslog server TLS certificate on the Credentials > Certificates > Certificate Authorities screen.
Include Audit Logs
Select to enable audit logging.
Audit Widget
The Audit widget displays the current audit storage and retention policy settings. The public-facing API allows querying
audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
Enter the number of days to retain local audit messages.
Reservation (in GiB)
Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)
Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)
Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range:5 - 80.
Quota Fill Critical (in %)
Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range:50 - 95.
Set to boot a debug kernel after the next system reboot. This is intended for troubleshooting scenarios only and should typically remain disabled. Enabling this option disables any Nvidia drivers present on the system.
Cron Jobs Widget
The Cron Jobs widget displays No Cron Jobs configured until you add a cron job, and then it shows the information on cron job(s) configured on the system.
Click on any job listed in the widget to open the Edit Cron Jobs configuration screen populated with the settings for that cron job.
Add or Edit Cron Job Configuration Screen
The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Cron Jobs lets users configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Enter the full path to the command or script to run. For example, to create a command string that generates a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt
Run As User
Select a user account to run the command. The user must have permissions allowing them to run the command or script.
Schedule
Select a schedule preset or choose Custom to open the advanced scheduler. Note that an in-progress cron task postpones any later scheduled instance of the same task until the running task is complete.
Hide Standard Output
Select to hide standard output (stdout) from the command. If left cleared, TrueNAS mails any standard output to the user account cron that ran the command.
Hide Standard Error
Select to hide error output (stderr) from the command. If left cleared, TrueNAS mails any error output to the user account cron that ran the command.
Enabled
Select to enable this cron job. Leave cleared to disable the cron job without deleting it.
Init/Shutdown Scripts Widget
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, then the widget lists the scrips configured on the system.
Select when the command or script runs from the dropdown list. Options are Pre Init for early in the boot process, after mounting file systems and starting networking. Post Init runs at the end of the boot process before Linux services start. Shutdown runs during the system power-off process.
Enabled
Select to enable this script. When left cleared, it disables the script without deleting it.
Timeout
Automatically stop the script or command after the specified number of seconds.
Sysctl Widget
The Sysctl widget displays either No Sysctl configured or the existing sysctl settings on the system.
Enter the name of the sysctl variable to configure. Sysctl tunables configure kernel parameters while the system runs and generally take effect immediately.
Value
Enter a sysctl value to use for the loader, sysctl variable.
Description
Enter a description for the tunable.
Enabled
Select to enable this tunable. Leave clear to disable this tunable without deleting it.
Storage Widget
Storage widget displays the pool configured as the system dataset pool and allows users to select the storage pool they want to hold the system dataset.
The system dataset stores core files for debugging and keys for encrypted pools. It also stores Samba4 metadata, such as the user and group cache and share-level permissions.
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 pool, or an encrypted pool without passphrases.
Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward.
If the encrypted pool already has a passphrase set, you cannot move the system dataset to that pool.
Replication Widget
The Replication widget displays the number of replication tasks that can execute simultaneously on the system. It allows users to adjust the maximum number of replication tasks the system can perform simultaneously.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
Access Widget
The Access widget shows a list of all active sessions including the current logged-in user and the time it started.
The Session Timeout setting shows the number of minutes for the current session.
The Login Banner shows the custom text entered on the Access Settings screen. This text shows before the login screen.
When configured, users see the login banner and must click Continue to show the TrueNAS login splash screen.
Administrators can manage other active sessions and configure the session timeout for their accounts.
Terminate Other Sessions ends all sessions except the current session.
To end individual sessions, click the logout button next to that session.
You must check a confirmation box before the system allows you to end sessions.
The logout icon is inactive for the currently logged-in administrator session and active for any other current sessions.
It cannot be used to terminate the currently logged-in active administrator session.
Session Timeout shows the configured token duration for the current session (default is five minutes).
TrueNAS logs out user sessions that are inactive for longer than the configured token setting for the user.
New activity resets the token counter.
When the configured session timeout is exceeded, TrueNAS displays a Logout dialog with the exceeded ticket lifetime value and the time the session is scheduled to terminate.
If the configured session timeout is exceeded, TrueNAS SCALE displays a Logout dialog with the exceeded ticket lifetime value and the time that the session is scheduled to terminate.
Extend Session resets the token counter.
If the button is not clicked, the TrueNAS SCALE terminates the session automatically and returns to the login screen.
Configure opens the Access Settings screen.
Token Settings Screen
The Token Settings screen allows users to configure the Session Timeout for the current account.
Select a value that fits your needs and security requirements.
Enter the value in seconds.
The default lifetime setting is 300 seconds or five minutes.
The maximum is 2147482 seconds or 24 days, 20 hours, 31 minutes, and 22 seconds.
The Login Banner field allows specifying a text message the system shows before the TrueNAS login splash screen displays.
Continue on the banner screen closes the screen, then shows the login splash screen.
The maximum length of the banner text is 4096 characters including spaces. Long text wraps and banner text can use carriage returns to break up long messages to improve readability.
Leave Login Banner empty to show just the login screen without interruption by a banner screen.
TrueNAS Enterprise
Enterprise-licensed systems include the Allow Directory Service users to access WebUI option on the Access Settings screen.
After enabling this option TrueNAS automatically creates a new entry, named as the domain admin group, in the Privileges screen table. For example, if the domain is ad03.mydomain.net, then you should see a group of that name listed as well as any the groups AD creates on the system.
Allowed IP Addresses Widget
The Allowed IP Addresses widget displays IP addresses and networks added to the system that are allowed to use the API and UI. If this list is empty, then all IP addresses are allowed to use API and UI.
Configure opens the Allowed IP Addresses configuration screen.
Entering an IP address to the allowed IP address list denies access to the UI or API for all other IP addresses not listed.
Only use when limiting system access to a single or limited number of IP addresses. Leave the list blank to allow all IP addresses.
Click Add next to Allowed IP Addresses to add an entry to the allowed IP Addresses list.
Ensure the first address and/or subnet includes your current client system.
You can enter a specific IP address, for example, 192.168.1.1, for individual access, or use an IP address with a subnet mask, like 192.168.1.0/24, to define a range of addresses.
You can add as many addresses as needed.
Click Save.
A Restart Web Service dialog opens.
Select Confirm and then Continue to restart the web UI and apply changes.
Self-Encrypting Drive Widget
The Self-Encrypting Drive (SED) widget displays the system ATA security user and password.
Configure opens the Isolated GPU PCI Ids screen, which allows users to isolate additional GPU devices.
Isolated GPU PCI IDs Configuration Screen
The Isolate GPU PCI IDs configuration screen allows you to isolate GPU devices for a virtual machine (VM).
To isolate a GPU, you must have at least two in your system; one allocated to the host system for system functions and/or applications, and the other available to isolate for use by a VM.
Select the GPU device ID from the dropdown list and click Save.
Isolated GPU devices are reserved for use by configured applications or a VM.
To allocate an isolated GPU device, select it while creating or editing the VM configuration.
When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM, and it becomes unavailable for any other allocations.
Global Two-Factor Authentication Widget
The Global Two Factor Authentication widget allows you to set up two-factor authentication (2FA) for your system.
Enter the number of valid passwords. Extends password validity beyond the current to the previous password(s) based on the number entered. For example, setting this to 1 means the current and previous passwords are valid. If the previous password is a and the current password is b, then both passwords are valid. If set to 2, the current password (c ) and the two previous passwords (a and b) are valid. Setting this to 3 works the same. Extending the window is useful in high-latency situations.
Enable Two-Factor Auth for SSH
Select to enable 2FA for system SSH access. Leave this disabled until you complete a successful test of 2FA with the UI.
System Security Widget
TrueNAS Enterprise
The System Security widget allows administrators of Enterprise-licensed systems to enable or disable FIPS 140-2 compliant algorithms.
This requires a system reboot to apply the settings.
High Availability (HA) systems reboot the standby controller and then prompt to failover and reboot the primary controller.
Settings opens the System Security configuration screen.
Click the Enable FIPS toggle to enable or disable enforcement, then click Save.
The system prompts to reboot (or failover for HA systems) to apply the settings.
Boot
The System > Boot screen contains options for monitoring and maintaining the TrueNAS install pool and disks.
This includes managing OS restore points, called boot environments, for the TrueNAS system.
The System > Boot screen displays four options at the top right of the screen.
Setting
Description
Stats/Settings
Opens the Stats/Settings window with the Boot pool Condition, Size and Used, and Last Scrub Run statistics for the operating system device, and provides the option to change the default duration between the operating system device scrubs from every 7 days to a new duration in days.
Boot Pool Status
Opens the Boot Pool Status screen that displays the status of each device in the operating system device (boot pool), options for managing boot-pool devices, and lists any read, write, or checksum errors.
Scrub Boot Pool
Opens the Scrub dialog. Performs a manual data integrity check (scrub) of the operating system device.
Boot Pool Status
The System > Boot > Boot Pool Status screen shows the status of the current boot-pool.
It includes the current status, the path, and the number of read, write and checksum errors.
Each time the system updates to a new software release, it creates a new boot environment.
You can also clone an existing boot environment to create an operating system restore point.
Each boot environment on the list includes:
Name which is the name of the boot entry as it appears in the boot menu.
Active that indicates which entry boots by default if a boot environment is not active. Activated environment displays Non/Reboot.
Date Created that shows the creation date and time.
Space shows the boot environment size.
Keep that indicates whether TrueNAS deletes this boot environment when a system update does not have enough space to proceed.
Batch Operations
Select the checkbox(es) for each boot environment. Displays the Batch Operations that allows you to delete the selected environments at one time.
The vertical ellipsis displays a list of boot environment actions that change based on whether it is activated or not.
Boot Environment Actions Lists
The vertical ellipsis for an environment displays actions available to that environment.
Action
Boot State
Description
ActivateActivate
Deactivated
Opens the Activate dialog. Changes the System Boot screen status to Reboot and changes the current Active entry from Now/Reboot to Now, indicating that it is the current boot environment but is not used on next boot.
CloneClone
Both states
Opens the Clone Boot Environment window. Copies the selected boot environment into a new entry. Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
RenameRename
Both states
Opens the Rename Boot Environment window. Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
DeleteDelete
Deactivated
Opens the Delete dialog. Does not display if the boot environment is activated/ You cannot delete the default or activated boot environment. Removes the highlighted entry and also removes that entry from the boot menu.
KeepKeep
If set to false
Opens the Keep dialog, and toggles the boot environment action to Unkeep. Use to prevent the TrueNAS updater from automatically deleting the environment to make more space for a new environment when there is insufficient space for it.
UnkeepUnkeep
If Keep is set to True
Opens the Unkeep dialog, and toggles the boot environment action to Keep. Use to allow TrueNAS updater to automatically delete the environment to make space for a new boot environment when there is not enough space for it.
Failover Screen
TrueNAS Enterprise
This article only applies to SCALE Enterprise (HA) systems.
The System > Failover screen displays settings used on SCALE Enterprise (HA) systems to turn the failover function on or off, sync the primary and standby controllers, and allow administrator users to configure failover. The main menu option and screen only display on Enterprise (HA) systems with the correct license applied.
Setting
Description
Disable Failover
Select to turn failover off. Leave clear to enable failover.
Default TrueNAS controller
Select to make the current active controller the default controller when both TrueNAS controllers are online and HA is enabled. To change the default TrueNAS controller, leave unselected on the default TrueNAS controller and allow the system to fail over. This process briefly interrupts system services.
Network Timeout Before Initiating Failover
Enter a number in seconds to wait after a network failure before triggering a failover. Default is 0 which means failover occurs immediately, or after two seconds when the system is using a link aggregate.
Sync To Peer
Initiates a sync operation that copies over the primary controller configuration to the standby controller. Opens the Sync To Peer dialog to confirm the operation.
Sync From Peer
Initiates a sync operation that copies over the standby controller configuration to the primary controller.
Sync To or From Peer
Sync To Peer and Sync From Peer buttons each open a confirmation dialog before SCALE performs the operation requested.
Setting
Description
Reboot standby TrueNAS controller
Select to cause the standby controller to reboot after the sync operation completes.
Confirm
Select to confirm you want to perform the sync-to-peer operation.
Proceed
Begins the sync operation.
Services
System > Services displays each system component that runs continuously in the background. These typically control data-sharing or other external access to the system. Individual services have configuration screens and activation toggles, and you can set them to run automatically.
SSH Service Screen: Provides information on the SSH service screens and settings.
UPS Services Screen: Provides information on the UPS service screen settings.
FTP Service Screen
The File Transfer Protocol (FTP) is a simple option for data transfers.
The SSH options provide secure transfer methods for critical objects like configuration files, while the Trivial FTP options provide simple file transfer methods for non-critical files.
The FTP service has basic and advanced setting options.
Click the edit for FTP to open the Basic Settings configuration screen.
FTP Basic Settings
To configure FTP, go to System > Services and find FTP, then click edit.
Enter the maximum number of connections per IP address. 0 is unlimited.
Login Attempts
Enter the maximum attempts before the client disconnects. Increase if users are prone to misspellings or typos.
Notransfer Timeout
Enter the maximum number of seconds a client is allowed to spend connected, after authentication, without issuing a command which results in creating an active or passive data connection (sending/receiving a file or receiving a directory listing).
Timeout
Enter the maximum client idle time in seconds before disconnecting. The default value is 600 seconds.
FTP Advanced Settings
Advanced Settings include the General Options on the Basic Settings configuration screen and allow you to specify access permissions, TLS settings, bandwidth, and other settings to customize FTP access.
Access settings specify user login, file, and directory access permissions.
Settings
Description
Always Chroot
Only allows users to access their home directory if they are in the wheel group. This option increases security risk. To confine FTP sessions to a local user home directory, enable chroot and select Allow Local User Login.
Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Allow Anonymous Login
Select to allow anonymous FTP logins with access to the directory specified in Path. Selecting this displays the Path field. Enter or browse the location to populate the field.
Allow Local User Login
Select to allow any local user to log in. Only members of the ftp group may log in by default.
Require IDENT Authentication
Select to require IDENT authentication. Setting this option results in timeouts when IDENT is not running on the client.
File Permissions
Select the default permissions for newly created files.
Directory Permissions
Select the default permissions for newly created directories.
TLS settings specify the authentication methods, such as if you want to encrypt the data you transfer across the Internet.
Settings
Description
Enable TLS
Select to allow encrypted connections. Requires a certificate (created or imported using Credentials > Certificates).
Certificate
Select the SSL certificate for TLS FTP connections from the dropdown list. Click Manage Certificates to go to Credentials > Certificates.
TLS Policy
Select the policy from the dropdown list of options. Options are On, off, Data, !Data, Auth, Ctrl, Ctrl + Data, Ctrl +!Data, Auth + Data or Auth +!Data. Defines whether the control channel, data channel, both channels, or neither channel of an FTP session must occur over SSL/TLS. The policies are described here.
TLS Allow Client Renegotiations
Select to allow client renegotiation. We do not recommend this option. Setting this option breaks several security measures. See mod_tls for details.
TLS Allow Dot Login
TrueNAS checks the user home directory for a .tlslogin file containing one or more PEM-encoded certificates. If not found, the user must enter their password.
TLS Allow Per User
Select to allow sending a user password unencrypted.
TLS Common Name Required
Select to require the common name in the certificate to match the FQDN of the host.
TLS Enable Diagnostics
Select for more verbose logging, which is helpful when troubleshooting a connection.
TLS Export Certificate Data
Select to export the certificate environment variables.
TLS No Certificate Request
Select if the client cannot connect, likely because the client server is not correctly handling the server certificate request.
TLS No Empty Fragments
Not recommended. This option bypasses a security mechanism.
TLS No Session Reuse Required
This option reduces connection security. Only use it if the client does not understand reused SSL sessions.
TLS Export Standard Vars
Select to set several environment variables.
TLS DNS Name Required
Select to require the client DNS name to resolve to its IP address and the cert contain the same DNS name.
TLS IP Address Required
Select to require the client certificate IP address to match the client IP address.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
Settings
Description
Local User Upload Bandwidth: (Examples: 500 KiB, 500M, 2 TB)
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Local User Download Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Anonymous User Upload Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
Anonymous User Download Bandwidth
Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited.
iSCSI Services Screen
The iSCSI screen displays settings to configure iSCSI block shares.
About the Block (iSCSI) Sharing Protocol
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations.
IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack. The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack.
Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance could suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
OSI Layer Number
OSI Layer Name
Activity as it relates to iSCSI
7
Application
An application tells the CPU that it needs to write data to non-volatile storage.
6
Presentation
OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage.
5
Session
Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU).
4
Transport
OSI encapsulates the iSCSI PDU within a TCP segment.
3
Network
OSI encapsulates the TCP segment within an IP packet.
2
Data
OSI encapsulates the IP packet within the Ethernet frame.
1
Physical
The Ethernet frame transmits as bits (zeros and ones).
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing.
Block sharing provides the benefit of block-level access to data on the TrueNAS.
iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
iSCSI Terminology
Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively. iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network. The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes.
It also requires that each node is given a unique iSCSI name.
To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
dash (-)
dot (.)
colon (:)
lower case characters (a…z).
Upper-case characters must be mapped to their related lower-case counterparts.
digits (0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN. The result is an iSCSI connection that emulates a connection to a SCSI hard disk. Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs. When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size. This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU). A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways.
Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames.
Systems administrators should also account for the impact on host CPU utilization.
Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment.
Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency.
Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.
TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system.
HA storage clusters can provide multiple paths to the same storage.
For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer.
The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage.
If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage.
When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.
iSCSI Configuration Methods
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS Enterprise
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores.
This is all managed through the vCenter web interface.
TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
iSCSI Configuration Screens
The iSCSI configuration screens display seven tabs, one for each of the share configuration areas.
The Add button at the top of the Sharing > iSCSI screen works with the currently selected tab or screen. For example, if Portals is the current tab/screen, the Add button opens the Add Portal screen.
The more_vert on configure tab screens with list views display the Edit and Delete options. Edit opens the Edit screen for the selected tab screen. For example, when on the Portals tab/screen, the Sharing > iSCSI > Portals > Edit screen opens.
The Delete option opens the delete dialog for the screen currently selected.
The Add and Edit screens display the same settings.
Target Global Configuration Screen
The Target Global Configuration displays configuration settings that apply to all iSCSI shares.
There are no add, edit, or delete options for this screen.
It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
Setting
Description
Base Name
Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
ISNS Servers
Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Pool Available Space Threshold (%)
Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port
The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators.
Asymmetric Logical Unit Access (ALUA)
Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server.
Portals Screens
The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
The more_vert next to the portal displays the Edit and Delete options.
Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
Basic Info Settings
Setting
Description
Description
Enter an optional description. Portals are automatically assigned a numeric group.
Authentication Method and Group Settings
Setting
Description
Discovery Authentication Method
Select the discovery method you want to use for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None, you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP, you must enter or create a new group in Discovery Authentication Group.
Discovery Authentication Group
Select the discovery authentication group you want to use from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is CHAP or Mutual CHAP. Select None or Create New. Create New displays additional setting options.
IP Address Settings
Setting
Description
IP Address
Select the IP addresses the portal listens to. Click Add to add IP addresses with a different network port. 0.0.0.0 listens on all IPv4 addresses, and :: listens on all IPv6 addresses.
Port
TCP port used to access the iSCSI target. The default is 3260.
Add
Adds another IP address row.
Initiators Groups Screen
The Initiators Groups screen display settings to create new authorized access client groups or edit existing ones in the list.
The more_vert next to the initiator group displays the Edit and Delete options.
Delete opens the Delete dialog for the selected group ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Sharing > iSCSI > Initiators > Add screen. Edit opens the Sharing > iSCSI > Initiators > Edit screen. Both screens have the same setting options.
Setting
Description
Allow All Initiators
Select to allows all initiators.
Allowed Initiators (IQN)
Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description
Enter any notes about the initiators.
Authorized Access Screen
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Add opens the Add Authorized Access screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Authorized Access screen, and Delete opens a dialog to delete the authorized access for the selected user.
The Add and Edit screens display the same settings.
Group Settings
Setting
Description
Group ID
Enter a number. This allows configuring different groups with different authentication profiles. Example: all users with a group ID of 1 inherit the authentication profile associated with Group 1.
User Settings
Setting
Description
User
User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret
Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a “password does not match” error until you enter the same password in Secret (Confirm).
Secret (Confirm)
Enter the same password to confirm the user password.
Peer User Settings
Setting
Description
Peer User
Optional. Enter only when configuring mutual CHAP. Usually the same value as User.
Peer Secret
Enter the mutual secret password. Required if entering a Peer User. Must be a different password than the password in Secret.
Peer Secret (Confirm)
Enter the same password to confirm the mutual secret password.
Targets Screen
The Targets screen displays settings to create new TrueNAS storage resources or edit existing ones in the list.
Add opens the Add iSCSI Targets screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit iSCSI Targets screen, and Delete opens a dialog to delete the select target.
The Add iSCSI Targets and Edit iSCSI Targets screens display the same settings.
Add and Edit iSCSI Target Screens
The Add iSCSI Target and Edit iSCSI Target screens display the same settings, but the current settings populate the Edit iSCSI Target screen settings for the selected share.
To access the Add iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click Add at the top of the screen.
To access the Edit iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click more_vert next to the share and then click Edit.
Extents Screen
The Extents screen displays settings to create new shared storage units or edit existing ones in the list.
Add opens the Add Extent screen.
The more_vert next to each entry opens two options, Edit and Delete. Edit opens the Edit Extent screen, and Delete opens a dialog to delete the extents for the selected user.
The Add and Edit screens display the same settings.
Basic Info Settings
Setting
Description
Name
Enter a name for the extent. An Extent where the size is not 0, cannot be an existing file within the pool or dataset.
Description
Enter any notes about this extent.
Enabled
Select to enable the iSCSI extent.
Type Settings
Setting
Description
Extent Type
Select the extent (zvol) option from the dropdown list. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file.
Device
Required. Displays if Extent Type is set to Device. Select the unformatted disk, controller, or zvol snapshot.
Path to the Extent
Displays when Extent Type is set to File. Click the play_arrow to browse an existing file. Create a new file by browsing to a dataset and appending /{filename.ext} to the path. Users cannot create extents inside a jail root directory.
Filesize
Only appears if File is selected. Entering 0 uses the actual file size and requires that the file already exists. Otherwise, specify the file size for the new file.
Logical Block Size
Enter a new value or leave it at the default of 512 unless the initiator requires a different block size.
Disable Physical Block Size Reporting
Select if the initiator does not support physical block size values over 4K (MS SQL).
Compatibility Settings
Setting
Description
Enable TPC
Select to allow an initiator to bypass normal access control and access any scannable target. This allows xcopy operations that are otherwise blocked by access control.
Xen initiator compat mode
Select when using Xen as the iSCSI initiator.
LUN RPM
Select the option from the dropdown list. Options are UNKNOWN, 5400, 7200, 10000 or 15000. Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics.
Read-only
Select to prevent the initiator from initializing this LUN.
Associated Targets Screen
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user.
The Add and Edit screens display the same settings.
Setting
Description
Target
Required. Select an existing target.
LUN ID
Select the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID.
Extent
Required. Select an existing extent.
NFS Services Screen
The System > Services screen includes two icons on the NFS service row:
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel.
Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
NFS Service Screen
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
You can access it from System > Services screen.
Locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
Select IP addresses to listen to for NFS requests. Leave empty for NFS to listen to all available addresses. You must configure static IPs on the interface for them to appear on the dropdown list.
Calculate number of threads dynamically
Automatically sets the number of threads used by the kernel NFS server.
Specify number of threads manually
Shows after deselecting Calculate number of threads dynamically. Enter an optimal number of threads used by the kernel NFS server.
NFSv4 Settings
Setting
Description
Enabled Protocols
Select NFSv3, NFSv4, or both. If NFSv4 is selected, NFSv3 ownership model for NFSv4 clears, allowing you to select or leave it clear.
NFSv4 DNS Domain
Select to use the value to override the default DNS domain name ofr NFSv4. Speicifies the domain idmapd.conf setting.
NFSv3 ownership model for NFSv4
Becomes selectable after selecting NFSv4. Select when you need NFSv4 ACL support without requiring the client and the server to sync users and groups. Selecting this deactivates the Manage Groups Server-side option.
Require Kerberos for NFSv4
Select to force NFS shares to fail if the Kerberos ticket is unavailable.
Select if NFS clients need to use the User Datagram Protocol (UDP).
Allow non-root mount
Only select if required by the NFS client to allow serving non-root mount requests.
Manage Groups Server-side
This option allows the server to determine group IDs based on server-side lookups rather than relying solely on the information provided by the NFS client. This can support more than 16 groups and provide more accurate group memberships. Equivalent to the --manage-gids flag for rpc.mountd.
We recommend using the default NFS settings unless you require specific settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
S.M.A.R.T. Service Screen
The Services > S.M.A.R.T. screen displays settings to configure when S.M.A.R.T. tests run and when to trigger alert warnings and send emails.
Name
Description
Check Interval
Enter the time in minutes for smartd to wake up and check if any tests are configured to run.
Power Mode
Select the power mode from the dropdown list. Options are Never, Sleep, Standby or Idle. S.M.A.R.T. only tests when the Power Mode is Never.
Difference
Enter a number of degrees in Celsius. S.M.A.R.T. reports if a drive temperature changes by N degrees Celsius since the last report.
Informational
Enter a threshold temperature in Celsius. S.M.A.R.T. sends a message with a LOG_INFO log level if the temperature is above the threshold.
Critical
Enter a threshold temperature in Celsius. S.M.A.R.T. sends a message with a LOG_CRIT log level and send an email if the temperature is above the threshold.
Click Save after changing any settings.
SMB Service Screen
The System > Services screen includes three icons on the SMB service row:
Click Save or Cancel to close the configuration screen and return to the Services screen.
Basic Settings
Setting
Description
NetBIOS Name
Automatically populates with the original system host name. Enter a name that does not exceed 15 characters that is not the same as the Workgroup name.
NetBIOS Alias
Enter any alias name that does not exceed 15 characters in length. If entering multiple aliases, separate alias names with a space between them.
Workgroup
Enter a name that matches the Windows workgroup name. If you do not configure a workgroup, and Active Directory or LDAP is active, TrueNAS detects and sets the correct workgroup from these services.
Description
(Optional) Enter any notes or descriptive details about the service configuration.
Enable SMB1 support
Select to allow legacy SMB1 clients to connect to the server (see caution below). SMB audit logging does not work when using SMB1.
NTLMv1 Auth
Off by default. Select to allow smbd attempts to authenticate users with the insecure and vulnerable NTLMv1 encryption. This setting allows backward compatibility with older versions of Windows, but we do not recommend it. Do not use on untrusted networks.
As of SCALE 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 SCALE SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
Select the character set to use internally from the dropdown list of options. UTF-8 is standard for most systems as it supports all characters in all languages.
Transport Encryption Behavior
Select the option for the level of transport encryption to implement. Options and behaviors:
Default - follow upstream/TrueNAS default
Negotiate - only encrypt transport if explicitly requested by the SMB client
Desired - encrypt transport if supported by client during session negotiation
Required - always encrypt transport (rejecting access if client does not support encryption - incompatible with SMB1 server enable_smb1)
the TrueNAS and Samba default behavior allows SMB clients to negotiate different encryption levels for SMB shares. When set to Default, there is no technical limitation preventing an SMB client from negotiating an encrypted session if it is required. Default enables negotiating encryption but does not turn on data encryption globally per share. For more information on SMB1 and SMB2 session or per-share encryption, see Samba Server SMB Encrypt(s). For more information on using Windows client-side SMB signing, see Windows SMB Signing Policies.
Log Level
Record SMB service messages up to the specified log level from the dropdown list. Options are None, Minimum, Normal, full and Debug. By default, TrueNAS logs error and warning-level messages. We do not recommend using a log level above Minimum for production servers.
Use Syslog Only
Select to log authentication failures in /var/log/messages instead of the default /var/log/samba4/log.smbd.
Local Master
Selected by default and determines if the system participates in a browser election. Leave cleared when the network contains an Active Directory or LDAP server or when Vista or Windows 7 machines are present.
Enable Apple SMB2/3 Protocol Extensions
Select to allow MacOS to use these protocol extensions to improve the performance and behavioral characteristics of SMB shares. TrueNAS requires Apple SMB2/3 protocol extensions for Time Machine support.
Multichannel
SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance. SMB multichannel does not function if you combine NICs into a LAGG.
Enter or select members from the dropdown list. Members of this group are local administrators and automatically have privileges to take ownership of any file in an SMB share, reset permissions, and administer the SMB server through the Computer Management MMC snap-in.
Guest Account
Select the account for guest access from the dropdown list. The default is nobody. The selected account must have permission for the shared pool or dataset. To adjust permissions, edit the dataset Access Control List (ACL), add a new entry for the chosen guest account, and configure the permissions in that entry. If you delete the selected Guest Account, the field resets to nobody.
File Mask
Overrides default 0664 file creation mask, which creates files with read and write access for everybody.
Directory Mask
Overrides default directory creation mask of 0775, which grants everyone directory read, write, and execute access.
Bind IP Addresses
Select static IP addresses that SMB listens on for connections from the dropdown list. Leaving all unselected defaults to listening on all active interfaces.
SNMP Service Screen
The Service > SNMP screen settings configure SNMP (Simple Network Management Protocol) that monitors network-attached devices for conditions that warrant administrative attention.
Click the edit to open the Services > SNMP configuration screen.
General Options
SNMP v3 Options
Setting
Description
Location
Enter the location of the system.
Contact
Enter the email address to receive SNMP service messages.
Community
Enter a community other than the default public to increase system security. Value can only contain alphanumeric characters, underscores (_), dashes (-), periods (.), and spaces. Not required and can leave this empty for SNMPv3 networks.
SNMP v3 Support Options
Setting
Description
SNMP v3 Support
Select to to enable support for SNMP version 3 and display the SNMP v3 setting fields. See snmpd.conf(5) for configuration details.
Username
Enter a user name to register with this service.
Authentication Type
Select an authentication method: — for none, SHA, or MD5 from the dropdown list.
Password
Enter a password of at least eight characters.
Privacy Protocol
Select a privacy protocol: — for none, AES, or DES from the dropdown list.
Privacy Passphrase
Enter a separate privacy passphrase. Password is used when this is left empty.
Other Options
Setting
Description
Auxiliary Parameters
Enter any additional snmpd.conf options. Add one option for each line.
Expose zilstat via SNMP
Select to enable. If enabled this option might have performance implications on your pools.
Log Level
Select how many log entries to create. Dropdown list options are Emergency, Alert, Critical, Error, Warning, Notice, Info and Debug.
SSH Service Screen
The System > Services > SSH screen allows you to set up SSH service on TrueNAS SCALE.
Click edit to open the Services > SSH configuration screen.
Allowing external connections to TrueNAS is a security vulnerability!
Do not enable SSH unless you require external connections.
See Security Recommendations for more security considerations when using SSH.
You must also configure SSH backup credentials to allow SSH access. See SSH Screens for more information.
SSH Basic Settings Options
The Basic Settings options display by default when you edit the SSH service.
Enter the port number for SSH connection requests.
Password Login Groups
List of TrueNAS account groups allowed to use a password for logging in to the system with SSH. Click in the field to see a list of current account groups. Begin typing in the field to filter the groups list. Left click a list item to add it to the field. Click the for an entry to remove it from the field.
Allow Password Authentication
Select to enable and allow using a password to authenticate the SSH login. If disabled (not selected), authentication changes to require SSH keys for all users. This requires additional setup for both the SSH client and server. Warning: when directory services are enabled, this setting grants access to all users the directory service imported.
Allow Kerberos Authentication
Select to allow Kerberos authentication. Ensure valid entries exist in Directory Services > Kerberos Realms and Directory Services > Kerberos Keytabs and the system can communicate with the Kerberos domain controller before enabling this option.
Allow TCP Port Forwarding
Select to allow users to bypass firewall restrictions using SSH port forwarding. For best security, leave disabled and deny shell access to users.
SSH Advanced Settings Options
Advanced Settings include the General Options settings. Advanced settings specify bind interfaces, SFTP settings, ciphers and any additional parameters you want to use.
Select the network interface configured on your system for SSH to listen on from the dropdown list. Leave all options unselected for SSH to listen on all interfaces.
Compress Connections
Select to attempt to reduce latency over slow networks.
SFTP Log Level
Select the syslog(3) level of the SFTP server from the dropdown list. Options are Quiet, Fatal, Error, Info, Verbose, Debug, Debug2 or Debug3.
SFTP Log Facility
Select the syslog(3) facility of the SFTP server option from the dropdown list. Options are Daemon, User, Auth and Local 0 through Local7.
Weak Ciphers
Select a cipher from the dropdown list. Options are None or AES128-CBC. To allow more ciphers for sshd(8) in addition to the defaults in sshd_config(5). Use None to allow unencrypted SSH connections. Use AES128-CBC to allow the 128-bit Advanced Encryption Standard. WARNING: These ciphers are security vulnerabilities. Only allow them in a secure network environment.
Auxiliary Parameters
Enter any sshd_config(5) options not covered in this screen. Enter one option per line. Options added are case-sensitive. Misspellings can prevent the SSH service from starting.
UPS Services Screen
The Services > UPS screen settings specify connection, shutdown and other settings to configure UPS service for servers running TrueNAS SCALE.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support.
For supported device and driver information, see their hardware compatibility list.
Further device-specific compatibility information is available from the NUT Devices Dumps Library.
Required. Type a description for the UPS device. You can use alphanumeric, period (.), comma (,), hyphen (-), and underscore (_) characters.
UPS Mode
Select the either Master or Slave mode from the dropdown list. Select Master if the UPS is plugged directly into the system serial port, or Slave to shut down this system before the master system. Slave displays the Remote Hostname and Remote Port fields, and removes the Driver field. The UPS remains the last item to shut down. See the Network UPS Tools Overview.
Remote Host
Required. Enter a valid IP address for the remote system with the UPS Mode set to Master. This field displays only when UPS Mode is set to Slave.
Remote Port
Required. Enter the open network port number of the UPS master system. The default port is 3493. This field displays only when UPS Mode is set to Slave.
Driver
Required. Enter or select the device driver from the dropdown list. See the Network UPS Tools compatibility list for a list of supported UPS devices. This field displays only when UPS Mode is set to Master.
Port or Hostname
Required. Enter or select the serial or USB port connected to the UPS from the dropdown list. Options include a list of port on your system and auto. Select auto to automatically detect and manage the USB port settings. When selecting an SNMP driver, enter the IP address or host name of the SNMP UPS device.
Monitor Settings
Monitor settings specify the primary username and password, other users that have administrative access to the UPS service, and whether the default configuration listens on all interfaces.
Setting
Description
Monitor User
Enter a user to associate with this service. Keeping the default is recommended.
Monitor Password
Change the default password to improve system security. The new password cannot include a space or #.
Extra Users
Enter accounts that have administrative access. See upsd.users(5) for examples.
Remote Monitor
Select to have the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.
Shutdown Settings
Shutdown settings specify the UPS shutdown mode, command, and timer for the UPS service.
Select the battery option to used when the UPS initiates shutdown from the dropdown list. Options are UPS reaches low battery or UPS goes on battery.
Shutdown Timer
Enter a value in seconds for the UPS to wait before initiating shutdown. Shutdown does not occur if power is restored while the timer is counting down. This value only applies when Shutdown Mode is set to UPS goes on battery.
Shutdown Command
Enter a command to shut down the system when either battery power is low or the shutdown timer ends.
Power off UPS
Select to power off the UPS after shutting down the system.
Other Options Settings
Other Options settings specify warning and host sync times, a description for the UPS, and any additional parameters you want to apply to the UPS service.
SCALE System > Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information.
When the user Shell setting is set to TrueNAS Console, the Shell screen opens and shows the TrueNAS Console Setup menu.
The Set font size slider adjusts the Shell displayed text size.
Restore Default resets the font size to default.
The Shell stores the command history for the current session.
Leaving the Shell screen clears the command history.
Click Reconnect to start a new session.
Alert Settings Screen
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies.
To access this screen, click the notifications icon, then click the settings icon and select Alert Settings on the dropdown list.
Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
Add/Edit Alert Service Screen
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default.
To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the more_vert icon for the service, and then click Edit to display the Edit Alert Service screen.
Name and Type Settings
Setting
Description
Name
Enter a name for the new alert service.
Enabled
Clear the checkmark to disable this service without deleting it.
Type
Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS.
Level
Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. TrueNAS SCALE sends alert notifications for all warnings matching and above the selected level. For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Alert Service Types
AWS SNS
Click here for more information
Select AWS SNS from the Type dropdown list to display AWS SNS authentication settings.
Select OpsGenie from the Type dropdown list to display OpsGenie authentication settings.
Authentication Settings
Setting
Description
API Key
Enter the API key. Find the API key by signing into the OpsGenie web interface and going to Integrations/Configured Integrations. Click the desired integration, Settings, and read the API Key field.
Select SNMP Trap from the Type dropdown list to display SNMP trap authentication settings.
Authentication Settings
Setting
Description
Hostname
Enter the hostname or IP address of the system to receive SNMP trap notifications.
Port
Enter the UDP port number on the system receiving SNMP trap notifications. The default is 162.
SNMPv3 Security Model
Select to enable the SNMPv3 security model.
SNMP Community
Enter the network community string. The community string acts like a user ID or password. A user with the correct community string can access network information. The default is public. For more information, see What is an SNMP Community String?.
Telegram
Click here for more information
Select Telegram from the Type dropdown list to display Telegram authentication settings.
Enter a list of chat IDs separated by a space ( ), comma (,), or semicolon (;). To find your chat ID, send a message to the bot, group, or channel and visit https://core.telegram.org/bots/api#getting-updates.
VictorOPS
Click here for more information
Select VictorOps from the Type dropdown list to display VictorOps authentication settings.
Use the Category dropdown list to display alert settings for each category.
Applications
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Click here for more information
You can customize alert settings for when available applications have updates, catalog is not healthy, the system cannot configure or start applications, and the system cannot sync the catalog.
Certificates
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Click here for more information
You can customize alert settings for when a certificate expires, a certificate parsing fails, a certificate revokes, and the web UI HTTPS certificate setup fails.
Directory Service
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
Click here for more information
You can customize alert settings for when the Active Directory bind is unhealthy, Active Directory domain validation fails, the domain is offline, and the LDAP bind bind is unhealthy.
High Availability Settings
TrueNAS Enterprise
This section only applies to TrueNAS Enterprise hardware.
High Availability alert settings apply to TrueNAS Enterprise HA systems and only displays on the list of alerts for dual-controller High-Availability systems with an Enterprise license applied.
Click here for more information
You can customize alert settings for when an automatic sync to peer fails, disks are missing on the active and/or standby controller, the system fails to check failover status with the other controller, syncing operations fail such as encryption keys to peer and KMIP keys to peer, the failover interface is not found, and when a failover action fails.
Hardware
Hardware alert settings apply to the IPMI network connections, and S.M.A.R.T. and smartd that monitors the hard drives installed on your TrueNAS system.
Click here for more information
You can customize alert settings for when disk(s) format with the data integrity feature, IPMI has system events, the IPMI system event log space is low, S.M.A.R.T. has an error, and smartd is not running.
The IPMI System Event Log (SEL) stores system events and can assist with debugging hardware issues.
Review IPMI SEL alerts and resolve any underlying hardware issues before clearing space in the SEL.
Consult manufacturer documentation for your motherboard to learn how to review IPMI system events and clear the log.
Key Management Interoperability Protocol (KMIP)
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Click here for more information
You can customize alert settings for when the system fails to communicate, sync the SED global password, and sync keys with the KMIP server.
Plugins
Plugins alert settings apply to plugins installed on your TrueNAS.
Click here for more information
You can customize the alert setting for when plugin updates are available.
Network
Network alert settings apply to network interfaces configured on your TrueNAS.
Click here for more information
You can customize alert settings for when ports are not active on the LAGG interface and when the LAGG interface has no active ports.
Reporting
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Click here for more information
You can customize alert settings for when netdata has critical alerts and warnings, the reporting database size exceeds the threshold, and syslog-ng is not running.
Sharing
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Click here for more information
You can customize alert settings for when a deprecated service is running, IP addresses bound to an iSCSI portal are not found, NFS services cannot bind to specific IP addresses using 0.0.0.0, and the system cannot resolve NFS share references hosts.
You can also customize alerts for when NTLMv1 attempts authentication in the last 24 hours, SMB1 connections to TrueNAS server are performed in the last 24 hours, and a share is unavailable because it uses a locked dataset.
Storage
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
Click here for more information
You can customize alert settings for when a dataset exceeds standard and critical quotas, a pool has new available feature flags, pool space usage exceeds 70, 80, or 90 percent, and pool status is not healthy.
You can change alert settings for when a pool consumes USB disks, a scrub pauses, and too many snapshots exist.
System
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system reboots, updates, and the web interface.
Click here for more information
You can customize alert settings for when the admin user is overridden, the boot pool is unhealthy, the system dataset has core files, a device slows down pool I/O, NTP health checks fail, and TrueCommand API keys are disabled or need confirmation.
You can also change alert settings for when SSH logins fail, the system is not ready for Kdump, the web UI cannot bind to a configured address, TrueCommand fails health checks, the system reboots off schedule, and update are available, failed, or not applied.
Tasks
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
Click here for more information
You can customize alert settings for when cloud sync tasks, VMWare snapshot creation, login, and deletion, replication, rsync tasks, scrubs, and snapshot tasks fail in general or due to locked datasets.
You can also change alert settings for when replication, rsync tasks, and scrubs succeed.
UPS
UPS alert settings apply to a UPS connected to your TrueNAS.
Click here for more information
You can customize alert settings for when the UPS battery is low or needs replacement, the UPS establishes or loses communication, and the UPS is on battery or line power.
Alert Warning Levels
Use the Set Warning Level dropdown list to customize alert importance.
Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
TrueNAS SCALE sends alert notifications for all warnings matching and above the selected level
For example, a warning level set to Critical triggers notifications for Critical, Alert, and Emergency level warnings.
Level
Icon
Alert Notification?
INFO
No
NOTICE
Yes
WARNING
Yes
ERROR
Yes
CRITICAL
Yes
ALERT
Yes
EMERGENCY
Yes
Alert Frequency
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
View Enclosure Screen (TrueNAS Systems Only)
The View Enclosure screen only displays on compatible TrueNAS hardware.
The UI options to select System > Enclosure is not present on incompatible systems.
The System Information widget on the main Dashboard displays an image of the host TrueNAS system.
Hover the mouse over the image to see the View Enclosure label.
Click anywhere on the system image to open the View Enclosure screen.
The View Enclosure screen displays an image of the TrueNAS platform.
Additional information about storage pools, drives, and other hardware components is available through a variety of elements and buttons.
The Elements button at the top right of the View Enclosure screen displays a dropdown list of options to view information about the system or expansion shelf.
The options vary by TrueNAS platform, if the system is connected to expansion shelves, and if you have an expansion shelf image selected instead of the main system.
All TrueNAS systems include the Disks option. TrueNAS systems with expansion shelves include the Temperature, Power Supply, and Voltage options.
The expansion shelf includes the Disks, Cooling, Services, Power Supply, SAS, Temperature, and Voltage options.
Each option displays a table with readings from the system’s internal components taken over a period of time.
Change Enclosure Label
Edit Label displays for the main system (except TrueNAS Minis) and expansion shelves.
Edit Label opens the Change Enclosure Label window.
Type a name or description for the system and click Save to apply the label.
To simplify system maintenance, use labels that help identify the physical location of the system, such as ES102 Rack D5 U20.
Reset to Default restores the default name for the system.
System Image Screens
System images display the front view of the system by default.
System image screens include options to change the information on the screen:
Show Pools shows disks highlighted in pools on the system image.
Show Status shows healthy or failed disks in the system and a status indicator color legend.
Show Expander Status shows a SAS expander status indicator for systems with one or more expander.
TrueNAS Mini Enclosure Screens
TrueNAS Mini systems display the front view of the system chassis.
Pool information displays at the top of the screen.
The drive bay number and disk label displays to the left of the image and the status to the right of the image.
The Disk Overview section provides general details about the system drive hardware and capacity.
Drive Temperatures displays current readings for each drive in the system.
The right side of the screen includes smaller thumbnail images of both the main system and any expansion shelves connected to the system.
A blue vertical line to the left of the thumbnail image indicates the selected enclosure.
Both the system and expansion shelf images show installed disk locations.
Click on a drive image in the system or expansion shelf to display a drive information screen for that drive.
Disk drive information includes the system pool, disk status, hardware details, and stats for the drive.
Identify on disk detail screens turns on the LED indicator located on a physical drive bay in the system server.
This helps to identify the physical drive bay that corresponds to the SCALE identification number for that drive.
Select the drive on the image and then click Identify.
Go to the location of the system server to locate the drive bay with the LED indication turned on, then check the drive location on the View Enclosure screen.
TrueNAS Mini and R30 systems do not include the IDENTIFY function.
The expansion shelf image varies based on the type of expansion shelf installed.
The disk information displayed is the same as for disks in the main system chassis.
