Back to Docs Hub
SCALE system management options are collected in this section of the UI and organized into a few different screens:
Update controls when the system applies a new version. There are options to download and install an update, have the system check daily and stage updates, or apply a manual update file to the system.
General shows system details and has basic, less intrusive management options, including web interface access, localization, and NTP server connections. This is also where users can input an Enterprise license or create a software bug ticket.
Advanced contains options that are more central to the system configuration or meant for advanced users. Specific options include configuring the system console, log, and dataset pool, managing sessions, adding custom system controls, kernel-level settings, scheduled scripting or commands, global two-factor authentication, and determining any isolated GPU devices. Warning: Advanced settings can be disruptive to system function if misconfigured.
Boot lists each ZFS boot environment stored on the system. These restore the system to a previous version or specific point in time.
Services displays each system component that runs continuously in the background. These typically control data sharing or other external access to the system. Individual services have their own configuration screens and activation toggles, and can be set to run automatically.
Shell allows users to use the TrueNAS Operating System command-line interface (CLI) directly in the web UI. Includes an experimental TrueNAS SCALE-specific CLI for configuring the system separately from the web interface. See the CLI Reference Guide for more information.
Alert Settings allows users to configure Alert Services and to adjust the threshold and frequency of various alert types. See Alerts Settings Screens for more information.
Enclosure appears when the system is attached to compatible SCALE hardware. This is a visual representation of the system with additional details about disks and other physical hardware components.
TrueNAS has several software branches (linear update paths) known as trains. If SCALE is in a prerelease train it can have various preview/early build releases of the software.
The Update Screen only displays the current train. When looking to upgrade SCALE to a new major version, make sure to upgrade SCALE along the path of major versions until the system is on the desired major version release. For more information on other available trains and the upgrade path from one version to the next, see Software Releases.
See the Software Status page for the latest recommendations for software usage. Do not change to a prerelease or nightly release unless the system is intended to permanently remain on early versions and is not storing any critical data.
If you are using a non-production train, be prepared to experience bugs or other problems. Testers are encouraged to submit bug reports and debug files. For information on how to file an issue ticket see Filing an Issue Ticket in SCALE.
The TrueNAS SCALE Update screen provides users with two different methods to update the system, automatic or manual.
We recommend updating SCALE when the system is idle (no clients connected, no disk activity, etc.). The system restarts after an upgrade. Update during scheduled maintenance times to avoid disrupting user activities.
All auxiliary parameters are subject to change between major versions of TrueNAS due to security and development issues. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
If an update is available, click Apply Pending Update to install it.
The Save configuration settings from this machine before updating? window opens.
Click Export Password Secret Seed then click Save Configuration. The Apply Pending Updates window opens.
Click Confirm, then Continue to start the automatic installation process. TrueNAS SCALE downloads the configuration file and the update file, then starts the install.
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
If the system detects an available update, to do a manual update click Download Updates and wait for the file to download to your system.
SCALE Manual update files are available from the TrueNAS SCALE Download page website.
Click Install Manual Update File. The Save configuration settings from this machine before updating? window opens. Click Export Password Secret Seed then click Save Configuration. The Manual Update screen opens.
Click Choose File to locate the update file on the system. Select a temporary location to store the update file. Select Memory Device or select one of the mount locations on the dropdown list to keep a copy in the server.
Click Apply Update to start the update process. A status window opens and displays the installation progress. When complete, a Restart window opens.
Click Confirm, then Continue to restart the system.
When a system update starts, appears in the toolbar at the top of the UI. Click the icon to see the current status of the update and which TrueNAS administrative account initiated the update.
After updating, you might find that you can update your storage pools and boot-pool to enable new supported and requested features that are not enabled on the pool.
Go to System Settings > Shell and enter cli
to enter the CLI if Shell does not open in the CLI.
To show which pools you can update, first enter a query command to see the list of pools on your system and the id number for each pool.
storage pool query
Next, check the update status:
storage pool is_upgraded id=2
where 2 is the pool ID number you want to check the update status for.
To update the pool, enter:
storage pool upgrade id=2
Upgrading pools is a one-way operation. After upgrading pools to the latest zfs features, you might not be able to boot into older versions of TrueNAS.
TrueNAS EnterpriseThis procedure only applies to SCALE Enterprise (HA) systems. If attempting to migrate from CORE to SCALE, see Migrating from TrueNAS CORE.
If the system does not have an administrative user account, create the admin user as part of this procedure.
Take a screenshot of the license information found on the Support widget on the System Settings > General screen. You use this to verify the license after the update.
To update your Enterprise (HA) system to the latest SCALE release, log into the SCALE UI using the virtual IP (VIP) address and then:
Check for updates. Go to the main Dashboard and click Check for Updates on the System Information widget for the active controller. This opens the System Settings > Update screen. If an update is available it displays on this screen.
Save the password secret seed and configuration settings to a secure location. Click Install Manual Updates. The Save configuration settings window opens. Select Export Password Secret Seed then click Save Configuration. The system downloads the file. The file contains sensitive system data and should be maintained in a secure location.
Select the update file and start the process. Click Choose File and select the update file downloaded to your system, then click Apply Update to start the update process. After the system to finishes updating it reboots.
Sign into the SCALE UI. If using root to sign in, create the admin account now. If using admin, continue to the next step.
Verify the system license after the update. Go to System Settings > General. Verify the license information in the screenshot of the Support widget you took before the update matches the information on the Support widget after updating the system.
Verify the admin user settings, or if not created, create the admin user account now.
If you want the admin account to have the ability to execute sudo
commands in an SSH session, select the option for the sudo access you want to allow.
Also, verify Shell is set to bash if you want the admin user to have the ability to execute commands in Shell.
To set a location where the admin user can save to, browse to, and select the dataset in Home Directory. If set to the default /nonexistent files are not saved for this user.
Test the admin user access to the UI.
a. Log out of the UI.
b. Enter the admin user credentials in the sign-in splash screen.
After validating access to the SCALE UI using the admin credentials, disable the root user password. Go to Credentials > Local User and edit the root user. Select Disable Password and click Save.
Finish the update by saving your updated system configuration file to a secure location and create a new boot environment to use as a restore point if it becomes necessary.
The TrueNAS SCALE General Settings section provides settings options for support, graphic user interface, localization, NTP servers, and system configuration.
TrueNAS SCALE allows users to manage the system configuration by uploading or downloading configurations, or by resetting the system to the default configuration.
The Manage Configuration option on the System Settings > General screen provides three options:
The Download File option downloads your TrueNAS SCALE current configuration to the local machine.
When you download the configuration file, you have the option to Export Password Secret Seed, which includes encrypted passwords in the configuration file. This 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 backups containing the seed to prevent unauthorized access or password decryption.
We recommend backing up the system configuration regularly. Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues. Save the configuration file each time the system configuration changes.
Go to System Settings > General and click on Manage Configuration. Select Download File.
The Save Configuration dialog displays.
Click Export Password Secret Seed and then click Save. The system downloads the system configuration. Save this file in a safe location on your network where files are regularly backed up.
Anytime you change your system configuration, download the system configuration file again and keep it safe.
The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS SCALE configuration file.
All passwords are reset if the uploaded configuration file was saved without selecting Save Password Secret Seed.
TrueNAS Enterprise
Save the current system configuration with the Download File option before resetting the configuration to default settings! If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.
The Reset to Defaults option resets the system configuration to factory settings. After the configuration resets, the system restarts and users must set a new login password.
SCALE does not automatically back up the system configuration file to the system dataset.
Users who want to schedule an automatic backup of the system configuration file should:
Users can manually back up the SCALE config file by downloading and saving the file to a location that is automatically backed up.
The TrueNAS SCALE General Settings section provides settings options for support, graphic user interface, localization, NTP servers, and system configuration.
The Support widget shows information about the TrueNAS version and system hardware. Links to the open source documentation, community forums, and official Enterprise licensing from iXsystems are also provided.
Add License opens the sidebar with a field to paste a TrueNAS Enterprise license (details).
File Ticket opens a window to provide feedback directly to the development team.
The GUI widget allows users to configure the TrueNAS SCALE web interface address. Click Settings to open the GUI Settings configuration screen.
The system uses a self-signed certificate to enable encrypted web interface connections. To change the default certificate, select a different certificate that was created or imported in the Certificates section from the GUI SSL Certificate dropdown list.
To set the WebUI IP address, if using IPv4 addresses, select a recent IP address from the Web Interface IPv4 Address dropdown list. This limits the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable. If using an IPv6 address, select a recent IP address from the Web Interface IPv6 Address dropdown list.
To allow configuring a non-standard port to access the GUI over HTTPS, enter a port number in the Web Interface HTTPS Port field.
Select the cryptographic protocols for securing client/server connections from the HTTPS Protocols dropdown list. Select the Transport Layer Security (TLS) versions TrueNAS SCALE can use for connection security.
To redirect HTTP connections to HTTPS, select Web Interface HTTP -> HTTPS Redirect. A GUI SSL Certificate is required for HTTPS. Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year. A warning displays when setting this function.
Special consideration should be given when TrueNAS is installed in a VM, as VMs are not configured to use HTTPS. Enabling HTTPS redirect can interfere with the accessibility of some apps. To determine if HTTPS redirect is active, go to System Settings > General > GUI > Settings and locate the Web Interface HTTP -> HTTPS Redirect checkbox. To disable HTTPS redirects, clear this option and click Save, then clear the browser cache before attempting to connect to the app again.
To send failed HTTP request data which can include client and server IP addresses, failed method call tracebacks, and middleware log file contents to iXsystems, select Crash Reporting.
To send anonymous usage statistics to iXsystems, select the Usage Collection option.
To display console messages in real time at the bottom of the browser, select the Show Console Messages option.
To change the WebUI on-screen language and set the keyboard to work with the selected language, click Settings on the System Settings > General > Localization widget. The Localization Settings configuration screen opens.
Select the language from the Language dropdown list, and then the keyboard layout in Console Keyboard Map.
Enter the time zone in Timezone and then select the local date and time formats to use.
Click Save.
The NTP Servers widget allows users to configure Network Time Protocol (NTP) servers. These sync the local system time with an accurate external reference. By default, new installations use several existing NTP servers. TrueNAS SCALE supports adding custom NTP servers.
The Email widget displays information about current system mail settings. When configured, an automatic script sends a nightly email to the administrator account containing important information such as the health of the disks.
To configure the system email send method, click Settings to open the Email Options screen. Select either SMTP or GMail OAuth to display the relevant configuration settings.
For users with a valid TrueNAS license, click Add License. Copy your license into the box and click Save.
You are prompted to reload the page for the license to take effect, click RELOAD NOW. Log back into the WebUI where the End User License Agreement (EULA) displays. Read it thoroughly and completely. After you finish, click I AGREE. The system information updates to reflect the licensing specifics for the system.
Silver and Gold level Support customers can also enable Proactive Support on their hardware to automatically notify iXsystems if an issue occurs. To find more details about the different Warranty and Service Level Agreement (SLA) options available, see iXsystems Support.
When the system is ready to be in production, update the status by selecting This is a production system and then click the Proceed button. This sends an email to iXsystems declaring that the system is in production.
While not required for declaring the system is in production, TrueNAS has the option to include an initial debug with the email that can assist support in the future.
Silver/Gold Coverage Customers can enable iXsystems Proactive Support. This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
To configure proactive support, click Get Support on the Support widget located on the System Settings > General screen. Select Proactive Support from the dropdown list.
Complete all available fields and select Enable iXsystems Proactive Support, then click Save.
An automatic script sends a nightly email to the administrator account containing important information such as the health of the disks. Configure the system to send these emails to the administrator remote email account for fast awareness and resolution of any critical issues.
Scrub Task issues and S.M.A.R.T. reports are mailed separately to the address configured in those services.
Configure the email address for the admin user as part of your initial system setup or using the procedure below. You can also configure email addresses for additional user accounts as needed.
Before configuring anything else, set the local administrator email address.
Add a new user as an administrative or non-administrative account and set up email for that user. Follow the directions in Configuring the Admin User Email Address above for an existing user or see Managing Users for a new user.
After setting up the admin email address, you need to set up the send method for email service.
There are two ways to access email configuration options. Go to the Systems Settings > General screen and locate the Email widget to view current configuration or click the Alerts icon in the top right of the UI, then click the gear icon, and select Email to open the General settings screen. Click Settings on the Email Widget to open the Email Options configuration screen.
Send Mail Method shows two different options:
The configuration options change based on the selected method.
After configuring the send method, click Send Test Mail to verify the configured email settings are working. If the test email fails, verify that the Email field is correctly configured for the admin user. Return to Credentials > Users to edit the admin user.
Save stores the email configuration and closes the Email Options screen.
To set up SMTP service for the system email send method, you need the outgoing mail server and port number for the email address.
To set up the system email using Gmail OAuth, you need to log in to your Gmail account through the TrueNAS SCALE web UI.
If the system email send method is configured, the admin email receives a system health email every night/morning.
You can also add/configure the Email Alert Service to send timely warnings when a system alert hits a warning level that is specified in Alert Settings.
From the Alerts
panel, select the icon and then Alert Settings, or go to System Settings > Alert Settings.Locate Email under Alert Services, select the
icon, and then click Edit to open the Edit Alert Service screen.Add the system email address in the Email Address field.
Use the Level dropdown to adjust the email warning threshold or accept the default Warning.
Use Send Test Alert to generate a test alert and confirm the email address and alert service works.
Advanced Settings provides configuration options for the console, syslog, kernel, sysctl, replication, cron jobs, init/shutdown scripts, system dataset pool, isolated GPU device(s), self-encrypting drives, system access sessions, allowed IP addresses, audit logging, and global two-factor authentication.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
This article provides information on sysctl, system dataset pool, setting the maximum number of simultaneous replication tasks the system can perform, and managing sessions.
Use the System Settings > Advanced screen Allowed IP Addresses configuration screen to restrict access to the TrueNAS SCALE web UI and API.
Entering an IP address limits access to the system to only the address(es) entered here. To allow unrestricted access to all IP addresses, leave this list empty.
Use Add on the Sysctl widget to add a tunable that configures a kernel module parameter at runtime.
The Add Sysctl or Edit Sysctl configuration screens display the settings.
Enter the sysctl variable name in Variable. Sysctl tunables configure kernel module parameters while the system runs and generally take effect immediately.
Enter a sysctl value for the loader in Value.
Enter a description and then select Enabled. To disable but not delete the variable, clear the Enabled checkbox.
Click Save.
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.
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.
Swap Size lets users enter an amount (in GiB) of hard disk space to use as a substitute for RAM when the system fully utilizes the actual RAM.
By default, the system creates all data disks with the specified swap amount. Changing the value does not affect the amount of swap on existing disks, only disks added after the change. Swap size does not affect log or cache devices.
The Replication widget displays the number of replication tasks that can execute simultaneously configured on the system. It allows users to adjust the maximum number of replication tasks the system can execute simultaneously.
Click Configure to open the Replication configuration screen.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
The Access widget displays a list of all active sessions, including the user who initiated the session and what time it started. It also displays the Token Lifetime setting for your current session. It allows administrators to manage other active sessions and to configure the token lifetime for their account.
The Terminate Other Sessions button ends all sessions except for the one you are currently using. You can also end individual sessions by clicking 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.
Token Lifetime displays the configured token duration for the current session (default five minutes). TrueNAS SCALE logs out user sessions that are inactive for longer than that configured token setting for the user. New activity resets the token counter.
If the configured token lifetime is exceeded, TrueNAS SCALE displays a Logout dialog with the exceeded ticket lifetime value and the time that the session is scheduled to terminate.
Click Extend Session to reset the token counter. If the button is not clicked, the TrueNAS SCALE terminates the session automatically and returns to the log in screen.
Click Configure to open the Token Settings screen and configure Token Lifetime for the current account.
Select a value that fits user needs and security requirements. Enter the value in seconds.
The default lifetime setting is 300 seconds, or five minutes.
The minimum value allowed is 30 seconds.
The maximum is 2147482 seconds, or 20 hours, 31 minutes, and 22 seconds.
Click Save.
Cron jobs allow users to configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Cron Jobs widget on the System > Advanced screen displays No Cron Jobs configured until you add a cron job, and then it displays information on cron job(s) configured on the system.
Click Add to open the Add Cron Job configuration screen and create a new cron job. If you want to modify an existing cron job, click anywhere on the item to open the Edit Cron Jobs configuration screen populated with the settings for that cron job. The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Enter a description for the cron job.
Next, enter the full path to the command or script to run in Command. For example, for a command string to create a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt
.
Select a user account to run the command from the Run As User dropdown list. The user must have permissions allowing them to run the command or script.
Select a schedule preset or choose Custom to open the advanced scheduler. An in-progress cron task postpones any later scheduled instances of the task until the one already running completes.
If you want to hide standard output (stdout) from the command, select Hide Standard Output. If left cleared, TrueNAS emails any standard output to the user account cron that ran the command.
To hide error output (stderr) from the command, select Hide Standard Error. If left cleared, TrueNAS emails any error output to the user account cron that ran the command.
Select Enabled to enable this cron job. Leave this checkbox cleared to disable the cron job without deleting it.
Click Save.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Console widget on the System Setting > Advanced screen displays current console settings for TrueNAS.
Click Configure to open the Console configuration screen. The Console configuration settings determine how the Console setup menu displays, the serial port it uses and the speed of the port, and the banner users see when it is accessed.
To display the console without being prompted to enter a password, select Show Text Console without Password Prompt. Leave it clear to add a login prompt to the system before showing the console menu.
Select Enable Serial Console to enable the serial console but do not select this if the serial port is disabled.
Enter the serial console port address in Serial Port and set the speed (in bits per second) from the Serial Speed dropdown list. Options are 9600, 19200, 38400, 57600 or 115200.
Finally, enter the message you want to display when a user logs in with SSH in MOTD Banner.
Click Save
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
By default, TrueNAS writes system logs to the system boot device. The Syslog widget on the System > Advanced screen allows users determine how and when the system sends log messages to a connected syslog server. The Syslog widget displays the existing system logging settings.
Before configuring your syslog server to use TLS as the Syslog Transport method, first make sure you add a certificate and certificate authority (CA) to the TrueNAS system. Go to Credentials > Certificates and use the Certificate Authority (CA) and Certificates widgets to verify you have the required certificates or to add them.
Click Configure to open the Syslog configuration screen. The Syslog configuration screen settings specify the logging level the system uses to record system events, the syslog server DNS host name or IP, the transport protocol it uses, and if using TLS, the certificate and certificate authority (CA) for that server, and finally if it uses the system dataset to store the logs.
Enter the remote syslog server DNS host name or IP address in Syslog Server. To use non-standard port numbers like mysyslogserver:1928, add a colon and the port number to the host name. Log entries are written to local logs and sent to the remote syslog server.
Enter the transport protocol for the remote system log server connection in Syslog Transport. Selecting Transport Layer Security (TLS) displays the Syslog TLS Certificate and Syslog TSL Certificate Authority fields.
Next, select the transport protocol for the remote system log server TLS certificate from the Syslog TLS Certificate dropdown list, and select the TLS CA for the TLS server from the Syslog TLS Certificate Authority dropdown list.
Select Use FQDN for Logging to include the fully-qualified domain name (FQDN) in logs to precisely identify systems with similar host names.
Select the minimum log priority level to send to the remote syslog server from Syslog Level the dropdown list. The system only sends logs at or above this level.
Click Save.
The Init/Shutdown Scripts widget on the System > Advanced screen allows you to add scripts to run before or after initialization (start-up), or at shutdown. For example, creating a script to backup your system or run a systemd command before exiting and shutting down the system.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before creating and executing script tasks.
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, and then the widget lists the scripts configured on the system.
Click Add to open the Add Init/Shutdown Script configuration screen.
Enter a description and then select Command or Script from the Type dropdown list. Selecting Script displays additional options.
Enter the command string in Command, or if using a script, enter or use the browse to the path in Script. The script runs using dash(1).
Select the option from the When dropdown list for the time this command or script runs.
Enter the number of seconds after the script runs that the command should stop in Timeout.
Select Enable to enable the script. Leave clear to disable but not delete the script.
Click Save.
Click a script listed on the Init/Shutdown Scripts widget to open the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
You can change from a command to a script, and modify the script or command as needed.
To disable but not delete the command or script, clear the Enabled checkbox.
Click Save.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Self-Encrypting Drive(s) widget on the System > Advanced screen allows you set the user and global SED password in SCALE.
The Self-Encrypting Drive (SED) widget displays the ATA security user and password configured on the system.
Click Configure to open the Self-Encrypting Drive configuration screen. The Self-Encrypting Drive configuration screen allows users set the ATA security user and create a SED global password.
Select the user passed to camcontrol security -u to unlock SEDs from the ATA Security User dropdown list. Options are USER or MASTER.
Enter the global password to unlock SEDs in SED Password and in Confirm SED Password.
Click Save.
Systems with more than one graphics processing unit (GPU) installed can isolate additional GPU device(s) from the host operating system (OS) and allocate them for use by a virtual machine (VM). Isolated GPU devices are unavailable to the OS and for allocation to applications.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Isolated GPU Device(s) widget on the System > Advanced screen shows configured isolated GPU device(s).
To isolate a GPU, you must have at least two in your system; one available to the host system for system functions and the other available to isolate for use by a VM. One isolated GPU device can be used by a single VM. Isolated GPU cannot be allocated to applications.
To allocate an isolated GPU device, select it while creating or editing VM configuration. When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM and becomes unavailable for any other allocations.
Click Configure on the Isolated GPU Device(s) widget to open the Isolate GPU PCI Ids screen, where you can select a GPU device to isolate.
Select the GPU device(s) to isolate from the dropdown list.
Click Save.
Global Two-factor authentication (2FA) is great for increasing security.
TrueNAS offers global 2FA to ensure that entities cannot use a compromised administrator root password to access the administrator interface.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
To use 2FA, you need a mobile device with the current time and date, and an authenticator app installed. We recommend Google Authenticator. You can use other authenticator applications, but you must confirm the settings and QR codes generated in TrueNAS are compatible with your particular app before permanently activating 2FA.
Two-factor authentication is time-based and requires a correct system time setting. Ensure Network Time Protocol (NTP) is functional before enabling two-factor authentication is strongly recommended!
Unauthorized users cannot log in since they do not have the randomized six-digit code.
Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.
Internet access on the TrueNAS system is not required to use 2FA.
2FA requires an app to generate the 2FA code.
If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled). You can bypass or unlock 2FA using the CLI.
Set up a second 2FA device as a backup before proceeding.
Before you begin, download Google Authenticator to your mobile device.
Go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save.
If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.
TrueNAS takes you to the Two-Factor Authentication screen to finish 2FA setup.
When using Google Authenticator, set Interval to 30 or the authenticator code might not function when logging in.
Click Show QR and scan the QR code using Google Authenticator.
After scanning the code click CLOSE to close the dialog on the Two-Factor Authentication screen.
Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until Global 2FA is enabled. When Global 2FA is enabled, user accounts that have not configured 2FA settings yet are shown the Two-Factor Authentication screen on their next login to configure and enable 2FA authentication for that account.
Go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config. Clear the Enable Two-Factor Authentication Globally checkbox and click Save.
If the device with the 2FA app is not available, you can use the system CLI to bypass 2FA with administrative IPMI or by physically accessing the system.
To unlock 2FA in the SCALE CLI, enter:
auth two_factor update enabled=false
If you want to enable 2FA again, go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save. To change the system-generated Secret, go to Credentials > 2FA and click Renew 2FA Secret.
Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.
The login screen adds another field for the randomized authenticator code. If this field is not immediately visible, try refreshing the browser.
Enter the code from the mobile device (without the space) in the login window and use the root username and password.
If you wait too long, a new number code displays in Google Authenticator, so you can retry.
Confirm that you set Enable Two-Factor Auth for SSH in System Settings > Advanced > Global Two Factor Authentication.
Go to System Settings > Services and edit the SSH service.
a. Set Log in as Admin with Password, then click Save.
b. Click the SSH toggle and wait for the service status to show that it is running.
Open the Google Authentication app on your mobile device.
Open a terminal (such as Windows Shell) and SSH into the system using either the host name or IP address, the administrator account user name and password, and the 2FA code.
Developer mode is for developers only. Users that enable this functionality will not receive support on any issues submitted to iXsystems.
Only enable when you are comfortable with debugging and resolving all issues encountered on the system. Never enable on a system that has production storage and workloads.
TrueNAS is an Open Source Storage appliance, not a standard Linux operating system (OS) that allows customization of the OS environment.
By default, the root/boot filesystem and tools such as apt
are disabled to prevent accidental misconfiguration that renders the system inoperable or puts stored data at risk.
However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.
Do not make system changes using the TrueNAS UI web shell. Using package management tools in the web shell can result in middleware changes that render the system inaccessible.
Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.
To enable developer mode, log into the system as the root account and access the Linux shell.
Run the install-dev-tools
command.
Running install-dev-tools
removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS.
These changes do not persist across updates and install-dev-tools
must be re-run after every system update.
System Settings > Boot contains options for monitoring and managing the ZFS pool and devices that store the TrueNAS operating system.
The Stats/Settings option displays current system statistics and provides the option to change the scrub interval, or how often the system runs a data integrity check on the operating system device.
Go to System Settings > Boot screen and click Stats/Settings. The Stats/Settings window displays statistics for the operating system device: Boot pool Condition as ONLINE or OFFLINE, Size in GiB and the space in use in Used, and Last Scrub Run with the date and time of the scrub. By default, the operating system device is scrubbed every 7 days.
To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.
From the System Settings > Boot screen, click the Boot Pool Status button to open the Boot Pool Status screen. This screen shows the boot-pool and expands to show the devices that are allocated to that pool. Read, write, or checksum errors are also shown for the pool.
A manual data integrity check (scrub) of the operating system device can be initiated at any time.
On the System Settings > Boot screen, and click Scrub Boot Pool to open the Scrub dialog.
Click Confirm and then Start Scrub.
TrueNAS supports a ZFS feature known as boot environments. These are snapshot clones of the TrueNAS boot-pool install location that TrueNAS boots into. Only one boot environment is used for booting at a time.
A boot environment allows rebooting into a specific point in time and greatly simplifies recovering from system misconfigurations or other potential system failures. With multiple boot environments, the process of updating the operating system becomes a low-risk operation.
For example, the TrueNAS update process automatically creates a snapshot of the current boot environment and adds it to the boot menu before applying the update. If anything goes wrong during the update, the system administrator can activate the snapshot of the pre-update environment and reboot TrueNAS to restore system functionality.
Boot environments do not preserve or restore the state of any attached storage pools or apps, only the system boot-pool. Storage backups must be handled through the ZFS snapshot feature or other backup options. TrueNAS applications also use separate upgrade and container image management methods to provide app update and rollback features.
To view the list of boot environments on the system, go to System Settings > Boot. Each boot environment entry contains this information:
To access more options for a boot environment, click to display the list of options:
System Settings > 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.
Documented services related to data sharing or automated tasks are in their respective Shares and Tasks articles.
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.
Options for configuring FTP, SSH, and TFTP are in System Settings > Services. Click the edit to configure the related service.
FTP requires a new dataset and a local user account.
Go to Storage to add a new dataset to use as storage for files.
Next, add a new user. Go to Credentials > Local Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory. You can do this for every user or create a global account for FTP (for example, OurOrgFTPaccnt).
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields. Select Apply User and Apply Group. Select the Read, Write, and Execute for User, Group, and Other you want to apply. Click Save.
To configure FTP, go to System Settings > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
To confine FTP sessions to the home directory of a local user, select both chroot and Allow Local User Login.
Do not allow anonymous or root access unless it is necessary. Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Click Save and then start the FTP service.
FTP requires a new dataset and a local user account.
Go to Storage and add a new [dataset]](/scale/scaletutorials/datasets/datasetsscale/).
Next, add a new user. Go to Credentials > Local Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory. Then, add ftp to the Auxiliary Groups field and click Save.
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields. Enable Apply User and Apply Group. Select the Read, Write, and Execute for User, Group, and Other you want to apply, then click Save.
Go to System Settings > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
To confine FTP sessions to the home directory of a local user, select chroot.
Do not allow anonymous or root access unless it is necessary. Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Click Save, then start the FTP service.
Use a browser or FTP client to connect to the TrueNAS FTP share. The images below use FileZilla, which is free.
The user name and password are those of the local user account on the TrueNAS system. The default directory is the same as the user home directory. After connecting, you can create directories and upload or download files.
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
You can access it from System Settings > Services screen. Locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
We recommend using the default NFS settings unless you require specific settings.
Select the IP address from the Bind IP Addresses dropdown list if you want to use a specific static IP address, or leave this field blank for NFS to listen to all available addresses.
By default, TrueNAS dynamically calculates the number of threads the kernel NFS server uses. However, if you want to manually enter an optimal number of threads the kernel NFS server uses, clear Calculate number of threads dynamically and enter the number of threads you want in the Specify number of threads manually field.
If using NFSv4, select NFSv4 from Enabled Protocols. NFSv3 ownership model for NFSv4 clears, allowing you to enable or leave it clear.
If you want to force NFS shares to fail if the Kerberos ticket is unavailable, select Require Kerberos for NFSv4.
Next, enter a port to bind to in the field that applies:
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Only select Allow non-root mount if the NFS client requires it to allow serving non-root mount requests.
Select Support > 16 groups when a user is a member of more than 16 groups. This setting assumes group membership is configured correctly on the NFS server.
Click Save.
Start the NFS service.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
There is a special consideration when installing TrueNAS in a Virtual Machine (VM), as S.M.A.R.T services monitor actual physical devices, which are abstracted in a VM. After the installation of TrueNAS completes on the VM, go to System Settings > Services > and click the blue toggle button on the S.M.A.R.T. service to stop the service from running. Clear the Start Automatically checkbox so the service does not automatically start when the system reboots.
Use the Services > S.M.A.R.T. screen to configure when S.M.A.R.T. tests run and when to trigger alert warnings and send emails.
Click the edit Configure icon to open the screen.
Enter the time in minutes smartd to wake up and check if any tests are configured to run in Check Interval.
Select the Power Mode from the dropdown list. Choices include Never, Sleep, Standby, and Idle. TrueNAS only performs tests when you select Never.
Set the temperatures that trigger alerts in Difference, Informational and Critical.
Click Save after changing any settings.
Start the service.
The Services > SMB screen displays after going to the Shares screen, finding the Windows (SMB) Shares section, and clicking
+ Config Service. Alternatively, you can go to System Settings > Services and click the edit icon for the SMB service.The SMB Services screen displays setting options to configure TrueNAS SMB settings to fit your use case. In most cases, you can set the required fields and accept the rest of the setting defaults. If you have specific needs for your use case, click Advanced Options to display more settings.
Enter the name of the TrueNAS host system if not the default displayed in NetBIOS Name. This name is limited to 15 characters and cannot be the Workgroup name.
Enter any alias name or names that do not exceed 15 characters in the NetBIOS Alias field. Separate each alias name with a space between them.
Enter a name that matches the Windows workgroup name in Workgroup. TrueNAS detects and sets the correct workgroup from these services when unconfigured with enabled Active Directory or LDAP active.
If using SMB1 clients, select Enable SMB1 support to allow legacy SMB1 clients to connect to the server. Note: SMB1 is deprecated. We advise you to upgrade clients to operating system versions that support modern SMB protocol versions.
If you plan to use the insecure and vulnerable NTLMv1 encryption, select NTLMv1 Auth to allow smbd attempts to authenticate users. This setting enables backward compatibility with older versions of Windows, but we don’t recommend it. Do not use on untrusted networks.
Enter any notes about the service configuration in Description
For more advanced settings, see SMB Services Screen.
Use Auxiliary Parameters to enter additional smb.conf options, or to log more details when a client attempts to authenticate to the share, add log level = 1, auth_audit:5
. Refer to the Samba Guide for more information on these settings.
Click Save.
Start the SMB service.
SNMP (Simple Network Management Protocol) monitors network-attached devices for conditions that warrant administrative attention. TrueNAS uses Net-SNMP to provide SNMP. To configure SNMP, go to System Settings > Services page, find SNMP, and click the edit.
See SNMP Service Screen for setting information.
Port UDP 161 listens for SNMP requests when starting the SNMP service.
Click to view or download a static copy of the SCALE 24.10 (Electric Eel) MIB file.
To download an MIB from your TrueNAS system, you can enable SSH and use a file transfer command like scp
.
When using SSH, make sure to validate the user logging in has SSH login permissions enabled and the SSH service is active and using a known port (22 is default).
Management Information Base (MIB) files are located in
Example (replace mytruenas.example.com with your system IP address or hostname):
PS C:\Users\ixuser> scp admin@mytruenas.example.com:/usr/local/share/snmp/mibs/* .\Downloads\
admin@mytruenas.example.com's password:
TRUENAS-MIB.txt 100% 11KB 112.0KB/s 00:00
PS C:\Users\ixuser>
The SSH service lets users connect to TrueNAS with the Secure SHell Transport Layer Protocol. When using TrueNAS as an SSH server, the users in the network must use SSH client software to transfer files with SSH.
Allowing external connections to TrueNAS is a security vulnerability! Do not enable SSH unless you require external connections. See Security Recommendations for more security considerations when using SSH.
To configure SSH go to System Settings > Services, find SSH, and click edit to open the basic settings General Options configuration screen.
Use the Password Login Groups and Allow Password Authentication settings to allow specific TrueNAS account groups the ability to use password authentication for SSH logins.
Click Save. Select Start Automatically and enable the SSH service.
If your configuration requires more advanced settings, click Advanced Settings. The basic options continue to display above the Advanced Settings screen. Configure the options as needed to match your network environment.
These Auxiliary Parameters can be useful when troubleshooting SSH connectivity issues:
ClientAliveInterval
if SSH connections tend to drop.MaxStartups
value (10 is default) when you need more concurrent SSH connections.Remember to enable the SSH service in System Settings > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
SFTP (SSH File Transfer Protocol) is available by enabling SSH remote access to the TrueNAS system. SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.
Go to System Settings > Services, find the SSH entry, and click the edit to open the Services > SSH basic settings configuration screen.
Select Allow Password Authentication.
Go to Credentials > Local Users. Click anywhere on the row of the user you want to access SSH to expand the user entry, then click Edit to open the Edit User configuration screen. Make sure that SSH password login enabled is selected. See Managing Users for more information.
SSH with root is a security vulnerability. It allows users to fully control the NAS remotely with a terminal instead of providing SFTP transfer access.
Choose a non-root administrative user to allow SSH access.
Review the remaining options and configure them according to your environment or security needs.
Remember to enable the SSH service in System Settings > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
Open an FTP client (like FileZilla) or command line. This article shows using FileZilla as an example.
Using FileZilla, enter SFTP://{TrueNAS IP} {username} {password} {port 22}
. Where {TrueNAS IP} is the IP address for your TrueNAS system, {username} is the administrator login user name, and {password} is the adminstrator password, and {port 22} to connect.
SFTP does not offer chroot locking. While chroot is not 100% secure, lacking chroot lets users move up to the root directory and view internal system information. If this level of access is a concern, FTP with TLS might be the more secure choice.
An Uninterruptible Power Supply (UPS) is a power backup system that ensures continuous electricity during outages, preventing downtime and damage.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support. For supported device and driver information, see their hardware compatibility list.
Report UPS bugs and feature requests to the NUT project.
Connect the TrueNAS system to the UPS device. To configure the UPS service, go to System settings > Services, finding UPS, and click edit.
See UPS Service Screen for details on the UPS service settings.
TrueNAS EnterpriseTrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
Some UPS models are unresponsive with the default polling frequency (default is two seconds).
TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.
If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10
.
The SCALE Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information.
Warning! The supported mechanisms for making configuration changes are the TrueNAS WebUI, CLI, and API exclusively. All other are not supported and result in undefined behavior that can result in system failure!
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.
This section provides keyboard navigation shortcuts you can use in Shell.
zsh is the default shell, but you can change this by going to Credentials > Local Users. Select the admin or other user to expand it. Click Edit to open the Edit User screen. Scroll down to Shell and select a different option from the dropdown list. Most Linux command-line utilities are available in the Shell. Click Save.
Admin users can set the Shell to default to the TrueNAS CLI by selecting TrueNAS CLI in Shell on the Edit User screen. See SCALE CLI Reference Guide for more information on using the TrueNAS CLI. To change the Shell to default to the Console Setup Menu, select TrueNAS Console in Shell on the Edit User screen.
Clicking other SCALE UI menus options closes the shell session and stops commands running in the Shell screen.
Tmux allows you to detach sessions in Shell and then reattach them later. Commands continue to run in a detached session.
The new SCALE command-line interface (CLI) lets you directly configure SCALE features using namespaces and commands based on the SCALE API.
TrueNAS CLI is still in active development. We are not accepting bug reports or feature requests at this time.
See SCALE CLI Reference Guide for more information on using the TrueNAS CLI.
We intend the CLI to be an alternative method for configuring TrueNAS features. Because of the variety of available features and configurations, we include CLI-specific instructions in their respective UI documentation sections.
TrueNAS SCALE auditing and logs provide a trail of all actions performed by a session, user, or service (SMB, middleware).
The audit function backends are both the syslog and the Samba debug library. Syslog sends audit messages via explicit syslog call with configurable priority (WARNING is the default) and facility (for example, USER). The default is syslog sent audit messages. Debug sends audit messages from the Samba debug library and these messages have a configurable severity (WARNING, NOTICE, or INFO).
The System Settings > Audit screen lists all session, user, or SMB events. Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).
SCALE includes a manual page with more information on the VFS auditing functions.
Administrative users can enter
man vfs_truenas_audit
in a SCALE command prompt to view the embedded manual page.
Events are organized by session and user, and SMB auditing.
Session and user auditing events
Audit records contain information that establishes:
Each audit message is a single JSON file containing mandatory fields. It can also include additional optional records. Message size is limited to not exceed 1024 bytes for maximum portability with different syslog implementations.
Use the Export to CSV button on an audit screen to download audit logs in a format readable in a spreadsheet program. Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file. The JSON object for an audit message contains the version information, the service which is the name of the SMB share, a session ID and the tree connection (tcon_id).
Authentication and other events are captured by the TrueNAS audit logging functions. The TrueNAS SCALE auditing logs event data varies based on the type of event tracked.
Users have access to audit information from three locations in the SCALE UI:
Click Audit Logging on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user.
Click Audit Logging on the SMB row on the Services screen to open the Audit log screen with the Search field filter added to show only SMB events.
The main System Settings > Audit screen shows all system events such as authentication and SMB events.
The audit screen includes basic and advanced search options. Click Switch to Basic to change to the basic search function or click Switch to Advanced to show the advanced search operators.
You can enter any filters in the basic Search field to show events matching the entry.
To enter advanced search parameters, use the format displayed in the field, for example, Service = “SMB” AND Event = “CLOSE” to show closed SMB events. Event types are listed in Auditing Event Types.
Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering. Parentheses define query priority. Clicking the advanced Search field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.
For example, to search for any SMB connect or close event from the user smbuser or any non-authentication SMB events, enter (Service = "SMB" AND Event in ("Connect", "Close") AND User in ("smbuser")) OR (Event != "Authentication" AND Service = "SMB")
.
The advanced search automatically checks syntax and shows done when the syntax is valid and warning for invalid syntax.
Click on a row to show details of that event in the Metadata and Event Data widgets.
Export as CSV sends the event log data to a csv file you can open in a spreadsheet program (i.e., MS Excel, Google Sheets, etc.) or other data management app that accept CSV files.
The assignment (Copy to Clipboard) icon shows two options, Copy Text and Copy Json. Copy Text copies the event to a text file. Copy Json copies the event to a JSON object.
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
Use the Watch List and Ignore List functions to add audit logging groups to include or exclude. Click in Watch List to see a list of user groups on the system. Click on a group to add it to the list and record events generated by user accounts that are members of the group. Leave Watch List blank to include all groups, otherwise auditing is restricted to only the groups added.
Click in Ignore List to see a list of user groups on the system.. Click on a group to add it to the list and explicitly avoid recording any events generated by user accounts that are members of this group.
The Watch List takes precedence over the Ignore List when using both lists.
Click Save.
To configure session auditing settings, go to System Settings > Advanced, then click Configure on the Audit widget.