Back to Docs Hub
This guide collects various how-tos for both simple and complex tasks using primarily the TrueNAS web interface. Tutorials are organized parallel to the TrueNAS web interface structure and grouped by topic. Tutorials are living articles and continually updated with new content or additional in-depth tutorials that guide in unlocking the full potential of TrueNAS.
To display all tutorials in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
If you are interested in writing a TrueNAS tutorial, see the Contributing section for some guidance!
TrueNAS SCALE allows users to synchronize SCALE and system server time when they get out of sync. This function does not correct time differences over 30 days out of alignment.
The System Information widget on the Dashboard displays a message and provides an icon button that executes the time-synchronization operation only when SCALE detects a discrepancy between SCALE and system server time.
Click the Synchronize Time
icon button to initiate the time-synchronization operation.The top toolbar in the web interface typically shows status icons along with a few small menus for system configuration. The tutorials in this section guide with using some of these menus.
The API Keys option on the top right toolbar Settings (user icon) dropdown menu displays the API Keys screen. This screen displays a list of API keys added to your TrueNAS.
Click Add to display a dialog window that lets users add a new API key. API keys identify outside resources and applications without a principal.
Type a descriptive name and click Add. The system displays a confirmation dialog and adds a new API key to the list.
TrueNAS SCALE supports creating API keys in the Shell with an allow list of permissions for the keys.
Go to System Settings > Shell and enter midclt call api_key.create '{"name":"KEYNAME", "allowlist": [{"method": "HTTPMETHOD", "resource": "METHODNAME"}]}'
using your desired allowlist
parameters.
After you enter the command, the Shell displays the API Key in the output.
Select the icon for any API key on the list to display options to manage that API key. Options are Edit or Delete.
Select the Reset to remove the existing API key and generate a new random key. The dialog displays the new key and the Copy to Clipboard option to copy the key to the clipboard.
Always back up and secure keys. The key string displays only one time, at creation!
To delete, select Confirm on the delete dialog to activate the Delete button.
Click API Docs to access API documentation for your system.
An automatic script sends a nightly email to the administrator root account containing important information such as the health of the disks. Alert events are also emailed to the root user account. 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 system root user as part of your initial system setup. You can also configure email addresses for additional user accounts as needed.
Before configuring anything else, set the local administrator account email address.
Just as with the root user, you can add new users as an admin or non-administrative account, and set up email for that user. Follow the directions in Configuring the Root User Email Address for an existing user or in Setting Up User Accounts to add email service for a new user.
After setting up the root user email address you need to set up the send method for email service.
Click the Alerts icon in the top right of the UI, then click the gear icon and select Email to open the Email configuration screen.
The Send Mail Method shows two different options:
The Email screen configuration options change based on the selected option.
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 root user Email field is correctly configured for the root user. Return to Credentials > Users to select the admin user.
The Email screen displays with GMail OAuth preselected as the default send method.
To setup up SMTP service for the system email send method you need the outgoing mail server and port number for the email you entered.
The system email account is sent a system health email every night/morning, if it is configured. You can also add/configure the Email Alert Service to send timely email warnings, when the system hits a specific state that is listed in Alert Settings, to the email specified in the alert service.
From the Alerts panel, select the
icon and then Alert Services.Change the Type field to Email and then populate the Add Alert Service form.
Add the system email address in the Email Address field.
Use Send Test Alert to generate a test alert and confirm the email address and alert service works.
TrueNAS Enterprise
This is SCALE Enterprise specific content.
If you need to power down your SCALE Enterprise system, this is the procedure:
While logged into the SCALE Web UI using the virtual IP (VIP), click the power button in the top right corner of the screen.
Select Shut Down from the dropdown list.
This shuts down the active controller.
The system fails over to the standby controller.
When the SCALE Web UI login screen displays, log back in to the system. This logs you in to the standby controller.
Click the power button in the top right corner of the screen.
Select Shut Down from the dropdown list.
This shuts down the standby controller.
The Network menu option has several screens that enable configuring network interfaces and general system-level network settings. The tutorials in this section guide with the various screens and configuration forms contained within this menu item.
TrueNAS SCALE supports configuring different types of network interfaces as part of the various backup, sharing, and virtualization features in the software. The tutorials in this section guide with each of these types of configurations.
You can add new or edit existing network interfaces on the Network screen.
You can only use DHCP to provide the IP address for one network interface and this is most likely for your primary network interface configured during the installation process.
To add another network interface leave the DHCP checkbox clear and click the Add button near the bottom of the Add Interface configuration panel so you can enter a static IP address for the interface.
Click Add on the Interfaces widget to display the Add Interface panel.
You must specify the type of interface you want to create. The Type field provides three options: Bridge, Link Aggregation or LAGG, and VLAN or virtual LAN. You cannot edit the interface type after you click Save.
Each interface type displays new fields on the Add Interface panel. Links with more information on adding these specific types of interfaces are at the bottom of this article.
Click on an existing interface in the Interfaces widget to display the Edit Interface configuration panel. The fields on the Edit Interface and Add Interface configuration panel fields are identical except for the Type and Name fields. Both of these fields are editable only on the Add Interface panel before you click Save. The Type field only appears on the Add Interface configuration panel.
Because you cannot edit the interface type or name after you click Save, if you make a mistake with either field you can only delete that interface and create a new one with the desired type.
If you want to change from DHCP to a static IP, you must also add the new default gateway and DNS nameservers that work with the new IP address. See Setting Up a Static IP for more information.
If you delete the primary network interface you can lose your TrueNAS connection and the ability to communicate with the TrueNAS through the web interface!
You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Click the delete icon next to the interface. The delete interface confirmation dialog displays.
Do not delete the primary network interface!
If you delete the primary network interface you lose your TrueNAS connection and the ability to communicate with the TrueNAS through the web interface! You might need command line knowledge or physical access to the TrueNAS system to fix misconfigured network settings.
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet.
You can combine multiple interfaces with Link Aggregation (LAGG) or a Network Bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
If you want to configure alias IPs for access to internal portions of the network, from the Network screen:
Click on the interface to open the Edit Interface screen for the selected interface.
Clear the checkmark for DHCP to show the Aliases fields, and then click Add for each alias you want to add to this interface.
Enter the IP address and CIDR values for the alias(es) you want to add.
Select DHCP to control the primary IP for the interface.
Click Save.
In general, a bridge refers to various methods of combining (aggregating) multiple network connections into a single aggregate network. TrueNAS uses bridge(4) as the kernel bridge driver. Bridge(8) is a command for configuring the kernal bridge in Linux. While the examples focus on the deprecated brctl(8) from the bridge-utilities package, we use ip(8) and bridge(8) from iproute2 instead. Refer to the FAQ section that covers bridging topics more generally.
To set up a bridge interface, from the Network screen:
Select Bridge from the Type dropdown list. You cannot change the Type field value after you click Save.
Enter a name for the interface. Use the format bondX, vlanX, or brX where X is a number representing a non-parent interface. Read-only when editing an interface. You cannot change the Name of the interface after you click Save.
(Optional but recommended) Enter any notes or reminders about this particular bridge in the Description field.
Select the interfaces on the Bridge Members dropdown list.
Next to Aliases click Add to enter the IP address for this bridge interface. (Optional) click Add to display an additional IP address field for each additional IP address you want to add.
In general, a link aggregation (LAGG) is a method of combining (aggregating) multiple network connections in parallel to provide additional bandwidth or redundancy for critical networking situations. TrueNAS uses lagg(4) to manage LAGGs.
To set up a LAGG, from the Network screen:
Click Add in the Interfaces widget. The Add Interface configuration screen displays.
Select Link Aggregation from the Type dropdown list. You cannot change the Type field value after you click Apply.
Enter a name for the interface using the format bondX, where X is a number representing a non-parent interface. You cannot change the Name of the interface after you click Apply.
(Optional but recommended) Enter any notes or reminders about this particular LAGG interface in the Description field.
Select the Link Aggregation Settings for this interface.
(Optional) Click Add to enter another IP address if desired for this LAGG interface. Click Add to display an IP address field for each IP address you want to add.
Click Save when finished.
A virtual LAN (VLAN) is a partitioned and isolated domain in a computer network at the data link layer (OSI layer 2). Click here for more information on VLANs. TrueNAS uses vlan(4) to manage VLANs.
Before you begin, make sure you have an Ethernet card connected to a switch port and already configured for your VLAN. Also that you have preconfigured the VLAN tag in the switched network.
To set up a VLAN interface, from the Network screen:
Click Add in the Interfaces widget. The Add Interface configuration screen displays.
Select VLAN from the Type dropdown list. You cannot change the Type field value after you click Apply.
Enter a name for the interface using the format vlanX where X is a number representing a non-parent interface. You cannot change the Name of the interface after you click Apply.
(Optional but recommended) Enter any notes or reminders about this particular VLAN in the Description field.
Select the interface in the Parent Interface dropdown list. This is typically an Ethernet card connected to a switch port already configured for the VLAN.
Enter the numeric tag for the interface in the Vlan Tag field. This is typically preconfigured in the switched network.
Select the VLAN Class of Service from the Priority Code Point dropdown list.
(Optional) Click Add to enter another IP address if desired for this bridge interface. Click Add to display an IP address field for each IP address you want to add.
Click Apply when finished.
This article provides instructions on setting up a network interface with a static IP address or changing the main interface from a DHCP-assigned to a manually-entered static IP address. You must know the DNS name server and default gateway addresses for your IP address.
Disruptive Change!
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
Command line knowledge and physical access to the TrueNAS system are often required to fix misconfigured network settings.
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet.
You can combine multiple interfaces with Link Aggregation (LAGG) or a Network Bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
By default, during installation, TrueNAS SCALE configures the primary network interface for Dynamic Host Configuration Protocol (DHCP) IP address management. However, some administrators might choose to assign a static IP address to the primary network interface. This choice may be made if TrueNAS is deployed on a system that does not allow DHCP for security, stability, or other reasons.
In all deployments, only one interface can be set up for DHCP, which is typically the primary network interface configured during the installation process. Any additional interfaces must be manually configured with one or more static IP addresses.
Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand to prevent lost communication with the server. You have only 60 seconds to change and test these network settings before they revert back to the current settings, for example back to DHCP assigned if moving from DHCP to a static IP.
Back up your system to preserve your data and system settings.
As a precaution, grab a screenshot of your current settings in the Global Configuration widget.
If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to this information to restore communication with your server. Lost communication could require you to reconfigure your network settings using the Console setup menu.
To view a demonstration of this procedure see the tutorial video in the Managing Global Configuration article.
To change an interface from using DHCP to a static IP address:
Click on the interface on the Interfaces widget to open the Edit Interface configuration screen and turn off DHCP.
Click Add in the Aliases section of the form and enter the new static IP. Select the CIDR number from the dropdown list.
Multiple interfaces cannot be members of the same subnet.
If an error displays or the Save button is inactive when setting the IP addresses on multiple interfaces, check the subnet and ensure the CIDR numbers differ.
Click Save.
The Network screen displays a new widget where you can select to either Test Changes or Revert Changes. If you have only one active network interface the system protects your connection to the interface by displaying the Test Changes dialog.
You have 60 seconds to test and save the change before the system discards the change and reverts back to the DHCP-configured IP address.
Check the name servers and default router information in the Global Information card. If the current settings are not on the same network, click Settings and modify each as needed to allow the static IP to communicate over the network.
Add the IP addresses for the DNS name servers in the Nameserver 1, Nameserver 2, and Nameserver 3 fields.
For home users, use 8.8.8.8 for a DNS name server address so you can communicate with external networks.
Add the IP address for the default gateway in the appropriate field. If the static network is IPv4 enter the gateway in IPv4 Default Gateway, if the static network is IPv6 use IPv6 Default Gateway.
Click Save.
Test the network changes. Click Test Changes. Select Confirm to activate Test Changes button.
The system attempts to connect to the new static IP address. If successful the Save Changes widget displays.
Click Save Changes to make the change to the static IP address permanent or click Revert Changes to discard changes and return to previous settings. The Save Changes confirmation dialog displays. Click SAVE. The system displays a final confirmation that the change is in effect.
Only one interface can use DHCP to assign the IP address and that is likely the primary network interface. If you do not have a existing network interface set to use DHCP you can convert an interface from static IP to DHCP.
To return to using DHCP:
Click Settings on the Global Configuration widget.
Clear the name server fields and the default gateway, and then click Save.
Click on the interface to display the Edit Interface screen.
Select DHCP.
Remove the static IP address from the IP Address field.
Click Apply.
Click Settings to display the Global Configuration configuration form and enter name server and default gateway addresses for the new DHCP-provided IP address.
Home users can enter 8.8.8.8 in the Nameserver 1 field.
Click Test Change. If the network settings are correct, the screen displays the Save Changes widget. Click Save Changes.
If the test network operation fails or the system times out, your system returns to the network settings before you attempted the change. Verify the name server and default gateway information to try again.
Use the Global Configuration Settings screen to add general network settings like the default gateway, DNS name servers to allow external communication.
To add new or change existing network interfaces see Managing Interfaces.
Disruptive Change
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.
From the Network > Global Configuration screen click Settings to display the Global Configuration configuration form and then:
Enter the host name for your TrueNAS in Hostname. For example, truenas.
Enter the system domain name in Domain. For example, mycompanyname.com.
Enter the IP addresses for your DNS name servers in the Nameserver 1, Nameserver 2, and/or Nameserver 3 fields. For home users, enter 8.8.8.8 in the Nameserver 1 field so your TrueNAS SCALE can communicate externally with the Internet.
Enter the IP address for your default gateway into the IPv4 Defalut Gateway if you are using IPv4 IP addresses. Enter the IP address in the IPv6 Default Gateway if you are using IPv6 addresses.
Select the Outbound Network radio button for outbound service capability.
Select Allow All to permit all TrueNAS SCALE services that need external communication to do that or select Deny All to prevent that external communication. Select Allow Specific and then use the dropdown list to pick the services you want to allow to communicate externally.
Click on as many services as you want to permit external communications for. Unchecked services cannot communication externally.
Click Save. The Global Configuration widget on the Network screen update to show the new settings.
Use the Global Configuration Settings screen to manage existing general network settings like the default gateway, DNS servers, set DHCP to assign the IP address or to set a static IP address, add IP address aliases, and set up services to allow external communication.
Disruptive Change
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.
Use the Global Configuration Outbound Network radio buttons to set up services to have external communication capability.
Services that use external communication are:
Select the Allow All to permit all the above services to externally communicate. This is the default setting.
Select the Deny All to prevent all the above services from externally communicating.
Select the Allow Specific to permit external communication for the services you specify. Selecting Allow Specific displays a dropdown list field with the list of services you can select from. Select all that apply. A checkmark displays next to each selected service. Selected services display in the field separated by a (,).
Click Save when finished.
Use Netwait to prevent starting all network services until the network is ready. Netwait sends a ping to each of the IP addresses you specify until one responds, and after receiving the response then services can start.
To set up Netwait, from the Network screen:
Click on Settings in the Global Configuration widget. The Global Configuration screen displays.
Select the Enable Netwait Feature checkbox. The Netwait IP List field displays.
Enter your list of IP addresses to ping. Press Enter after entering each IP address.
TrueNAS Enterprise
The instructions in the article only apply to SCALE Enterprise (HA) systems.
SCALE Enterprise (HA) systems use three static IP addresses for access to the UI:
Have your list of network addresses, host, and domain names ready so you can complete the network configuration without disruption or system timeouts. SCALE safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes. This is to prevent users from breaking their network connection in SCALE.
You must disable the failover before you can configure network settings!
To configure network settings:
Disable the failover service. Go to System Settings > Failover. Select Disable Failover and click Save.
Edit the Global Network settings to add or change the host and domain names, DNS name server and default gateway address. If enabled on your network, TrueNAS uses DHCP to assign global network addresses as well as the SCALE UI access IP address. If not enabled in your network, you must enter these values yourself. Review the Global Configuration settings to verify they match the information your network administrator provided.
Edit the primary network interface. Go to Network and click on the primary interface eno1 to open the Edit Interface screen for this interface.
a. Turn DHCP off. Select DHCP to clear the checkbox.
b. Add the failover settings. Select Critical, and then select 1 on the Failover Group dropdown list.
c. Add the virtual IP (VIP) and controller 2 IP. Click Add for Aliases to display the additional IP address fields.
Type the IP address for controller 1 into IP Address (This Controller) and select the CIDR number from the dropdown list.
Type the controller 2 IP address into IP Address (TrueNAS Controller 2) field.
Type the VIP address into Virtual IP Address (Failover Address) field.
Click Save
After editing the interface settings, the Test Changes button displays. You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Turn failover back on. Go to System Settings > Failover Select Disable Failover to clear the checkmark and turn failover back on, then click Save.
The system might reboot. Monitor the status of controller 2 and wait until the controller is back up and running, then click Sync To Peer. Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation. The controller reboots, and SCALE syncs controller 2 with controller 1, which adds the network settings and pool to controller 2.
TrueNAS does not have defined static routes by default but TrueNAS administrators can use the Static Routes widget on the Network screen to manually enter routes so a router can send packets to a destination network.
If you have a monitor and keyboard connected to the system you can use the Console setup menu to configure static routes during the installation process, but we recommend using the web UI for all configuration tasks.
If you need a static route to reach portions of the network, from the Network screen:
Click Add in the Static Routes widget. The Add Static Route configuration screen displays.
Enter a value in Destination. Enter the destination IP address and CIDR mask in the format A.B.C.D/E where E is the CIDR mask.
Enter the gateway IP address for the destination address in Gateway.
(Optional) Enter a brief description for this static route, such as the part of the network it reaches.
Click Save.
IPMI requires compatible hardware! Refer to your hardware documentation to determine if the TrueNAS web interface has IPMI options.
Many TrueNAS Storage Arrays have a built-in out-of-band management port that provides side-band management should the system become unavailable through the web interface.
Intelligent Platform Management Interface (IPMI) allows users to check the log, access the BIOS setup, and boot the system without physical access. IPMI also enables users to remotely access the system to assist with configuration or troubleshooting issues.
Some IPMI implementations require updates to work with newer versions of Java. See here for more information.
IPMI is configured in Network > IPMI. The IPMI configuration screen provides a shortcut to the most basic IPMI configuration.
We recommend setting a strong IPMI password. IPMI passwords must include at least one upper case letter, one lower case letter, one digit, and one special character (punctuation, e.g. ! # $ %, etc.). It must also be 8-16 characters long. Document your password in a secure way!
After saving the configuration, users can access the IPMI interface using a web browser and the IP address specified in Network > IPMI. The management interface prompts for login credentials. Refer to your IPMI device documentation to learn the default administrator account credentials.
After logging in to the management interface, users can change the default administrative user name and create additional IPMI users. IPMI utility appearance and available functions vary by hardware.
The SCALE Storage section has controls for pool, snapshot, and disk management. The storage section also has options for datasets, zvols, and permissions.
For guidance on clustering storage across multiple SCALE systems, see Clustering and Sharing SCALE Volumes with TrueCommand.
The Import Pool button lets users reconnect pools exported/disconnected from the current system or created on another system. This also reconnects pools after users reinstall or upgrade the TrueNAS system.
The Disks button lets users manage, wipe, and import storage disks that TrueNAS will use for ZFS data storage.
The Create Pool button creates ZFS data storage “pools” from physical disks to efficiently store and protect data.
The Storage screen displays all the pools that users have created on the system. Statistics and status are shown for each pool, along with buttons to manage the different elements of the pool.
The articles in this section offer specific guidance for the different storage management options.
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
We strongly recommend users review the available system resources and plan the storage use case before creating a storage pool.
Determining your specific storage requirements is a critical step before creating a pool.
The articles in this section provide information on setting up system storage, which includes adding, importing or mananging pools, adding or managing datasets and zvols.
TrueNAS uses ZFS data storage pools to efficiently store and protect data.
We strongly recommend that you review your available system resources and plan your storage use case before creating a storage pool.
Determining your specific storage requirements is a critical step before creating a pool.
To create a pool using the Pool Manager you:
You access the Pool Manager from the Storage Dashboard.
Click Storage on the main navigation panel on the left of the screen.
Click Create Pool to open the Pool Manager screen for new pools.
If you already have a pool created on your system you can use either the Create Pool button at the top right of the screen or click the Add To Pool button on the Unassigned Disks widget to create a new pool.
First, enter a name for the pool using up to 50 lower case alpha-numeric and permitted special characters that conform to ZFS naming conventions. The pool name contributes to the maximum character length for datasets so it is limited to 50 characters.
You cannot change the name of the pool after you click Create!
Next, decide if you want to encrypt this pool. Datasets inherit encryption from the pool.
Next, add disks to your primary data VDEV. A data VDEV is the standard VDEV for primary storage operations. A data VDEV configuration typically affects how the other types of VDEVs get configured.
All pools must have a data VDEV. You can add as many VDEV types (cache, log, spare, etc.) as you want to the pool for your use case but it must have a data VDEV.
The Available Disks table lists all available disks detected on the system including disks for exported pools.
Warning: USB-connected disks might report their serial numbers inaccurately, making them indistinguishable from each other.
You can add disks to the data VDEV manually or click the Suggest Layout button and allow TrueNAS to review all available disks and populate the primary Data VDevs with identically sized drives in a configuration balanced between storage capacity and data redundancy. If you don’t want to use the suggested layout, click Reset Layout to clear the data VDEV layout and move the disks back to the Available Disks list.Disks with non-unique serial numbers do not populate the Available Disks section until you select Show disk with non-unique serial numbers.
To manually add disks, select the checkboxes to the left of each disk you want to add and then click the to the left of the data VDEV to move the disks over. See About Data VDEV Layouts or the Pool Manager Screen or more information on data VDEV layouts.
Next, if you want to add another type of VDEV, click Add Vdev and select the VDEV type from the options. Each VDEV type stores data or enables unique features for the pool. For more details on VDEV types and data VDEV layouts see the Pool Manager Screen article.
If you have enough disks of the same size available, you can duplicate the data VDEV.
Click Create to add the pool.
To duplicate a data VDEV, click Repeat First Vdev. If disks of equal size are available, the Repeat First VDEV button opens a window pre-populated or where you enter the number of additional data VDEVs to create.
The dialog displays information on the data VDEV layout, the storage size of the VDEV, and the number of disks used and remaining for the VDEV you are repeating.
Click Repeat Vdev to create and populate a duplicated data VDEV. Another VDEV with an identical configuration is called a mirror of VDEVs.
If you add more disks of the same size to your system, you can add another duplicate data VDEV.
Don’t have multiple data vdevs with different numbers of disks in each VDEV. This complicates and limits the pool capabilities.
You can add a data VDEV to a pool in one of several layouts.
The Pool Manager screen suggests a VDEV layout from the number of disks added to the VDEV. For example, if you add two disks, TrueNAS automatically configures the VDEV as a mirror. The total available storage is the size of one added disk while the other disk provides redundancy.
This section provides articles with instructions for importing, replacing, wiping disks.
To manage disks, go to Storage and click Disks on the top right of the screen to display the Storage Disks screen.
Select the disk on the list, then select Edit.
The Disks page lets users edit disks, perform manual tests, and view S.M.A.R.T. test results. Users may also delete obsolete data off an unused disk.
Select the disk(s) you want to perform a S.M.A.R.T. test on and click Manual Test.
Click Start to begin the test. Depending on the test type you choose, 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.
To review test results, expand the disk and click S.M.A.R.T. Test Results.
Users can also view S.M.A.R.T. Test Results in Shell using the smartctl
command and the name of the drive. For example, smartctl -l selftest /dev/sdb
.
Hard drives and solid-state drives (SSDs) have a finite lifetime and can fail unexpectedly. When a disk fails in a Stripe (RAID0) pool, you must to recreate the entire pool and restore all data backups. We always recommend creating non-stripe storage pools that have disk redundancy.
To prevent further redundancy loss or eventual data loss, always replace a failed disk as soon as possible! TrueNAS integrates new disks into a pool to restore it to full functionality.
TrueNAS requires you to replace a disk with another disk of the same or greater capacity as a failed disk. You must install the disk install in the TrueNAS system and it should not be part of an existing storage pool. TrueNAS wipes the data on the replacement disk as part of the process.
Disk replacement automatically triggers a pool resilver.
If you configure your main SCALE Dashboard to include individual Pool or the Storage widgets they show the status of your system pools as on or offline, degraded, or in an error condition.
The new Storage Dashboard pool widgets also show the status of each of your pools.
From the main Dashboard, you can click the on either the Pool or Storage widget to go to the Storage Dashboard screen, or you can click Storage on the main navigation menu to open the Storage Dashboard and locate the pool in the degraded state.
To replace a failed disk:
Locate the failed drive.
a. Go to the Storage Dashboard and click Manage Devices on the Topology widget for the degraded pool to open the Devices screen for that pool.
b. Click anywhere on the VDEV to expand it and look for the drive with the Offline status.
Take the disk offline.
Click Offline on the ZFS Info widget to take the disk offline. The button toggles to Online.
Pull the disk from your system and replace it with a disk of at least the same or greater capacity as the failed disk. V:
a. Click Replace on the Disk Info widget on the Devices screen for the disk you off-lined.
b. Select the new drive from the Member Disk dropdown list on the Replacing disk diskname dialog.
Add the new disk to the existing VDEV. Click Replace Disk to add the new disk to the VDEV and bring it online.
Disk replacement fails when the selected disk has partitions or data present. To destroy any data on the replacement disk and allow the replacement to continue, select the Force option.
When the disk wipe completes, TrueNAS starts replacing the failed disk. TrueNAS resilvers the pool during the replacement process. For pools with large amounts of data, this can take a long time. When the resilver process completes, the pool status returns to Online status on the Devices screen.
We recommend users off-line a disk before starting the physical disk replacement. Off-lining a disk removes the device from the pool and can prevent swap issues.
Click on Manage Devices to open the Devices screen, click anywhere on the VDEV to expand VDEV and show the drives in the VDEV.
Click Offline on the ZFS Info widget. A confirmation dialog displays. Click Confirm and then Offline. The system begins the process to take the disk offline. When complete, the disk displays the status of the failed disk as Offline. The button toggles to Online.
Use Replace to bring the new disk online in the same VDEV.
After a disk fails, the hot spare takes over. To restore the hot spare to waiting status after replacing the failed drive, remove the hot spare from the pool, then re-add it to the pool as a new hot spare.
The disk wipe option deletes obsolete data from an unused disk.
Wipe is a destructive action and results in permanent data loss! Back up any critical data before wiping a disk.
TrueNAS only shows the Wipe option for unused disks.
Ensure you have backed-up all data and are no longer using the disk. Triple check that you have selected the correct disk for the wipe. Recovering data from a wiped disk is usually impossible.
Click Wipe to open a dialog with additional options:
After selecting the appropriate method, click Wipe and confirm the action. A Confirmation dialog opens.
!
Verify the name to ensure you have chosen the correct disk. When satisfied you can wipe the disk, set Confirm and click Continue.
Continue starts the disk wipe process and opens a progress dialog with the Abort button.
Abort stops the disk wipe process. At the end of the disk wipe process a success dialog displays. Close closes the dialog and returns you to the Disks screen.
Use the Storage Dashboard widgets to manage a pool, and the Dataset screen to manage dataset functions.
Select Storage on the main navigation panel and then click the Edit Auto TRIM on the ZFS Health widget for the selected pool to open the Pool Options for poolname dialog.
Select Auto TRIM.
Click Save.
With Auto TRIM selected and active, TrueNAS periodically checks the pool disks for storage blocks it can reclaim. Auto TRIM can impact pool performance, so the default setting is disabled.
For more details about TRIM in ZFS, see the autotrim
property description in zpool.8.
The Export/Disconnect option allows you to disconnect a pool and transfer drives to a new system where you can import the pool. It also lets you completely delete the pool and any data stored on it.
Select Export/Disconnect on the Storage Dashboard.
A dialog box displays with any system services affected by exporting the pool listed in the dialog.
To delete the pool and erase all the data on the pool, select Destroy data on this pool. The pool name field displays at the bottom of the window. Type the pool name into this field. To export the pool, do not select this option.
Select Delete configuration of shares that used this pool? to delete shares connected to the pool.
Select Confirm Export/Disconnect
Click Export/Disconnect. A confirmation dialog displays when the export/disconnect completes.
ZFS supports adding VDEVs to an existing ZFS pool to increase the capacity of the pool.
You cannot change the original encryption or data VDEV configuration.
To add a VDEV to a pool: Click Manage Devices on the Topology widget to open the Devices screen. Click Add VDEV on the Devices screen. The Add Vdevs to Pool version of the Pool Manager screen opens.
Click Add Vdev and select the type of VDEV you want to add.
Select the disk(s) you want to move to that VDEV and then click the to the left of the VDEV you just added to them to that VDEV.
Repeat for each type of VDEV you want to add to this pool.
Click Add Vdevs at the bottom of the screen to save the changes and close the Pool Manager screen. The Topology widget displays the newly added VDEVs.
You cannot add more drives to an existing data VDEV but you can stripe a new VDEV of the same type to increase the overall pool size. To extend a pool, you must add a data VDEV that is the same type as existing VDEVs.
To make a hot spare for a VDEV, click Add VDev and select Hot Spare. Move the disk you want to use to that Spare VDev before you click Add VDevs to save the changes to the pool.
Use Scrub on the ZFS Health pool widget to start a pool data integrity check.
Click Scrub to open the Scrub Pool dialog. Select Confirm, then click Start Scrub.
If TrueNAS detects problems during the scrub operation, it either corrects them or generates an alert in the web interface.
By default, TrueNAS automatically checks every pool on a reoccurring scrub schedule.
The ZFS Health widget displays the state of the last scrub or disks in the pool. To view scheduled scrub tasks, click View all Scrub Tasks on the ZFS Health widget.
The Storage Dashboard screen Disks button and the Manage Disks button on the Disk Health widget both open the Disks screen.
The Manage Devices button on the Topology widget opens the Devices screen. To manage disks in a pool, click on the VDEV to expand it and show the disks in that VDEV. Click on a disk to see the devices widgets for that disk. You can take a disk offline, detach it, replace it, manage the SED encryption password, and perform other disk management tasks from this screen.
See Replacing Disks for more information on the Offline, Replace and Online options.
Click Expand on the Storage Dashboard to increase the pool size to match all available disk space. An example is expanding a pool when resizing virtual disks apart from TrueNAS.
ZFS pool importing works for pools that are exported or disconnected from the current system, those created on another system, and for pools you reconnect after reinstalling or upgrading the TrueNAS system.
The import procedure only applies to disks with a ZFS storage pool. To import disks with different file systems, see the SCALE Managing Disks article.
To import a pool, go to the Storage Dashboard and click Import Pool at the top of the screen.
TrueNAS detects any pools that are present but unconnected and adds them to the Pools dropdown list.
Select a pool from the Pool dropdown list and click Import.
Fusion Pools are also known as ZFS allocation classes, ZFS special vdevs, and metadata vdevs (Metadata vdev type on the Pool Manager screen.).
Go to Storage Dashboard, click Create Pool.
A pool must always have one normal (non-dedup/special) VDEV before you assign other devices to the special class.
Enter a name for the pool using up to 50 lower case alpha-numeric and permitted special characters that conform to ZFS naming conventions. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
Click ADD VDEV and select Metadata to add the VDEV to the pool layout.
Add disks to the primary Data VDevs, then to the Metadata VDEV.
Add SSDs to the new Metadata VDev and select the same layout as the Data VDevs.
The metadata special VDEV is critical for pool operation and data integrity, so you must protect it with hot spare(s).
Using special VDEVs identical to the data VDEVs (so they can use the same hot spares) is recommended, but for performance reasons, you can make a different type of VDEV (like a mirror of SSDs). In that case, you must provide hot spare(s) for that drive type as well. Otherwise, if the special VDEV fails and there is no redundancy, the pool becomes corrupted and prevents access to stored data.
Drives added to a metadata VDEV cannot be removed from the pool.
When more than one metadata VDEV is created, then allocations are load-balanced between all these devices. If the special class becomes full, then allocations spill back into the normal class.
After you create the fusion pool, the Status shows a Special section with the metadata SSDs.
Over-provisioning SLOG SSDs is useful for different scenarios. The most useful benefit of over-provisioning is greatly extending SSD life. Over-provisioning an SSD distributes the total number of writes and erases across more flash blocks on the drive.
Seagate provides a thoughtful investigation into over-provisioning SSDs here: https://www.seagate.com/blog/ssd-over-provisioning-benefits-master-ti/.
Some SATA devices are limited to one resize per power cycle. Some BIOS can block resize during boot and require a live power cycle.
SCALE uses the disk_resize
command to change the size of a device. The SCALE UI does not have a UI function for this command yet.
Go to System Settings > Shell to enter the command and resize or over-provision a device.
disk_resize sda 32GB
where sda is the device and 32GIB is the new size for the device.
When no size is specified, it reverts the provision back the full size of the device.
The disk_resize
command supports SAS, SATA, SAT (interposer) and NVMe drives. Power cycle SATA drives before a second resize
This section has several tutorials about dataset configuration and management.
A TrueNAS dataset is a file system within a data storage pool. Datasets can contain files, directories (child datasets), and have individual permissions or flags. Datasets can also be encrypted, either using the encryption created with the pool or with a separate encryption configuration.
We recommend organizing your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.
To create a dataset using the default settings, go to Datasets. Default settings include the settings datasets inherit from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
Select SMB for the Share Type or leave it set to Generic, then click Save.
You can create datasets optimized for SMB shares or with customized settings for your dataset use cases.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but it is not used for application data storage. If you want to store data by application, create the dataset first, then deploy your application. When creating a dataset for an application, select App as the Share Type setting. This optimizes the dataset for use by an application.
Review the Share Type and Case Sensitivity options on the configuration screen before clicking Save. You cannot change these or the Name setting after clicking Save.
Compression encodes information in less space than the original data occupies. We recommended you choose a compression algorithm that balances disk performance with the amount of saved space.
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.
You can set dataset quotas when you add a dataset using the Add Dataset > Advanced Options quota management options, or to add or edit quotas for a selected dataset, click Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset. You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space. You can configure quotas for only the new dataset or for both the new dataset and any child datasets of the new dataset.
Define the maximum allowed space for the dataset in either the Quota for this dataset or Quota for this dataset and all children field. Enter 0 to disable quotas.
Dataset quota alerts are based on the percentage of used storage. To set up a quota warning alert, enter a percentage value in Quota warning alert at, %. When consumed space reaches the defined percentage it sends the alert. To change the setting from the parent dataset warning level, clear the Inherit checkbox and then change the value.
To set up the quota critical level alerts, enter the percentage value in Quota critical alert at, %. Clear the Inherit checkbox to change this value to something other than using the parent alert setting.
When setting quotas or changing the alert percentages for both the parent dataset and all child datasets, use the fields under This Dataset and Child Datasets.
Enter a value in Reserved space for this dataset to set aside additional space for datasets that contain logs which could eventually take all available free space. Enter 0 for unlimited.
For more information on quotas, see Managing User or Group Quotas.
By default, many of dataset options inherit their values from the parent dataset. When you select Inherit, as a checkbox or option in a dropdown list, the dataset uses the setting from the parent dataset. For example, the Encryption or ACL Type settings.
To change any setting that can inherit the parent setting, clear the checkbox or select another available option, and then enter the desired setting values for the child dataset.
For information on ACL settings see Setting Up Permissions.
First, add a Metadata VDEV to the pool.
Then add the dataset. Use the Metadata (Special) Small Block Size setting on the Add Dataset > Advanced Options > Other Options screen to set a threshold block size for including small file blocks into the special allocation class (fusion pools).
Blocks smaller than or equal to this value are assigned to the special allocation class while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. The default size 0 means no small file blocks are allocated in the special class. Enter a threshold block size for including small file blocks into the special allocation class (fusion pools).
After creating a dataset, users can manage additional options from the Datasets screen. Select the dataset you want to manage, then click Edit on the widget for the function you want to manage. The Datasets Screen article describes each option in detail.
Select the dataset on the tree table, then click Edit on the Dataset Details widget to open the Edit Dataset screen and change the dataset configuration settings. You can change all settings except Name, Case Sensitivity, or Share Type.
The Permissions widget for a dataset with an NFSv4 ACL type, converts each listed ACL item a button that opens a permissions editor for that ACL item. To configure new ACL items for an NFSv4 ACL, click Edit to open the ACL Editor screen.
To edit a POSIX ACL type, click Edit on the Permissions widget to open the Unix Permissions Editor screen.
For more information, see the Setting Up Permissions article.
Select the dataset on the tree table, then click Delete on the Dataset Details widget. This opens a window where you enter the path (parent/child) and select Confirm to delete the dataset, all stored data, and any snapshots from TrueNAS.
To delete a root dataset, use the Export/Disconnect option on the Storage Dashboard screen to delete the pool.
Deleting datasets can result in unrecoverable data loss! Move off any critical data stored on the dataset or obsolete it before performing the delete operation.
A ZFS Volume (zvol) is a dataset that represents a block device or virtual disk drive. TrueNAS requires a zvol when configuring iSCSI Shares. Adding a virtual machine also creates a zvol to use for storage.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused. Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume. Do not assign capacity that exceeds what is required for SCALE to operate properly. For more information, see SCALE Hardware Guide for CPU, memory and storage capacity information.
To create a zvol in a pool, go to Datasets. Select the root, non-root parent, or child dataset where you want to add the zvol, and then click Add Zvol.
To create a zvol with default options, enter a name and a value in Size for the zvol and click Save.
Options to manage a zvol are on the zvol widgets found on the Dataset screen. Select the zvol to display the zvol widgets.
Delete Zvol removes the zvol from TrueNAS. Deleting a zvol also deletes all snapshots of that zvol. Click Delete on the Zvol Details widget.
Deleting zvols can result in unrecoverable data loss! Remove critical data from the zvol or verify it is obsolete before deleting a zvol.
Edit on the Zvol Details widget opens the Edit Zvol screen where you can change the saved settings. Name is read-only and you cannot change it.
To create a snapshot, click Create Snapshot on the Data Protection widget.
If you clone a zvol from an existing snapshot, the cloned zvol displays on the Datasets screen.
Importing is a one-time procedure that copies data (from a disk) into a TrueNAS dataset. TrueNAS can only import one disk at a time, and you must install or physically connect it to the TrueNAS system.
You can use the import function to integrate UFS (BSD Unix), NTFS (Windows), MSDOS (FAT), or EXT2 (Linux) formatted disks into TrueNAS.
You can only import one disk at a time.
To import a disk:
Go to Dataset and click Import Data at the top right of the screen.
Use the Disk dropdown list to select the disk you want to import.
TrueNAS attempts to detect and select the file system type. If not already selected by the system, click a radio button for a file system type to use from the on-screen options.
Selecting the MSDOSFS file system displays the MSDOSFS locale dropdown field. Use this option to select the locale when non-ASCII characters are present on the disk. Select the locale for the MSDOSFS device to see files of that locale.
Select the ZFS dataset you want to hold the copied data in Destination Path.
Click Save. The disk mounts and copies its contents to the specified dataset you entered in Destination Path.
To monitor an in-progress import, click the assignment on the top toolbar, then click History open the Jobs Manager.
The disk unmounts after the copy operation completes. A dialog allows viewing or downloading the disk import log.
TrueNAS allows setting data or object quotas for user accounts and groups cached on or connected to the system. You can use the quota settings on the Add Dataset or Edit Dataset configuration screens in the Advanced Options settings to set up alarms and set aside more space in a dataset. See Adding and Managing Datasets for more information.
To manage the dataset overall capacity, use Edit on the Dataset Space Management widget to open the Capacity Settings screen.
To view and edit user quotas, go to Datasets and click Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen.
Click Add to open the Add User Quota screen.
Click in the field to view a list of system users including any users from a directory server properly connected to TrueNAS. Begin typing a user name to filter all users on the system to find the desired user, then click on the user to add the name. Add additional users by repeating the same process. A warning dialog displays if there are not matches found.
To edit individual user quotas, click anywhere on a user row to open the Edit User Quota screen where you can edit the User Data Quota and User Object Quota values.
User Data Quota is the amount of disk space that selected users can use. User Object Quota is the number of objects selected users can own.
Click Add to open the Add Group Quota screen.
Click in the Group field to view a list of system groups on the system. Begin typing a name to filter all groups on the system to find the desired group, then click on the group to add the name. Add additional groups by repeating the same process. A warning dialog displays if there are not matches found.
To edit individual group quotas, click anywhere on a group name to open the Edit Group Quota screen where you can edit the Group Data Quota and Group Object Quota values.
Group Data Quota is the amount of disk space that the selected group can use. Group Object Quota is the number of objects the selected group can own.
Snapshots are one of the most powerful features of ZFS. A snapshot provides a read only point-in-time copy of a file system or volume. This copy does not consume extra space in the ZFS pool. The snapshot only records the differences between storage block references whenever the data is modified.
Taking snapshots requires the system have all pools, datasets, and zvols already configured.
Consider making a Periodic Snapshot Task to save time and create regular, fresh snapshots.
There are two ways to access snapshot creation:
To access the Snapshots screen, go to Data Protection > Periodic Snapshot Tasks and click the Snapshots button in the lower right corner of the widget.
Existing snapshots display as a list.
From the Datasets screen select the dataset you want to snapshot, then click Create Snapshot on Data Protection widget.
If you click Create Snapshot the Snapshots screen opens filtered for the dataset you selected. Clear the dataset from the search field to see all snapshots.
You can also click the Manage Snapshots link on the Data Protection widget to open the Snapshots screen.
Select a dataset or zvol from the Dataset dropdown list.
Accept the name suggested by the TrueNAS software in the Name field or enter any custom string to override the suggested name.
(Optional) Select an option from the Naming Schema dropdown list that the TrueNAS software populated with existing periodic snapshot task schemas.
If you select an option, TrueNAS generates a name for the snapshot using that naming schema from the selected periodic snapshot and replicates that snapshot.
You cannot enter a value in both Naming Schema and in Name as selecting or entering a value in Naming Schema populates the other field.
(Optional) Select Recursive to include child datasets with the snapshot.
Click Save to create the snapshot.
File Explorer limits the number of snapshots Windows presents to users. If TrueNAS responds with more than the File Explorer limit, File Explorer shows no available snapshots. TrueNAS displays a dialog stating the dataset snapshot count has more snapshots than recommended, and states performance or functionality might degrade.
There are two ways to view the list of snapshots:
The Snapshots screen displays a list of snapshots on the system. Use the search bar at top to narrow the selection, clear the search bar to list all snapshots.
Click
to view snapshot options.The Clone to New Dataset button creates a clone of the snapshot. The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen. Clicking the Clone to New Dataset button opens a clone confirmation dialog.
Click Clone to confirm.
The Go to Datasets button opens the Datasets screen.
Clicking on the clone name in the dataset listing populates the Dataset Details widget. The Promote button is visible.
After clicking the Promote button, the dataset clone is promoted and this button no longer appears.
Promote now displays on the Dataset Details widget when you select the demoted parent dataset.
See zfs-promote.8 for more information.
The Delete option destroys the snapshot. You must delete child clones before you can delete their parent snapshot. While creating a snapshot is instantaneous, deleting one is I/O intensive and can take a long time, especially when deduplication is enabled.
Click the Delete button. A confirmation dialog displays. Select Confirm to activate the Delete button.
To delete multiple snapshots, select the left column box for each snapshot to include. Click the delete Delete button that displays.
To search through the snapshots list by name, type a matching criteria into the search Filter Snapshots text field. The list now displays only the snapshot names that match the filter text.
Confirm activates the Delete button. If the snapshot has the Hold options selected, an error displays to prevent you from deleting that snapshot.
The Rollback option reverts the dataset back to the point in time saved by the snapshot.
Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out-of-order. To restore the data within a snapshot:Rollback is a dangerous operation that causes any configured replication tasks to fail.
This approach does not destroy any on-disk data or impact replication.
TrueNAS asks for confirmation before rolling back to the chosen snapshot state. Select the radio button for how you want the rollback to operate.
Click Confirm to activate the Rollback button.
Browsing a snapshot collection is an advanced capability that requires ZFS and command-line experience.
All dataset snapshots are accessible as an ordinary hierarchical file system, accessed from a hidden
A snapshot and any files it contains are not accessible or searchable if the snapshot mount path is longer than 88 characters. The data within the snapshot is safe but to make the snapshot accessible again shorten the mount path.
A user with permission to access the hidden file can view and explore all snapshots for a dataset from the Shell or the Shares screen using services like SMB, NFS, and SFTP.
In summary, the main required changes to settings are:
veto files
command to not hide the zfsacl:expose_snapdir=true
.The effect is that any user who can access the dataset contents can view the list of snapshots by going to the dataset
When creating a snapshot, permissions or ACLs set on files within that snapshot might limit access to the files.
Snapshots are read-only, so users do not have permission to modify a snapshot or its files, even if they had write permissions when creating the snapshot.
The zfs diff
ZFS command, which can run in the Shell, lists all changed files between any two snapshot versions within a dataset, or between any snapshot and the current data.
TrueNAS SCALE offers ZFS encryption for your sensitive data in pools and datasets or Zvols.
Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.
Data-at-rest encryption is available with:
The local TrueNAS system manages keys for data-at-rest. Users are responsible for storing and securing their keys. TrueNAS SCALE includes the Key Management Interface Protocol (KMIP).
Encryption is for users storing sensitive data. Pool-level encryption does not apply to the storage pool or the disks in the pool. It only applies to the root dataset that shares the same name as the pool. Child datasets or zvols inherit encryption from the parent dataset.
TrueNAS automatically generates a root dataset when you create a pool. This root dataset inherits the encryption state of the pool based on the Encryption option on the Pool Manager screen when you create the pool. Because encryption is inherited from the parent, the data within that pool is encrypted. Selecting the Encryption option for the pool (root dataset) forces encryption for all datasets and Zvols created within the root dataset.
As of SCALE 22.12.3, you can no longer create an unencrypted dataset within an encrypted pool or dataset. This change does not affect existing datasets, only new datasets created in release 22.12.3 and later.
Leaving the Encryption option on the Pool Manager screen cleared creates an unencrypted pool root dataset. You can create both unencrypted and encrypted datasets within this pool (root dataset), but if you create an encrypted dataset within an unencrypted root dataset any dataset or Zvol created within that encrypted dataset are automatically encrypted. If you have only one pool on your system, do not select the Encryption option for this pool.
If your system loses power or you reboot the system, the datasets, Zvols, and all data in an encrypted pool automatically lock to protect the data in that encrypted pool.
Dataset encryption can be visually confusing in SCALE. SCALE uses different lock-type icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen. Each icon displays text labels that explain the state of the dataset when you hover the mouse over the icon.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon | State | Description |
---|---|---|
![]() | Locked | Displays for locked encrypted root, non-root parent and child datasets. |
![]() | Unlocked | Displays for unlocked encrypted root, non-root parent and child datasets. |
![]() | Locked by ancestor | Displays for locked datasets that inherit encryption properties from the parent. |
![]() | Unlocked by ancestor | Displays for unlocked datasets that inherit encryption properties from the parent. |
If a dataset inherits encryption, the locking icons change to a different type and the mouse hover-over label indicates the encryption is Locked by ancestor or Unlocked by ancestor.
Each encrypted dataset includes the ZFS Encryption widget on the Datasets screen when you select the dataset.
The dataset encryption state is unlocked until you lock it using the Lock option on the ZFS Encryption widget. After locking the dataset, the icon on the tree table changes to the locked version and the ZFS Encryption widget displays the Unlock option.
Datasets inherit encryption, which means they keep the encryption settings of the parent dataset whether the parent is the root dataset or a non-root parent dataset with child datasets nested under it.
You can change inherited settings for a dataset when you add the dataset using the Edit option on the ZFS Encryption widget.
Before creating a pool with encryption make sure you want to encrypt all datasets and data stored on the pool.
If your system does not have enough disks to allow you to create a second storage pool, we recommend that you not use encryption at the pool level. You can mix encrypted and unencrypted datasets on an unencrypted pool.You cannot change a pool from encrypted to non-encrypted. You can only change the dataset encryption type (key or passphrase) for the encrypted pool.
All pool-level encryption is key-based encryption. When prompted, download the encryption key and keep it stored in a safe place where you can back up the file. You cannot use passphrase encryption at the pool level.
Go to Storage and click Create Pool on the Storage Dashboard screen. You can also click Add to Pool on the Unassigned Disks widget and select the Add to New radio button to open the Pool Manager screen.
Enter a name for the pool, then add the disks to the Data VDEV. Select Encryption next to Name. A warning dialog displays.
Read the warning, select Confirm, and then click I UNDERSTAND.
A second dialog opens where you click Download Encryption Key for the pool encryption key.
Click Done to close the window. Move the encryption key to safe location where you can back up the file.
Click Save to create the pool with encryption.
To add encryption to a new dataset, go to Datasets.
First, select the root or other dataset on the tree table where you want to add a dataset. The default dataset selected when you open the Datasets screen is the root dataset of the first pool on the tree table list. If you have more than one pool and want to create a dataset in a pool other than the default, select the root dataset for that pool or any dataset under the root where you want to add the new dataset.
Click Add Dataset to open the Add Dataset screen.
To add a dataset, enter a value in Name.
Next, select the type of Case Sensitivity and Share Type for the dataset.
To add encyrption to a dataset, select Inherit under Encryption Options to clear the checkbox. This displays the Encryption checkbox already preselected.
Now decide if you want to use the default encryption type key and if you want to let the system generate the encryption key. To use key encryption and your own key, clear the Generate key checkbox to display the Key field. Enter your key in this field.
To change to passphrase encryption, click the down arrow and select Passphrase from the Encryption Type dropdown.
You can select the encryption algorithm to use from the Encryption Standard dropdown list of options or use the recommended default.
Leave the default selection if you do not have a particular encryption standard you want use.
The passphrase must be longer than 8 and less than 512 characters.
Keep encryption keys and/or passphrases safeguarded in a secure and protected place. Losing encryption keys or passphrases can result in permanent data loss!
You cannot add encryption to an existing dataset. You can change the encryption type for an already encrypted dataset using the Edit option on the ZFS Encryption widget for the dataset.
Save any change to the encryption key or passphrase, and update your saved passcodes and keys file, and then back up that file.
To change the encryption type, go to Datasets:
Select the unlocked, encrypted dataset on the tree table, then click Edit on the ZFS Encryption widget. The Edit Encryption Options dialog for the selected dataset displays.
You must unlock a locked encrypted dataset before you can make changes.
If the dataset inherits encryption settings from a parent dataset, to change this, clear the Inherit encryption properties from parent checkbox to display the key type encryption setting options.
Change the encryption settings. Key type options are to change the type from Key to Passphrase or from a generated to a manually-entered encryption key. After clearing the Inherits encryption properties from parent the default settings display with Encryption Type set to Key and Generate Key pre-selected. To manually enter an encryption key, select Generate Key to clear the checkmark and display the Key field. Enter the new key in this field.
(Optional) Change the Encryption Type to Passphrase using the dropdown list of options. The Passphrase and Confirm Passphrase fields and other passphrase encryption fields display.
Enter the passphrase twice. Use a complex passphrase that is not easy to guess. Store in a secure location subject to regular backups.
Leave the other settings at default, then click Confirm to activate Save.
Click Save. The window closes, the ZFS Encryption widget updates to reflect the changes made.
You can only lock and unlock an encrypted dataset if it is secured with a passphrase instead of a key file. Before locking a dataset, verify that it is not currently in use.
Select the dataset on the tree table, then click Lock on the ZFS Encryption widget to open the Lock Dataset dialog with the dataset full path name.
Use the Force unmount option only if you are certain no one is currently accessing the dataset. Force unmount boots anyone using the dataset (e.g. someone accessing a share) so you can lock it. Click Confirm to activate Lock, then click Lock.
You cannot use locked datasets.
To unlock a dataset, go to Datasets then select the dataset on the tree table. Click Unlock on the ZFS Encryption widget to open the Unlock Dataset screen.
Type the passphrase into Dataset Passphrase and click Save.
Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.
Select Force if the dataset mount path exists but is not empty. When this happens, the unlock operation fails. Using Force allows the system to rename the existing directory and file where the dataset should mount. This prevents the mount operation from failing. A confirmation dialog displays.
Click CONTINUE to confirm you want to unlock the datasets. Click CLOSE to exit and keep the datasets locked. A second confirmation dialog opens confirming the datasets unlocked. Click CLOSE. TrueNAS displays the dataset with the unlocked icon.
Encryption is for securing sensitive data.
You can only encrypting a Zvol if you create the Zvol from a dataset with encryption.
Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.
Zvols inherit encryption settings from the parent dataset.
To encrypt a Zvol, select a dataset configured with encryption and then create a new Zvol. Next, click the more_vert icon to display the Zvol Actions options list and then click Encryption Options.
If you do not see Encryption Options on the Zvol Actions option list you created the Zvol from an unencrypted dataset. Delete the Zvol and start over.
Click Encryption Options. The Edit Encryption Options dialog for the Zvol displays with Inherit encryption properties from parent selected.
If not making changes, click Confirm, and then click Save. The Zvol is encrypted with settings inherited from its parent.
To change inherited encryption properties, clear the Inherit encryption properties from parent checkbox. The current encryption settings display. You can change from key to passphrase or change from a system-generated key to one of your choosing.
If Encryption Type is set toKey, type an encryption key into the Key field or select Generate Key. If using Passphrase, it should be at least eight characters long. Use a passphrase complex enough to not easily guess. After making any changes, select Confirm, and then click Save.
Save any change to the encryption key or passphrase, update your saved passcodes and keys file, and back up the file.
There are two ways to manage the encryption credentials, with a key file or passphrase.
Creating a new encrypted pool automatically generates a new key file and prompts users to download it.
Always back up the key file to a safe and secure location.
To manually back up a root dataset key file, click the icon to display the Pool Actions list of options, and select Export Dataset Keys. The keys download to your system.
To change the key, click more_vert for the dataset, and then click Encryption Options.
See Changing Dataset-Level Encryption for more information on changing encryption settings.
A passphrase is a user-defined string at least eight characters long that is required to decrypt the dataset.
The pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Users must enter a number greater than 100000.
TrueNAS SCALE users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special json manifest to unlock each child dataset/Zvol with a unique key.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension
On the remote system, unlock the dataset(s) using properly constructed
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Go to Datasets on the system you are replicating from. Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset. Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
TrueNAS SCALE provides basic permissions settings and an Access Control List (ACL) editor to define dataset permissions. ACL permissions control the actions users can perform on dataset contents.
An Access Control List (ACL) is a set of account permissions associated with a dataset and applied to directories or files within that dataset. TrueNAS uses ACLs to manage user interactions with shared datasets and creates them when users add a dataset to a pool.
TrueNAS SCALE offers two 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.
Basic ACL permissions are viewable and configurable in the Datasets screen. Select a dataset to view its permissions in the Permissions widget.
You can view permissions for any dataset, but the edit option only displays on the Permissions widget for non-root datasets.
Configuring advanced permissions overrides basic permissions configured on the add and edit dataset screens.
Select a non-root dataset, then click Edit in the Permissions widget.
Enter or select the user from the dropdown list, set the read/write/execute permissions. The options include users created manually or imported from a directory service. Enable Apply User to confirm changes. To prevent errors, TrueNAS only submits changes when selected.
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.
Next, enter or select the group from the dropdown list, set the read/write/execute permissions. The options include groups created manually or imported from a directory service. Enable Apply Group to confirm changes. To prevent errors, TrueNAS only submits changes when selected.
If you want to apply these settings to all child datasets, select Apply permissions recursively.
Click Save if you do not want to use an ACL preset.
Warning: Changing the ACL type affects how TrueNAS writes and reads on-disk ZFS ACL.
When the ACL type changes from POSIX to NFSv4, internal ZFS ACLs do not migrate by default, and access ACLs encoded in posix1e extended attributes convert to native ZFS ACLs.
When the ACL type changes from NFSv4 to POSIX, native ZFS ACLs do not convert to posix1e extended attributes, but ZFS will use the native ACL for access checks.
To prevent unexpected permissions behavior, you must manually set new dataset ACLs recursively after changing the ACL type.
Setting new ACLs recursively is destructive. We suggest creating a ZFS snapshot of the dataset before changing the ACL type or modifying permissions.
An ACL preset loads NFS4 pre-configured permissions to match general permissions situations.
From the Unix Permissions Editor configuration screen, click Set ACL to configure advanced NFS4 permissions. The If you want to use an ACL preset, click Set ACL. The Edit ACL screen displays with the Select a preset ACL dialog as the first step.
Click the Select a present ACL radio button to use a pre-configured set of permissions, and then select the preset you want to use from the Default ACL Options dropdown list, or click Create a custom ACL to configure your own set of permissions. Click Continue.
Each default preset loads different permissions to the Edit ACL screen. The Create a custom preset option opens the Edit ACL screen with no default permission settings.
First, select or type the user name in Owner. The owner controls which TrueNAS user and group has full control of the dataset.
Next, select or type the group name in Owner Group.
Select the Who ACE value from the dropdown list and then select the Permissions. If you select User or Group, choose a name from the User or Group field. See nfs4_setfacl(1) NFSv4 ACL ENTRIES. Whatever you select in Who highlights the Access Control List entry on the left side of the screen.
Select Flags to specify how this ACE applies to newly created directories and files within the dataset. Basic flags enable or disable ACE inheritance. Advanced flags allow further control of how the ACE applies to files and directories in the dataset.
If you want to apply this preset to all child datasets select Apply permissions recursively.
To add another item to your ACL, click Add Item. To display the ACL presets window, click Use Preset.
Click Save Access Control List when you finish configuring settings for the user or group in the Who field.
Pyrite Version 1 SEDs do not have PSID support and can become unusable if the password is lost.
See this Trusted Computing Group and NVM Express® joint white paper for more details about these specifications.
TrueNAS implements the security capabilities of camcontrol for legacy devices and sedutil-cli for TCG devices.
When managing a SED from the command line, it is recommended to use the sedhelper
wrapper script for sedutil-cli
to ease SED administration and unlock the full capabilities of the device. See provided examples of using these commands to identify and deploy SEDs below.
You can configure a SED before or after assigning the device to a pool.
By default, SEDs are not locked until the administrator takes ownership of them. Ownership is taken by explicitly configuring a global or per-device password in the web interface and adding the password to the SEDs. Adding SED passwords in the web interface also allows TrueNAS to automatically unlock SEDs.
A password-protected SED protects the data stored on the device when the device is physically removed from the system. This allows secure disposal of the device without having to first wipe the contents. Repurposing a SED on another system requires the SED password.
For TrueNAS High Availability (HA) systems, SED drives only unlock on the active controller!
Enter command sedutil-cli --scan
in the Shell to detect and list devices. The second column of the results identifies the drive type:
Character | Standard |
---|---|
no | non-SED device |
1 | Opal V1 |
2 | Opal V2 |
E | Enterprise |
L | Opalite |
p | Pyrite V1 |
P | Pyrite V2 |
r | Ruby |
Example:
root@truenas1:~ # sedutil-cli --scan
Scanning for Opal compliant disks
/dev/ada0 No 32GB SATA Flash Drive SFDK003L
/dev/ada1 No 32GB SATA Flash Drive SFDK003L
/dev/da0 No HGST HUS726020AL4210 A7J0
/dev/da1 No HGST HUS726020AL4210 A7J0
/dev/da10 E WDC WUSTR1519ASS201 B925
/dev/da11 E WDC WUSTR1519ASS201 B925
TrueNAS supports setting a global password for all detected SEDs or setting individual passwords for each SED. Using a global password for all SEDs is strongly recommended to simplify deployment and avoid maintaining separate passwords for each SED.
Go to System Settings > Advanced > Self-Encrypting Drive and click Configure. A warning displays stating Changing Advanced settings can be dangerous when done incorrectly. Please use caution before saving. Click Close to display the settings form. Enter the password in SED Password and Confirm SED Password and click Save.
Now configure the SEDs with this password. Go to the Shell and enter commandRecord this password and store it in a safe place!
sedhelper setup <password>
, where <password>
is the global password entered in System > Advanced > SED Password.sedhelper
ensures that all detected SEDs are properly configured to use the provided password:
root@truenas1:~ # sedhelper setup abcd1234
da9 [OK]
da10 [OK]
da11 [OK]
Rerun command sedhelper setup <password>
every time a new SED is placed in the system to apply the global password to the new SED.
Go to Storage click the Disks dropdown in the top right of the screen and select Disks. From the Disks screen, click the
for the confirmed SED, then Edit. Enter and confirm the password in the SED Password fields to override the global SED password.You must configure the SED to use the new password. Go to the Shell and enter command sedhelper setup --disk <da1> <password>
, where <da1>
is the SED to configure and <password>
is the created password from Storage > Disks > Edit Disks > SED Password.
Repeat this process for each SED and any SEDs added to the system in the future.
Remember SED passwords! If you lose the SED password, you cannot unlock SEDs or access their data. After configuring or modifying SED passwords, always record and store them in a secure place!
When SED devices are detected during system boot, TrueNAS checks for configured global and device-specific passwords.
Unlocking SEDs allows a pool to contain a mix of SED and non-SED devices. Devices with individual passwords are unlocked with their password. Devices without a device-specific password are unlocked using the global password.
To verify SED locking is working correctly, go to the Shell. Enter command sedutil-cli --listLockingRange 0 <password> <dev/da1>
, where <dev/da1>
is the SED and <password>
is the global or individual password for that SED. The command returns ReadLockEnabled: 1
, WriteLockEnabled: 1
, and LockOnReset: 1
for drives with locking enabled:
root@truenas1:~ # sedutil-cli --listLockingRange 0 abcd1234 /dev/da9
Band[0]:
Name: Global_Range
CommonName: Locking
RangeStart: 0
RangeLength: 0
ReadLockEnabled: 1
WriteLockEnabled:1
ReadLocked: 0
WriteLocked: 0
LockOnReset: 1
This section contains command line instructions to manage SED passwords and data. The command used is sedutil-cli(8). Most SEDs are TCG-E (Enterprise) or TCG-Opal (Opal v2.0). Commands are different for the different drive types, so the first step is to identify the type in use.
These commands can be destructive to data and passwords. Keep backups and use the commands with caution.
Check SED version on a single drive, /dev/da0 in this example:
root@truenas:~ # sedutil-cli --isValidSED /dev/da0
/dev/da0 SED --E--- Micron_5N/A U402
To check all connected disks at once:
root@truenas:~ # sedutil-cli --scan
Scanning for Opal compliant disks
/dev/ada0 No 32GB SATA Flash Drive SFDK003L
/dev/ada1 No 32GB SATA Flash Drive SFDK003L
/dev/da0 E Micron_5N/A U402
/dev/da1 E Micron_5N/A U402
/dev/da12 E SEAGATE XS3840TE70014 0103
/dev/da13 E SEAGATE XS3840TE70014 0103
/dev/da14 E SEAGATE XS3840TE70014 0103
/dev/da2 E Micron_5N/A U402
/dev/da3 E Micron_5N/A U402
/dev/da4 E Micron_5N/A U402
/dev/da5 E Micron_5N/A U402
/dev/da6 E Micron_5N/A U402
/dev/da9 E Micron_5N/A U402
No more disks present ending scan
root@truenas:~ #
The Data Protection section allows users to set up multiple reduntant tasks that will 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.
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.
When TrueNAS performs a scrub, ZFS scans the data on a pool. 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.
To schedule a new resilver task to run at a higher priority, select the hour and minutes from the Begin dropdown list.
To schedule a new resilver task to run at a lower priority to other processes, select the hour and minutes from the End dropdown list. Running at a lower priority is a slower process and takes longer to complete. Schedule this for times when your server is at its lowest demand level.
TrueNAS needs at least one data pool to create scrub task.
To create a scrub task for a pool, go to Data Protection and click ADD in the Scrub Tasks window.
Select a preset schedule from the dropdown list or click Custom to create a new schedule for when to run a scrub task. Custom opens the Advanced Scheduler window.
To view the progress of a scrub task, check the status under the Next Run column.
To edit a scrub, go to Data Protection and click the scrub task you want to edit.
This section has tutorials for configuring and managing data backups to from TrueNAS to various 3rd party Cloud Service Providers.
TrueNAS can send, receive, or synchronize data with a cloud storage provider. Cloud sync tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
Using the cloud means data can go to a third-party commercial vendor not directly affiliated with iXsystems. You should fully understand vendor pricing policies and services before using them for cloud sync tasks.
iXsystems is not responsible for any charges incurred from using third-party vendors with the cloud sync feature.
You can create the cloud storage account credentials using Credentials > Backup Credentials > Cloud Credentials before creating the sync task or add it at the time you create the cloud sync task on Data Protection > Cloud Sync Task > Add Cloud Sync Task. See the Cloud Credentials article for instructions on adding a backup credential using cloud credentials.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Add Cloud Sync Task configuration screen opens.
(Required) Type a memorable task description in Description.
Select an existing backup credential from the Credential dropdown list. If you have not added the cloud credential, click Manage Credentials to open the Backup Credentials screen.
Select the option from Direction and in Transfer Mode.
Select the dataset location in Directory/Files.
Cloud provider settings change based on the credential you select. Select or enter the required settings that include where files are stored.
Select the time from the Schedule options.
Click Save to add the task.
You can use Dry Run to test your configuration before you click Save or select the option on the Cloud Sync Task widget after you click Save.
Sync keeps all the files identical between the two storage locations. If the sync encounters an error, it does not delete files in the destination.
One common error occurs when the Dropbox copyright detector flags a file as copyrighted.
Syncing to a Backblaze B2 bucket does not delete files from the bucket, even when you deleted those files locally. Instead, files are tagged with a version number or moved to a hidden state. To automatically delete old or unwanted files from the bucket, adjust the Backblaze B2 Lifecycle Rules.
A directory, deleted in BackBlaze B2 and notated with an asterisk, do not display in the SCALE UI. These folders are essentially empty directories and Backblaze API restricts these so they do not display.
Sync cannot delete files stored in Amazon S3 Glacier or S3 Glacier Deep Archive. First restore these files by another means, like the Amazon S3 console.
Advanced users can write scripts that run immediately before or after the cloud sync task. Using either the Add Cloud Sync Task or Edit Cloud Sync Task screens, enter environment variables to either the Pre-script or Post-script fields. The Post-script field only runs when the cloud sync task succeeds.
Saved tasks activate according to their schedule or you can use the Run Now option the Cloud Sync Task widget.
To run the sync task before the saved schedule for the task, click on the cloud sync task to open the edit configuration screen for that task.
If not already cleared, select Enable below the Schedule field to clear the checkbox, and then click Save.
On the Cloud Sync Task widget, click the Run Now play_arrow button.
An in-progress cloud sync must finish before another can begin. Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.
To view logs about a running task, or its most recent run, click State.
To create a new cloud sync task that uses the same options but reverses the data transfer, select history for an existing cloud sync on the Data Protection page. The Restore Cloud Sync Task window opens.
Enter a name in Description for this reversed task.
Select the Transfer Mode and then define the path for a storage location on TrueNAS scale for the transferred data.
Click Restore.
TrueNAS saves the restored cloud sync as another entry in Data protection > Cloud Sync Tasks.
If you set the restore destination to the source dataset, TrueNAS may alter ownership of the restored files to root. If root did not create the original files and you need them to have a different owner, you can recursively reset their ACL permissions through the GUI or run chown
from the CLI.
Google Drive and G Suite are widely used tools for creating and sharing documents, spreadsheets, and presentations with team members. While cloud-based tools have inherent backups and replications included by the cloud provider, certain users might require additional backup or archive capabilities. For example, companies using G Suite for important work might be required to keep records for years, potentially beyond the scope of the G Suite subscription. TrueNAS offers the ability to easily back up Google Drive by using the built-in cloud sync.
You can add Google Drive credentials using the Add Cloud Credentials screen accessed from the Credentials > Backup Credentials > Cloud Credentials screen, or you can add them when you create a cloud sync task using the Add Cloud Sync Task screen accessed from the Data Protection > Cloud Sycn Task screen.
To set up a cloud credential, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
Select Google Drive on the Provider dropdown list. The Google Drive authentication settings display on the screen.
Enter the Google Drive authentication settings.
a. Enter the Google Drive user name and password.
b. Click Log In To Provider. The Google Authentication window opens.
c. Click Proceed to open the Choose an Account window.
d. Select the email account to use. Google displays the Sign In window. Enter the password and click Next to enter the password. Click Next again. Google might display a Verify it’s you window. Enter a phone number where Google can text an verification code, or you can click Try another way.
e. Click Allow on the TrueNAS wants to access your Google Account window. TrueNAS populates Access Token with the token Google provides.
Click Verify Credentials and wait for TrueNAS to display the verification dialog with verified status. Close the dialog.
Click Save. The Cloud Credentials widget displays the new credentials. These are also available for cloud sync tasks to use.
You must add the cloud credential on the Backup Credentials screen before you create the cloud sync task.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Add Cloud Sync Task configuration screen opens.
(Required) Type a memorable task description in Description. For example, googledrivepush to represent the provider name and transfer direction.
Select your Google Drive credential on the Credential dropdown list to add a new backup credential.
Select the direction for the sync task. PULL brings files from the cloud storage provider to the location specified in Directory/Files (this is the location on TrueNAS SCALE). PUSH sends files from the location in Directory/Files to the cloud storage provider location you specify in Folder.
Select the transfer method from the Transfer Mode dropdown list. Sync keeps files identical on both TrueNAS SCALE and the remote cloud provider server. If the sync encounters an error, destination server files are not deleted. Copy duplicates files on both the TrueNAS SCALE and remote cloud provider server. Move transfer the files to the destination server and then deleted the copy on server that transferred the files. It also overwrites files with the same names on the destination.
Enter or browse to the dataset or folder directory using the
arrow to the left of / under the Directory/Files and Folder fields. Select the TrueNAS SCALE dataset path in Directory/Files and the Google Drive path in Folder. If PUSH is the selected Direction, this is where on TrueNAS SCALE the files you want to copy, sync or move transfer to the provider. If Direction is set to PULL this is the location where on TrueNAS SCALE you want to copy, sync or move files to.Click the
to the left of / to collapse the folder tree.Select the preset from the Schedule dropdown that defines when the task runs. For a specific schedule, select Custom and use the Advanced Scheduler. Clear the Enable checkbox to make the configuration available without allowing the specified schedule to run the task.
To manually activate a saved task, go to Data Protection > Cloud Sync Tasks, click for the cloud sync task you want to run. Click CONTINUE or CANCEL for the Run Now operation.
(Optional) Set any advanced option you want or need for your use case or define environment variables in either the Pre-script or Post-script fields. These fields are for advanced users.
Click then click Dry Run to test your settings before you click Save. TrueNAS connects to the cloud storage provider and simulates a file transfer but does not send or receive data.
The new cloud sync task displays on the Cloud Sync Tasks widget with the status of PENDING until it completes. If the task completes without issue the status becomes SUCCESS.
See Using Scripting and Environment Variables for more information on environment variables.
One caveat is that Google Docs and other files created with Google tools have their own proprietary set of permissions and their read/write characteristics unknown to the system over a standard file share. Files are unreadable as a result.
To allow Google-created files to become readable, allow link sharing to access the files before the backup. Doing so ensures that other users can open the files with read access, make changes, and then save them as another file if further edits are needed. Note that this is only necessary if the file was created using Google Docs, Google Sheets, or Google Slides; other files should not require modification of their share settings.
TrueNAS is perfect for storing content, including cloud-based content, for the long term. Not only is it simple to sync and backup from the cloud, but users can rest assured that their data is safe, with snapshots, copy-on-write, and built-in replication functionality.
TrueNAS can send, receive, or synchronize data with the cloud storage provider Storj. Cloud sync tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.
This procedure provides instructions to set up both Storj and SCALE.To take advantage of the lower-cost benefits of the Storj-TrueNAS cloud service, you must create your Storj account using the link provided on the Add Cloud Credentials screen.
You must also create and authorize the storage buckets on Storj for use by SCALE.
iXsystems is not responsible for any charges incurred from using a third-party vendor with the cloud sync feature.
TrueNAS supports major providers like Amazon S3, Google Cloud, and Microsoft Azure. It also supports many other vendors. To see the full list of supported vendors, go to Credentials > Backup Credentials > Cloud Credentials click Add and open the Provider dropdown list.
You must have all system storage (pool and datasets or zvols) configured and ready to receive or send data.
To create your cloud sync task for a Storj-TrueNAS transfer you:
Create the SCALE cloud credential.
Adding the cloud credential in SCALE includes using the link to go create the Storj-TrueNAS account, create a new bucket and obtain the S3 authentication credentials you need to complete the process in SCALE.
Create the Storj-TrueNAS account.
You must create the new Storj-TrueNAS account to use SCALE to access a Storj account.
Add a new Storj bucket.
Create Storj S3 access for the new bucket.
Finish creating the SCALE cloud credential using the S3 access and secret keys provided by Storj.
Create the cloud sync task for one bucket.
In this section you add your cloud service credentials in SCALE and in Storj. This process includes going to Storj to create a new Storj-TrueNAS account and returning to SCALE to enter the S3 credentials provided by Storj for this credential.
Go to Credentials > Backup Credentials and click Add on the Cloud Credentials widget. The Add Cloud Credential screen opens with Storj displayed as the default provider in the Provider field.
Enter a descriptive name you want to identify this credential in the Name field.
Click Signup for account to create your Stor-TrueNAS account. This opens the Storj new account screen for TrueNAS.
You must use this link to create your Storj account to take advantage of the benefits of the Storj-TrueNAS pricing!
After setting up your Storj-TrueNAS account, create your Storj bucket and create the Storj S3 access for the new bucket.
Enter the authentication information provided but Storj in the Acces Key ID and Secret Access Key fields.
Click Verify Credentials, and wait for the system to verify the credentials.
Click Save.
After completing this configuration form, you can set up the cloud sync task.
Click Signup for account on the Add Cloud Credential screen. The Storj Sign In website opens.
Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, then click Create an Ix-Storj Account.
Now add the storage bucket to use in your Storj-TrueNAS account and to add in the SCALE cloud sync task.
From the Storj main dashboard:
Click Buckets on the navigation panel on the left side of the screen to open the Buckets screen.
Click New Bucket to open the Create a bucket window.
Enter a name in Bucket Name using lower case alphanumeric characters, with no spaces between characters, then click Continue to open the Encrypt your bucket window.
Select the encryption option you want to use. Select Generate passphrase to let Storj provide the encryption or select Enter Passphrase to enter your own. If you already have a Storj account and want to use the same passphrase for your new bucket, select Enter Passphrase.
If you select Generate a passphrase Storj presents you with the option to download the encryption keys. You must keep encryption keys stored in a safe place, and where you can back up the file. Select I understand, and I have saved the passphrase then click Download.
Click Continue to complete the process and open the Buckets screen with your new bucket.
After creating your bucket, add S3 access for the new bucket(s) you want to use in your Storj-TrueNAS account and use in the SCALE cloud sync task.
Click Access to open the** Access Management** dashboard, then click Create S3 Credentials on the middle S3 credentials widget.
The Create Access window opens with Type set to S3 Credentials.
Enter the name you want to use for this credential. Our example uses the name of the bucket we created.
Select the permissions you want to allow this access from the Permissions dropdown and select the bucket you want to have access to this credential from the dropdown list. The example selects All for Permissions and selected the one bucket we created ixstorj1.
If you want to use the SCALE option to add new buckets in SCALE, set Storj Permissions to All and Buckets to All.
Select Add Date (optional) if you want to set the duration or length of time you want to allow this credential to exist. This example set this to Forever. You can select a preset period of time or use the calendar to set the duration.
Click Encrypt My Access to open the Encryption Information dialog, then click Continue to open theSelect Encryption options window.
Select the encryption option you want to use. Select Generate Passphrase to allow Storj to provide the encryption passphrase, or select Create My Own Passphrase to enter a passphrase of your choice.
Use Copy to Clipboard or Download.txt to obtain the Storj generated passphrase. Keep this passphrase along with the access keys in a safe place where you can back up the file.
If you lose your passphrase neither Storj or iXsystems can help you recover your stored data!
7 . Click Create my Access to obtain the access and secret keys. Use Download.txt to save these keys to a text file.
This completes the process of setting up your Storj buckets and S3 access. Enter these keys in the Authentication fields in TrueNAS SCALE on the Add Cloud Credential screen to complete setting up the SCALE cloud credential.
To add the Storj cloud sync task, go to Data Protection > Cloud Sync Tasks:
Click Add to open the Add Cloud Sync Task screen.
(Required) Type a memorable task description in Description. You can use the the name of the Storj-TrueNAS bucket or credential you created as the name of the cloud sync task.
Select the Storj credential you just created from the Credential dropdown list.
Set the Direction and Transfer Mode you want to use.
Browse to the dataset or zvol you want to use on SCALE for data storage.
Select the bucket you just created in Storj from the Bucket dropdown list.
If you set the Storj S3 access to only apply to the new bucket created in Storj, you can only use that bucket, selecting Add New results in an error. If you set the Storj S3 Bucket access to All you can either select the new bucket you created in Storj or Add New to create a new Storj bucket here in SCALE!
Set the task schedule when you want this task to run.
Click Save.
The task is added to the Cloud Sync Task widget with the Pending status until the task runs on schedule. You can click Dry Run to test the task or Run Now to run the task now and apart from the scheduled time.
Google Photos works best in TrueNAS using a Google Photos API key and rclone token.
On the Google API dashboard, click the dropdown menu next to the Google Cloud logo and select your project. If you do not have a project, click NEW PROJECT and enter a value in Project name, Organization, and Location.
After you select your project, click Enabled APIs & Services on the left menu, then click + ENABLE APIS AND SERVICES.
Enter photos library api in the search bar, then select Photos Library API and click ENABLE.
Next, click OAuth consent screen on the left menu, select EXTERNAL, then click CREATE.
Enter a value in App name and User support email.
Enter an email address in the Developer contact information section, then click SAVE AND CONTINUE.
Continue to the Add users section, enter your email address, then click ADD.
On the OAuth consent screen, click PUBLISH APP under Testing and push the app to production.
Click Credentials on the left menu, then click + CREATE CREDENTIALS and select OAuth client ID.
Select Desktop app in the Application type dropdown, then enter a name for the client ID and click CREATE.
Copy and save your client ID and secret, or download the JSON file.
Download rclone for your OS and open it in a command line utility. The example photos in this article use Powershell in Windows OS.
Enter rclone config
, then enter n
to create a new remote.
Enter a name for the new remote, then enter the number from the list corresponding to Google Photos.
Enter the client id and secret you saved when you created the Google Photos API credentials, then enter false
to keep the Google Photos backend read-only.
Do not edit the advanced config. When prompted about automatically authenticating rclone with the remote, enter y
.
A browser window opens to authorize rclone access. Click Allow.
In the command line, enter y
when prompted about media item resolution to complete the configuration.
Copy and save the type, client_id, client_secret, and token, then enter y
to keep the new remote.
Open your TrueNAS Web UI. Go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
Select Google Photos as the Provider and enter a name.
Do not click Log In To Provider.
Paste the Google Photos API client ID and client secret in the OAuth Client ID and OAuth Client Secret fields.
Paste your rclone token into the Token field.
Click Verify Credential to ensure you filled out the fields correctly, then click Save.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Add Cloud Sync Task configuration screen opens.
(Required) Type a memorable task description in Description.
Select an existing backup credential from the Credential dropdown list. If you have not added the cloud credential, click Manage Credentials to open the Backup Credentials screen.
Select the option from Direction and in Transfer Mode.
Select the dataset location in Directory/Files.
Cloud provider settings change based on the credential you select. Select or enter the required settings that include where files are stored.
Select the time from the Schedule options.
Click Save to add the task.
You can use Dry Run to test your configuration before you click Save or select the option on the Cloud Sync Task widget after you click Save.
You often need to copy data to another system for backup or when migrating to a new system. A fast and secure way of doing this is by using rsync with SSH.
For a remote sync (rsync) task to work you need to first:
Create a dataset on the TrueNAS
When the Rsync Mode is SSH, go to System Settings > Services and enable SSH. Create an SSH connection in Credentials > Backup Credentials > SSH Connections.
When the Rsync Mode is Module, record the host and path to the data on the remote system you plan to sync with.
Rsync provides the ability to either push or pull data. The Push direction copies data from TrueNAS to a remote system. The Pull function moves or copies data from a remote system and stores it in the defined Path on the TrueNAS host system.
When the remote system is another TrueNAS, set the Rsync Mode to SSH, verify the SSH service is active on both systems, and ensure SSH keys are exchanged between systems. When the remote system is not TrueNAS, make sure that system has the rsync service activated and permissions configured for the user account name that TrueNAS will use to run the rsync task.
Go to Data Protection > Rsync Tasks and click Add to open the Add Rsync Task configuration screen.
Enter or use the
to the left of /mnt to browse to the path to copy.Begin typing the user into the User field or select the user from the dropdown list. The user must have permissions to run an rsync on the remote server.
Select the direction. Select Pull to copy from the remote server to TrueNAS, or Push to copy from TrueNAS to the remote server.
Enter the remote host name or IP in Remote Host. You need to have the remote server rsync service configured and turned on.
Select the connection mode from the Rsync Mode dropdown. Each mode option displays settings for the selected type. You need to have either a rsync module configured in a remote rsync server or an SSH connection for the remote server already configured.
Set the schedule for when to run this task, and any other options you want to use. If you need a custom schedule, select Custom to open the advanced scheduler window.
Click Save.First, enable SSH on the remote system. Next enable SSH in TrueNAS; go to System > Services and toggle SSH on.
Now set up an SSH connection to the remote server. You can do this in Credentials > Backup Credentials using SSH Connections and SSH Keypairs, or using System Settings > Shell and TrueNAS CLI commands. To use the UI, see Adding SSH connections. Populate the SSH Connections configuration fields as follows:
Semi-Automatic (TrueNAS to TrueNAS)
Manual (TrueNAS to Non-TrueNAS)
After establishing the SSH connection, add the rsync task.
Before you create an rsync task on the host system, you must create a module on the remote system. You must define at least one module in rsyncd.conf(5) of the rsync server or in the rsync modules of another system. When TrueNAS is the remote system, create a module in System Settings > Services > Rsync on the Rsync Modules screen. See Configuring an Rsync Module for more information.
Clear the Enabled checkbox to disable the task schedule without deleting the configuration. You can still run the rsync task by going to Data Protection > Rsync Tasks and clicking then the Run Now play_arrow icon.
Periodic snapshot tasks allow you to schedule creating read-only versions of pools and datasets at a given point in time. You can also access VMWare snapshot integration and TrueNAS SCALE storage snapshots from the Periodic Snapshot Tasks widget.
Create the required datasets or zvols before creating a snapshot task.
Go to Data Protection > Periodic Snapshot Tasks and click Add.
First, choose the dataset (or zvol) to schedule as a regular backup with snapshots, and how long to store the snapshots.
Next, define the task Schedule. If you need a specific schedule, choose Custom and use the Advanced Scheduler section below.
Configure the remaining options for your use case. For help with naming schema and lifetime settings refer to the sections below.
Click Save to save this task and add it to the list in Data Protection > Periodic Snapshot Tasks.
You can find any snapshots taken using this task in Storage > Snapshots.
To check the log for a saved snapshot schedule, go to Data Protection > Periodic Snapshot Tasks and click on the task. The Edit Periodic Snapshot Tasks screen displays where you can modify any settings for the task.
The Naming Schema determines how automated snapshot names generate. A valid schema requires the %Y (year), %m (month), %d (day), %H (hour), and %M (minute) time strings, but you can add more identifiers to the schema too, using any identifiers from the Python strptime function.
For Periodic Snapshot Tasks used to set up a replication task with the Replication Task function:
You can use custom naming schema for full backup replication tasks. If you are going to use the snapshot for an incremental replication task, use the default naming schema.
This uses some letters differently from POSIX (Unix) time functions.
For example, including %z
(time zone) ensures that snapshots do not have naming conflicts when daylight time starts and ends, and %S (second) adds finer time granularity.
Examples:
Naming Scheme | Snapshot Names Look Like |
---|---|
replicationsnaps-1wklife-%Y%m%d_%H:%M | replicationsnaps-1wklife-20210120_00:00 , replicationsnaps-1wklife-20210120_06:00 |
autosnap_%Y.%m.%d-%H.%M.%S-%z | autosnap_2021.01.20-00.00.00-EST , autosnap_2021.01.20-06.00.00-EST |
When referencing snapshots from a Windows computer, avoid using characters like colon (:) that are invalid in a Windows file path. Some applications limit filename or path length, and there might be limitations related to spaces and other characters. Always consider future uses and ensure the name given to a periodic snapshot is acceptable.
TrueNAS deletes snapshots when they reach the end of their life and preserves snapshots when at least one periodic task requires it. For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for 3 years. Each has an hourly snapshot taken. After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task. These snapshots get destroyed at the end of 3 years.
You must power on virtual machines for TrueNAS to copy snapshots to VMware. The temporary VMware snapshots deleted on the VMware side still exist in the ZFS snapshot and are available as stable restore points. These coordinated snapshots go in the VMware Snapshots list.
Use this procedure to create ZFS snapshots when using TrueNAS SCALE as a VMWare datastore. VMware Snapshots coordinate ZFS snapshots when using TrueNAS as a VMware datastore. When creating a ZFS snapshot, TrueNAS SCALE automatically takes a snapshot of any running VMWare virtual machine before taking a scheduled or manual ZFS snapshot of the data or zvol backing that VMWare datastore.
You must have a paid edition of VMWare ESXi to use the TrueNAS SCALE VMWare Snapshots feature. If you try to use them with the free-edition of VMware ESXi, you see this error message: “Error, Can’t create snapshot, current license or ESXi version prohibits execution of the requested operation.” ESXi free has a locked (read-only) API that prevents using TrueNAS SCALE VMWare Snapshots. The cheapest ESXi edition that is compatible with TrueNAS VMware Snapshots is VMWare vSphere Essentials Kit.
Go to Data Protection and click the VMware Snapshot Integration button in the Periodic Snapshot Tasks widget.
Click the Add button to configure the VMWare Snapshot Task.
You must follow the exact sequence to add the VMware snapshot or the ZFS Filesystem and Datastore fields do not populate with options available on your system. If you click in ZFS Filestore* or Datastores before you click Fetch Datastores the creation process fails, the two fields do not populate with the information from the VMWare host and you must exit the add form or click Cancel and start again.
Enter the IP address or host name for your VMWare system in Hostname.
Enter the user on the VMware host with permission to snapshot virtual machine for VMWare in Username and the the password for that account in Password.
Click Fetch Datastores. This connects TrueNAS SCALE to the VMWare host and populates the ZFS Filesystem and Datastore dropdown fields with the host response.
Select the file system from the ZFS Filesystem dropdown list of options.
Select the datastore from the Datastore dropdown list of options.
Click Save.
You must power on virtual machines before you can copy TrueNAS SCALE snapshots to VMWare.
The temporary VMWare snapshots deleted on the VMWare side still exist in the ZFS snapshot and are available as stable restore points. These coordinated snapshots go on the list found by clicking VMware Snapshot Integration in the Data Protection > Periodic SnapShot Tasks widget.
S.M.A.R.T. or Self-Monitoring, Analysis and Reporting Technology is a standard for disk monitoring and testing. You can monitor disks for problems using different kinds of self-tests. TrueNAS can adjust when it issues S.M.A.R.T. alerts. When S.M.A.R.T. monitoring reports a disk issue, we recommend you replace that disk. Most modern ATA, IDE, and SCSI-3 hard drives support S.M.A.R.T. Refer to your respective drive documentation for confirmation.
TrueNAS runs S.M.A.R.T. tests on disks. Running tests can reduce drive performance, so we recommend scheduling tests when the system is in a low-usage state. Avoid scheduling disk-intensive tests at the same time! For example, do not schedule S.M.A.R.T. tests on the same day as a disk scrub or other data protection task.
To test one or more disk for errors, go to Storage and click the Disks button.
Select the disks you want to test using the checkboxes to the left of the disk names. Selecting multiple disks displays the Batch Operations options.
Click Manual Test. The Manual S.M.A.R.T. Test dialog displays.
Manual S.M.A.R.T. tests on NVMe devices is currently not supported.
Next, select the test type from the Type dropdown and then click Start.
Test types differ based on the drive connection, ATA or SCSI. Test duration varies based on the test type you chose. TrueNAS generates alerts when tests discover issues.
The ATA drive connection test type options are:
For more information, refer to smartctl(8).
To schedule recurring S.M.A.R.T. tests, go to Data Protection and click ADD in the S.M.A.R.T. Tests widget.
Select the disks to test from the Disks dropdown list, and then select the test type to run from the Type dropdown list.
Next select a preset from the Schedule dropdown. To create a custom schedule select Custom to open the advanced scheduler window where you can define the schedule parameters you want to use.
Saved schedules appear in the S.M.A.R.T. Tests window.
S.M.A.R.T. tests can offline disks! Avoid scheduling S.M.A.R.T. tests simultaneously with scrub or other data protection tasks.
Start the S.M.A.R.T. service. Go to System Settings > Services and scroll down to the S.M.A.R.T. service. If not running, click the toggle to turn the service on. Select Start Automatically to have this service start after after the system reboots.
If you have not configured the S.M.A.R.T. service yet, while the service is stopped, click edit to open the service configuration form. See Services S.M.A.R.T. Screen for more information on service settings. Click Save to save settings and return to the Services screen.
TrueNAS SCALE replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their SCALE system as a way to back up stored data. When properly configured and scheduled, replication takes regular snapshots of storage pools or datasets and saves them in the destination location either on the same system or a different system.
Local replication occurs on the same TrueNAS SCALE system using different pools or datasets. Remote replication can occur between your TrueNAS SCALE system and another TrueNAS system, or with some other remote server you want to use to store your replicated data. Local and remote replication can involve encrypted pools or datasets.
With the implementation of rootless login and the admin user, setting up replication tasks as an admin user has a few differences than with setting up replication tasks when logged in as root. Each of the tutorials in this section include these configuration differences.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps to take prior to configuring a replication task.
A local replication creates a zfs snapshot and saves it to another location on the same TrueNAS SCALE system either using a different pool, or dataset or zvol. This allows users with only one system to take quick data backups or snapshots of their data when they have only one system. In this scenario, create a dataset on the same pool to store the replication snapshots. You can create and use a zvol for this purpose. If configuring local replication on a system with more than one pool, create a dataset to use for the replicated snapshots on one of those pools.
While we recommend regularly scheduled replications to a remote location as the optimal backup scenario, this is useful when no remote backup locations are available, or when a disk is in immediate danger of failure.
Storage space you allocate to a zvol is only used by that volume, it does not get reallocated back to the total storage capacity of the pool or dataset where you create the zvol if it goes unused. Plan your anticipated storage need before you create the zvol to avoid creating a zvol that exceeds your storage needs for this volume. Do not assign capacity that exceeds what is required for SCALE to operate properly. For more information, see SCALE Hardware Guide for CPU, memory and storage capacity information.
With the implementation of rootless login and the admin user, setting up replication tasks as an admin user has a few differences over setting up replication tasks when logged in as root.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
Replication tasks require a periodic snapshot task. The earlier releases of SCALE required creating a periodic snapshot task before the replication task, but SCALE 22.12 and newer automatically creates the snapshot task when a scheduled replication task starts. To start a replication task using the Run Now option on the Replication Task widget or by selecting Run Once in the Replication Task Wizard, create a periodic snapshot task first.
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps you should take prior to configuring a replication task.
The replication wizard allows users to create and copy ZFS snapshots to another location on the same system.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make change such as assigning it a different destination, schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard.
Before you begin configuring the replication task, first verify the destination dataset you want to use to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
To create a replication task:
Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS SCALE system, create a dataset in one of your pools.
Verify the admin user home directory, auxiliary groups, and sudo setting on both the local and remote destination systems. Local replication does not require an SSH connection so this only applies to replication to another system.
If using a TrueNAS CORE system as the remote server, the remote user is always root.
If using a TrueNAS SCALE system on an earlier release like Angelfish, the remote user is always root.
If using an earlier TrueNAS SCALE Bluefin system (22.12.1) or you installed SCALE as the root user, then created the admin user after initial installation, you must verify the admin user is correctly configured.
Go to Data Protection and click Add on the Replication Tasks widget to open the Replication Task Wizard. Configure the following settings:
a. Select On this System on the Source Location dropdown list. Browse to the location of the pool or dataset you want to replicate and select it so it populates Source with the path. Selecting Recursive replicates all snapshots contained within the selected source dataset snapshots.
b. Select On this System on the Destination Location dropdown list. Browse to the location of the pool or dataset you want to use to store replicated snapshots and select it so it populates the Destination with the path.
c. (Optional) Enter a name for the snapshot in Task Name. SCALE populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in destination dataset a challenge. To make it easier to find the snapshot, give it name easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to display the scheduling options.
Select the schedule and snapshot retention life time.
a. Select the Replication Schedule radio button you want to use. Select Run Once to set up a replication task you run one time. Select Run On a Schedule then select when from the Schedule dropdown list.
b. Select the Destination Snapshot Lifetime radio button option you want to use. This specifies how long SCALE should store copied snapshots in the destination dataset before SCALE deletes it. Same as Source is selected by default. Select Never Delete to keep all snapshots until you delete them manually. Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click START REPLICATION. A dialog displays if this is the first snapshot taken using the destination dataset. If SCALE does not find a replicated snapshot in the destination dataset to use to create an incremental snapshot, it deletes any existing snapshots found and creates a full copy of the day snapshot to use as a basis for the future scheduled incremental snapshots for this schedule task. This operation can delete important data, so ensure you can delete any existing snapshots or back them up in another location.
Click Confirm, then Continue to add the task to the Replication Task widget. The newly added task shows the status as PENDING until it runs on the schedule you set.
Select Run Now if you want to run the task immediately.
To see a log for a task, click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset. Click Show extra columns to add more information columns to the table such as the date created which can help you locate a specific snapshot or enter part of or the full the name in the search field to narrow the list of snapshots.
TrueNAS SCALE replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their SCALE system as a way to back up stored data. When properly configured and scheduled, remote replication takes take regular snapshots of storage pools or datasets and saves them in the destination location on another system.
Remote replication can occur between your TrueNAS SCALE system and another TrueNAS system (SCALE or CORE) where you want to use to store your replicated snapshots.
With the implementation of rootless login and the admin user, setting up replication tasks as an admin user has a few differences than with setting up replication tasks when logged in as root. Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
Replication tasks require a periodic snapshot task. The earlier releases of SCALE required creating a periodic snapshot task before the replication task, but SCALE 22.12 and newer automatically creates the snapshot task when a scheduled replication task starts. To start a replication task using the Run Now option on the Replication Task widget or by selecting Run Once in the Replication Task Wizard, create a periodic snapshot task first.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps you should take prior to configuring a replication task.
To streamline creating simple replication tasks use the Replication Task Wizard to create and copy ZFS snapshots to another system. The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make change such as assigning it a different destination, schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard. This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify the destination dataset you want to use to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
To create a replication task:
Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS SCALE system, create a dataset in one of your pools.
Verify the admin user home directory, auxiliary groups, and sudo setting on both the local and remote destination systems. Local replication does not require an SSH connection so this only applies to replication to another system.
If using a TrueNAS CORE system as the remote server, the remote user is always root.
If using a TrueNAS SCALE system on an earlier release like Angelfish, the remote user is always root.
If using an earlier TrueNAS SCALE Bluefin system (22.12.1) or you installed SCALE as the root user, then created the admin user after initial installation, you must verify the admin user is correctly configured.
Go to Data Protection and click Add on the Replication Tasks widget to open the Replication Task Wizard. Configure the following settings:
a. Select either On this System or On a Different System on the Source Location dropdown list.
If your source is a remote system, select On a Different System. The Destination Location automatically changes to On this System.
If your source is the local TrueNAS SCALE system, you must select On a Different System from the Destination Location dropdown list to do remote replication.
TrueNAS shows the number snapshots available for replication.
b. Select an existing SSH connection to the remote system, or select Create New to open the New SSH Connection configuration screen.
c. Browse to the source pool/dataset(s), then click on the dataset(s) to populate the Source with the path. You can select multiple sources or manually type the names into the Source field. Selecting Recursive replicates all snapshots contained within the selected source dataset snapshots.
d. Repeat to populate the Destination field. You cannot use zvols as a remote replication destination. Add a name to the end of the path to create a new dataset in that location.
e. Select Use Sudo for ZFS Commands. Only displays when logged in as the admin user (or the name of the admin user).
This removes the need to issue the cli zfs allow
command in Shell on the remote system.
When the dialog displays, click Use Sudo for ZFS Comands. If you close this dialog, select the option on the Add Replication Task wizard screen.
f. Select Replicate Custome Snapshots, then leave the default value in Naming Schema. If you know how to enter the schema you want, enter it in Naming Schema. Remote sources require entering a snapshot naming schema to identify the snapshots to replicate. A naming schema is a pattern of naming custom snapshots you want to replicate. Enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Separate entries by pressing Enter. The number of snapshots matching the patterns display.
g. (Optional) Enter a name for the snapshot in Task Name. SCALE populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in destination dataset a challenge. To make it easier to find the snapshot, give it name easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to display the scheduling options.
Select the schedule and snapshot retention life time.
a. Select the Replication Schedule radio button you want to use. Select Run Once to set up a replication task you run one time. Select Run On a Schedule then select when from the Schedule dropdown list.
b. Select the Destination Snapshot Lifetime radio button option you want to use. This specifies how long SCALE should store copied snapshots in the destination dataset before SCALE deletes it. Same as Source is selected by default. Select Never Delete to keep all snapshots until you delete them manually. Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click START REPLICATION. A dialog displays if this is the first snapshot taken using the destination dataset. If SCALE does not find a replicated snapshot in the destination dataset to use to create an incremental snapshot, it deletes any existing snapshots found and creates a full copy of the day snapshot to use as a basis for the future scheduled incremental snapshots for this schedule task. This operation can delete important data, so ensure you can delete any existing snapshots or back them up in another location.
Click Confirm, then Continue to add the task to the Replication Task widget. The newly added task shows the status as PENDING until it runs on the schedule you set.
Select Run Now if you want to run the task immediately.
To see a log for a task, click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset. Click Show extra columns to add more information columns to the table such as the date created which can help you locate a specific snapshot or enter part of or the full the name in the search field to narrow the list of snapshots.
For information on replicating encrypted pools or datasets, see Setting Up a Encrypted Replication Task.
When using a TrueNAS system on a different release, like CORE or SCALE Angelfish, the remote or destination system user is always root.
To configure a new SSH connection from the Replication Task Wizard:
Select Create New on the SSH Connection dropdown list to open the New SSH Connection configuration screen.
Enter a name for the connection.
Select the Setup Method from the dropdown list. If a TrueNAS system, select Semi-Automatic.
Enter the URL to the remote TrueNAS in TrueNAS URL.
Enter the administration user (i.e., root or admin) that logs into the remote system with the web UI in Admin Username. Enter the password in Admin Password.
Enter the administration user (i.e., root or admin) for remote system SSH session. If you clear root as the the user and type any other name the Enable passwordless sudo for ZFS commands option displays. This option does nothing so leave it cleared.
Select Generate New from the Private Key dropdown list.
(Optional) Select a cipher from the dropdown list, or enter a new value in seconds for the Connection Timeout if you want to change the defaults.
Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.
Using encryption for SSH transfer security is always recommended.
In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer. However, the data is completely unprotected from eavesdropping.
Choosing No Encryption for the task is less secure but faster. This method uses common port settings, but you can override these by switching to the Advanced Replication Creation options or by editing the task after creation.
TrueNAS SCALE advanced replication tasks allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their SCALE system as a way to back up stored data. When properly configured and scheduled, advanced replication takes regular snapshots of storage pools or datasets and saves them in the destination location either on the same system or a different system.
Local replication occurs on the same TrueNAS SCALE system using different pools or datasets. Remote replication can occur between your TrueNAS SCALE system and another TrueNAS system, or with some other remote server you want to use to store your replicated data. Local and remote replication can involve encrypted pools or datasets.
With the implementation of rootless login and the admin user, setting up replication tasks as an admin user has a few differences than with setting up replication tasks when logged in as root. Each of the tutorials in this section include these configuration differences.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
TrueNAS SCALE advanced replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their SCALE system as a way to back up stored data. When properly configured and scheduled, local or remote replication using the Advanced Replication Creation option takes take regular snapshots of storage pools or datasets and saves them in the destination location on the same or another system.
The Advanced Replication Creation option opens the Add Replication Task screen. This screen provides access to the same settings found in the repliation wizard but has more options to specify:
You can also:
With the implementation of rootless login and the admin user, setting up replication tasks as an admin user has a few differences than with setting up replication tasks when logged in as root. Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
Replication tasks require a periodic snapshot task. The earlier releases of SCALE required creating a periodic snapshot task before the replication task, but SCALE 22.12 and newer automatically creates the snapshot task when a scheduled replication task starts. To start a replication task using the Run Now option on the Replication Task widget or by selecting Run Once in the Replication Task Wizard, create a periodic snapshot task first.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps you should take prior to configuring a replication task.
Configure your SSH connection before you begin configuring the replication task through the Add Replication Task screen. If you have an existing SSH connection with the remote system the option displays on the SSH Connection dropdown list.
Turn on SSH service. Go to System Settings > Services screen, verify the SSH service configuration, then enable it.
To access advanced replication settings, click Advanced Replication Creation at the bottom of the first screen of the Replication Task Wizard. The Add Replication Task configuration screen opens.
Before you begin configuring the replication task, first verify the destination dataset you want to use to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
To create a replication task:
Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS SCALE system, create a dataset in one of your pools.
Verify the admin user home directory, auxiliary groups, and sudo setting on both the local and remote destination systems. Local replication does not require an SSH connection so this only applies to replication to another system.
If using a TrueNAS CORE system as the remote server, the remote user is always root.
If using a TrueNAS SCALE system on an earlier release like Angelfish, the remote user is always root.
If using an earlier TrueNAS SCALE Bluefin system (22.12.1) or you installed SCALE as the root user, then created the admin user after initial installation, you must verify the admin user is correctly configured.
Give the task a name and set the direction of the task. Unlike the wizard, the Name does not automatically populate with the source/destination task name after you set the source and destination for the task. Each task name must be unique, and we recommend you name it in a way that makes it easy to remember what the task is doing.
Select the direction of the task. Pull replicates data from a remote system to the local system. Push sends data from the local system to the remote.
Select the method of tranfer for this replication from the Transport dropdown list. Select LOCAL to replicate data to another location on the same system. Select SSH is the standard option for sending or receiving data from a remote system. Select the existing SSH Connection from the dropdown list. Select SSH+Netcat is available as a faster option for replications that take place within completely secure networks. SSH+Netcat requires defining netcat ports and addresses to use for the Netcat connection.
With SSH-based replications, select the SSH Connection to the remote system that sends or receives snapshots. To create a new connection to use for replication from a destination to this local system, select newpullssh.
Select Use Sudo for Zfs Commands to controls whether the user used for SSH/SSH+NETCAT replication has passwordless sudo enabled to execute zfs commands on the remote host.
If not selected, you must enter zfs allow
on the remote system to to grant non-user permissions to perform ZFS tasks.
Specify the source and destination paths. Adding /name to the end of the path creates a new dataset in that location. Click the arrow to the left of each folder or dataset name to expand the options and browse to the dataset, then click on the dataset to populate the Source. Choose a preconfigured periodic snapshot task as the sorce of snapshots to replicate. Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories.
A remote destination requires you to specify an SSH connection before you can enter or select the path. If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and configure it to allow SSH connections. Define how long to keep snapshots in the destination.
Remote sources require defining a snapshot naming schema to identify the snapshots to replicate. Local sources are replicated by snapshots that were generated from a periodic snapshot task and/or from a defined naming schema that matches manually created snapshots.
DO NOT use zvols as remote destinations.
Select a previously configured periodic snapshot task for this replication task in Periodic Snapshot Tasks. The replication task selected must have the same values in Recursive and Exclude Child Datasets as the chosen periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
If a periodic snapshot task does not exist, select Replicate Specfic Snapshots tp define specific snapshots from the periodic task to use for the replication. This displays the schedule options for the snapshot task. Enter the schedule. The only periodically generated snapshots included in the replication task are those that match your defined schedule.
Select the naming schema or regular exression option to use for this snapshot.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema custom-%Y-%m-%d_%H-%M
finds and replicates snapshots like custom-2020-03-25_09-15
.
Enter multiple schemas by pressing Enter to separate each schema.
Set the replication schedule to use and define when the replication task runs. Leave Run Automatically selected to use the snapshot task specified and start the replication immediately after the related periodic snapshot task completes. Select Schedule to display scheduling options for this replication task and To automate the task according to its own schedule.
Selecting Schedule allows scheduling the replication to run at a separate time. Choose a time frame that gives the replication task enough time to finish and is during a time of day when network traffic for both source and destination systems is minimal. Use the custom scheduler (recommended) when you need to fine-tune an exact time or day for the replication.
Click Save.
Options for compressing data, adding a bandwidth limit, or other data stream customizations are available. Stream Compression options are only available when using SSH. Before enabling Compressed WRITE Records, verify that the destination system also supports compressed write records.
Allow Blocks Larger than 128KB is a one-way toggle. Replication tasks using large block replication only continue to work as long as this option remains enabled.
By default, the replication task uses snapshots to quickly transfer data to the receiving system. Selecting Full Filesystem Replication means the task completely replicates the chosen Source, including all dataset properties, snapshots, child datasets, and clones. When using this option, we recommended allocating additional time for the replication task to run.
Leave Full Filesystem Replication unselected and select Include Dataset Properties to include just the dataset properties in the snapshots to replicate. Leave this option unselected on an encrypted dataset to replicate the data to another unencrypted dataset.
Select Recursive to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
Enter newly defined properties in Properties Override to replace existing dataset properties with the newly defined properties in the replicated files.
List any existing dataset properties to remove from the replicated files in Properties Exclude.
When a replication task is having difficulty completing, it is a good idea to select Save Pending Snapshots. This prevents the source TrueNAS from automatically deleting any snapshots that failed to replicate to the destination system.
By default, the destination dataset is set to be read-only after the replication completes. You can change the Destination Dataset Read-only Policy to only start replication when the destination is read-only (set to REQUIRE) or to disable it by setting it to IGNORE.
The Encryption option adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system. Selecting Encryption adds the addtional setting options HEX key or PASSPHRASE. You can store the encryption key either in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots. TrueNAS also does a full replication of the source snapshots as if the replication task never run, which can lead to excessive bandwidth consumption.
This can be a very destructive option. Make sure that any snapshots deleted from the destination are obsolete or otherwise backed up in a different location.
Defining the Snapshot Retention Policy is generally recommended to prevent cluttering the system with obsolete snapshots. Choosing Same as Source keeps the snapshots on the destination system for the same amount of time as the defined Snapshot Lifetime from the source system periodic snapshot task.
You can use Custom to define your own lifetime for snapshots on the destination system.
Selecting Only Replicate Snapshots Matching Schedule restricts the replication to only replicate those snapshots created at the same time as the replication schedule.
TrueNAS SCALE replication allows users to create replicated snapshots of data stored in encrypted pools, datasets or zvols that on their SCALE system as a way to back up stored data to a remote system. You can use encrypted datasets in a local replication.
You can set up a replication task for a dataset encrypted with a passphrase or a hex encryption key, but you must unlock the dataset before the task runs or the task fails.
With the implementation of rootless login and the admin user, when setting up remote replication tasks when logged in as an admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
Replication tasks require a periodic snapshot task. The earlier releases of SCALE required creating a periodic snapshot task before the replication task, but SCALE 22.12 and newer automatically creates the snapshot task when a scheduled replication task starts. To start a replication task using the Run Now option on the Replication Task widget or by selecting Run Once in the Replication Task Wizard, create a periodic snapshot task first.
Remote replication with datasets also require an SSH connection in TrueNAS. You can use an existing SSH connection if it has the same user credentials you want to use for the new replication task.
This section provides a simple overview of setting up a remote replication task for an encrypted dataset. It also covers the related steps you should take prior to configuring the replication task.
To streamline creating simple replication tasks use the Replication Task Wizard to create and copy ZFS snapshots to another system. The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.
If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make change such as assigning it a different destination, select encryption options, schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard. This saves some time when creating multiple replication tasks between the same two systems.
Before you begin configuring the replication task, first verify the destination dataset you want to use to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.
To create a replication task:
Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS SCALE system, create a dataset in one of your pools.
Verify the admin user home directory, auxiliary groups, and sudo setting on both the local and remote destination systems. Local replication does not require an SSH connection so this only applies to replication to another system.
If using a TrueNAS CORE system as the remote server, the remote user is always root.
If using a TrueNAS SCALE system on an earlier release like Angelfish, the remote user is always root.
If using an earlier TrueNAS SCALE Bluefin system (22.12.1) or you installed SCALE as the root user, then created the admin user after initial installation, you must verify the admin user is correctly configured.
Unlock the source dataset and export the encryption key to a text editor such as Notepad. Go to Datasets select the source dataset, locate the ZFS Encryption widget and unlock the dataset if locked. Export the key and paste it in any text editor such as Notepad. If you set up encryption to use a passphrase, you do not need to export a key.
Go to Data Protection and click Add on the Replication Tasks widget to open the Replication Task Wizard. Configure the following settings:
a. Select On this System on the Source Location dropdown list. If your source is the local TrueNAS SCALE system, you must select On a Different System from the Destination Location dropdown list to do remote replication.
If your source is a remote system, create the replication task as the root user and select On a Different System. The Destination Location automatically changes to On this System.
TrueNAS shows the number of snapshots available for replication.
b. Select an existing SSH connection to the remote system or create a new connection. Select Create New to open the New SSH Connection configuration screen.
c. Browse to the source pool/dataset(s), then click on the dataset(s) to populate the Source with the path. You can select multiple sources or manually type the names into the Source field. Separate multiple entries with commas. Selecting Recursive replicates all snapshots contained within the selected source dataset snapshots.
d. Repeat to populate the Destination field. You cannot use zvols as a remote replication destination. Add a /datasetname to the end of the destination path to create a new dataset in that location.
e. (Optional) Select Encryption to add a second layer of encryption over the already encrypted dataset.
f. Select Use Sudo for ZFS Commands. Only displays when logged in as the admin user (or the name of the admin user).
This removes the need to issue the cli zfs allow
command in Shell on the remote system.
When the dialog displays, click Use Sudo for ZFS Comands. If you close this dialog, select the option on the Add Replication Task wizard screen.
This option only displays when logged in as the admin user.
If not selected you need to issue the cli zfs allow
command in Shell on the remote system.
g. Select Replicate Custom Snapshots, then accept the default value in Naming Schema. Remote sources require entering a snapshot naming schema to identify the snapshots to replicate. A naming schema is a pattern of naming custom snapshots you want to replicate. If you want to change the default schema, enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Separate entries by pressing Enter. The number of snapshots matching the patterns display.
h. (Optional) Enter a name for the snapshot in Task Name. SCALE populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in destination dataset a challenge. To make it easier to find the snapshot, give it a name that is easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to display the scheduling options.
Select the schedule and snapshot retention life time.
a. Select the Replication Schedule radio button you want to use. Select Run Once to set up a replication task you run one time. Select Run On a Schedule then select when from the Schedule dropdown list.
b. Select the Destination Snapshot Lifetime radio button option you want to use. This specifies how long SCALE should store copied snapshots in the destination dataset before SCALE deletes it. Same as Source is selected by default. Select Never Delete to keep all snapshots until you delete them manually. Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.
Click START REPLICATION. A dialog displays if this is the first snapshot taken using the destination dataset. If SCALE does not find a replicated snapshot in the destination dataset to use to create an incremental snapshot, it deletes any existing snapshots found and creates a full copy of the day snapshot to use as a basis for the future scheduled incremental snapshots for this schedule task. This operation can delete important data, so ensure you can delete any existing snapshots or back them up in another location.
Click Confirm, then Continue to add the task to the Replication Task widget. The newly added task shows the status as PENDING until it runs on the schedule you set.
Select Run Now if you want to run the task immediately.
To see a log for a task, click the task State to open a dialog with the log for that replication task.
To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset. Click Show extra columns to add more information columns to the table such as the date created which can help you locate a specific snapshot or enter part of or the full the name in the search field to narrow the list of snapshots.
When using a TrueNAS system on a different release, like CORE or SCALE Angelfish, the remote or destination system user is always root.
To configure a new SSH connection from the Replication Task Wizard:
Select Create New on the SSH Connection dropdown list to open the New SSH Connection configuration screen.
Enter a name for the connection.
Select the Setup Method from the dropdown list. If a TrueNAS system, select Semi-Automatic.
Enter the URL to the remote TrueNAS in TrueNAS URL.
Enter the administration user (i.e., root or admin) that logs into the remote system with the web UI in Admin Username. Enter the password in Admin Password.
Enter the administration user (i.e., root or admin) for remote system SSH session. If you clear root as the the user and type any other name the Enable passwordless sudo for ZFS commands option displays. This option does nothing so leave it cleared.
Select Generate New from the Private Key dropdown list.
(Optional) Select a cipher from the dropdown list, or enter a new value in seconds for the Connection Timeout if you want to change the defaults.
Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.
Using encryption for SSH transfer security is always recommended.
In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer. However, the data is completely unprotected from eavesdropping.
Choosing No Encryption for the task is less secure but faster. This method uses common port settings, but you can override these by switching to the Advanced Replication Creation options or by editing the task after creation.
After the replication task runs and creates the snapshot on the destination, you must unlock it to access the data. Use the encryption key exported from the dataset or pool, or if you use a passphrase to lock the dataset, enter the passphrase to unlock the dataset on the remote destination system.
To replication an encrypted dataset to an unencrypted dataset on the remote destination system, follow the instructions above to configure the task, then:
Select the task on the Replication Task widget. The Edit Replication Task screen opens.
Scroll down to Include Dataset Properties and select it to clear the checkbox.
This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.
When you replicate an encrypted pool or dataset you have one level of encryption applied at the data storage level. Use the passphrase or key created or exported from the dataset or pool to unlock the dataset on the destination server.
To add a second layer of encryption at the replication task level, select Encryption, then select the type of encryption you want to apply.
Select either Hex (base-16 numeral format) or Passphrase (alphanumeric format) from the Encryption Key Format dropdown list to open settings for that type of encryption.
Selecting Hex displays Generate Encryption Key preselected. Select the checkbox to clear it and display the Encryption Key field where you can import a custom hex key.
Selecting Passphrase displays the Passphrase field where you enter your alphanumeric passphrase.
Select Store Encryption key in Sending TrueNAS database to store the encryption key in the sending TrueNAS database or leave unselected to choose a temporary location for the encryption key that decrypts replicated data.
TrueNAS SCALE users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.
Replicate every encrypted dataset you want to replicate with properties.
Export key for every child dataset that has a unique key.
For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
{"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}
Save this file with the extension
On the remote system, unlock the dataset(s) using properly constructed
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
Go to Data Protection and click ADD in the Replication Tasks window.
Click Advanced Replication Creation.
Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
Click Save.
Go to Datasets on the system you are replicating from. Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.
Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.
Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.
Option 2: Copy the key code provided in the Key for dataset window.
On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.
Unlock the dataset. Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.
Click Save.
Click Continue.
SCALE Credential options are collected in this section of the UI and organized into a few different screens:
Local Users allows those with permissions to add, configure, and delete users on the system. There are options to search for keywords in usernames, display or hide user characteristics, and toggle whether the system shows built-in users.
Local Groups allows those with permissions to add, configure, and delete user groups on the system. There are options to search for keywords in group names, display or hide group characteristics, and toggle whether the system shows built-in groups.
Directory Services contains options to edit directory domain and account settings, set up Idmapping, and configure access and authentication protocols. Specific options include configuring Kerberos realms and key tables (keytab), as well as setting up LDAP validation.
Backup Credentials stores credentials for cloud backup services, SSH Connections, and SSH Keypairs. Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
Certificates contains all the information for certificates, certificate signing requests, certificate authorities, and DNS-authenticators. TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
2FA allows users to set up Two-Factor Authentication for their system. Users can set up 2FA, then link the system to an authenticator app (such as Google Authenticator, LastPass Authenticator, etc.) on a mobile device.
The initial implementation of TrueNAS SCALE rootless log in permits users to use the root user but encourages users to create the local administrator account when first installing SCALE.
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create a local administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
A future update of TrueNAS SCALE will permanently disable root account access.
If migrating from CORE to SCALE, when first logging into SCALE as the root user, you are advised to create the administrator account. All users should create the local administrator account and use this account for web interface access. To improve system security after the local administrator account is created, disable the root account password so that root access to the system is restricted.
Some UI screens and settings still refer to the root account, but these references are updating to the administrator account in future release of SCALE.
At present, SCALE has both the root and local administrator user logins and passwords. If properly set up, the local administrator (admin) account performs the same functions and has the same access the root user has.
The root user is no longer the default user so you must add and enable a password to use the root user.
As a security measure, the root user password is disabled when you create the admin user during installation. Do not disable the admin account and root passwords at the same time. If both root and admin account passwords become disabled at the same time and the web interface session times out, a one-time sign-in screen allows access to the system.
Enter and confirm a password to gain access to the UI. After logging in, immediately go to Credentials > Local Users to enable either the root or admin password before the session times out again. This temporary password is not saved as a new password and it does not enable the admin or root passwords, it only provides one-time access to the UI.
When disabling a password for UI login, it is also disabled for SSH access.
To enable SSH to access the system as root or the admin user:
Configure the SSH service.
a. Go to System Settings > Services, then select Configure for the SSH service.
b. Select Log in as Root with Password to enable the root user to sign in as root.
Select Log in as Admin with Password and Allow Password Authentication to enable the admin user to sign in as admin. Select both options.
c. Click Save and restart the SSH service.
Configure or verify the user configuration options to allow ssh access.
If you want to SSH into the system as the root, you must create and enable a password for the root user. If the root password password is disabled in the UI you cannot use it to gain SSH access to the system.
To allow the admin user to issue commands in an ssh session, edit the admin user and select which sudo options are allowed.
Select Allow all sudo commands with no password. You might see a prompt in the ssh session to enter a password the first time you enter a sudo command but will not see this password prompt again in the same session.
To use two-factor authentication with the administrator account (root or admin user), first configure and enable SSH service to allow SSH access, then configure two-factor authentication. If you have the root user configured with a password and enable it, you can SSH into the system with the root user. Security best practice is to disable the root user password and only use the local administrator account.
At present, rootless log in works with TrueCommand but you need to set up and use an API key. Future releases of TrueCommand should eliminate the need for the API key.
In TrueNAS, user accounts allow flexibility for accessing shared data. Typically, administrators create users and assign them to groups. Doing so makes tuning permissions for large numbers of users more efficient.
Only the root user account can log in to the TrueNAS web interface until the root user creates an admin user with the same permissions. After logging in as root, TrueNAS alerts you to create the local administrator account.
As part of security hardening and to comply with Federal Information Processing standards (FIPS), iXsystems plans to completely disable root login in a future release.
System administrators should create and begin using a new root-level user before this function goes away.
When the network uses a directory service, import the existing account information using the instructions in Directory Services.
Using Active Directory requires setting Windows user passwords in Windows.
To see user accounts, go to Credentials > Local Users.
TrueNAS hides all built-in users (except root) by default. Click the toggle Show Built-In Users to see all built-in users.
SCALE has implemented rootless log in. All systems should create and begin using an admin user as a replacement for the root user.
If you upgraded to a 22.12.0 release instead of installing fresh from an iso file and setting up the admin user in that process, you can create an admin user with this procedure.
Go to Credentials > Local Users and click Add.
Enter the name you want to use for the administrator account.
Enter and confirm the admin user passwords.
Select the root, builtin_administrators and builtin_users groups from the Auxiliary Group dropdown list.
Click Save.
Log out of the TrueNAS system and then log back in using the admin user credentials. Once you are back in the TrueNAS web UI, determine that the admin user credentials are working properly with your network configuration.
The Nextcloud application, configured on the Apps > Available Applications screen, requires including sudo permissions for the administrator account. To verify, or manage the local administrator account, go to Credentials > Local Users and click on the administrator user row to expand it, then click Edit to open the Edit User configuration screen.
Scroll down to the Authentication settings and select the proper Allow sudo authorization settings.
Click Save.
For information on adding sudo permissions in cli commands, see Installing Nextcloud for Media Previews.
To create a new user, click Add.
TrueNAS lets users configure four different user account traits (settings).
Enter the user full name in Full Name. TrueNAS suggests a simplified name in Username derived from the Full Name, but you can override it with your own choice.
You can also assign a user account email address in the Email field.
By default, the Disable Password toggle is not enabled. In this case, set and confirm a password.
Setting Disable Password toggle to active (blue toggle) disables several options:
Next, you must set a user ID (UID). TrueNAS suggests a user ID starting at 1000, but you can change it if you wish. We recommend using an ID of 1000 or greater for non-built-in users. New users can be created with a UID of 0.
By default, TrueNAS creates a new primary group with the same name as the user. This happens when the Create New Primary Group toggle is enabled. To add the user to an existing primary group instead, disable the Create New Primary Group toggle and search for a group in the Primary Group field. You can add the user to more groups using the Auxiliary Groups drop-down list.
When creating a user, the home directory path is set to
You can set the home directory permissions directly under the file browser. You cannot change TrueNAS default user account permissions.
You can assign a public SSH key to a user for key-based authentication by entering or pasting the public key into the Authorized Keys field.
Do not paste the private key.
If you are using an SSH public key, always keep a backup of the key.
Select the shell option for the user from the Shell dropdown options. Set the local admin user shell to TrueNAS CLI to open shell in the TrueNAS CLI. Set to TrueNAS Console to open in the Console Setup Menu for SCALE.
Selecting Lock User disables all password-based functionality for the account until you clear the checkbox.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password and Allow all sudo commands with no password allows the account to act as the system administrator using the sudo command. Leave it disabled for better security.
By default, Samba Authentication is enabled. This allows using the account credentials to access data shared with SMB.
To edit an existing user account, go to Credentials > Local Users, expand the user entry, and click edit Edit to open the Edit User configuration screen. See Local User Screens for details on all settings.
TrueNAS offers groups as an efficient way to manage permissions for many similar user accounts. See Users for managing users. The interface lets you manage UNIX-style groups. If the network uses a directory service, import the existing account information using the instructions in Active Directory.
To see saved groups, go to Credentials > Local Groups.
By default, TrueNAS hides the system built-in groups. 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.
To create a group, go to Credentials > Local Groups and click Add.
Enter a unique number for the group ID in GID that TrueNAS uses to identify a Unix group. Enter a number above 1000 for a group with user accounts or for a system service enter the default port number for the service as the GID. 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.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password and Allow all sudo commands with no password allows the group members to act as the system administrator using the sudo command. Leave it disabled for better security.
To allow Samba permissions and authentication to use this group, select Samba Authentication.
To allow more than one group to have the same group ID (not recommended), select Allow Duplicate GIDs.
To manage group membership, go to Credentials > Local Groups, expand the group entry, and click Members to open the Update Members screen.
To add user accounts to the group, select users and then click . Select All Users to move all users to the selected group, or select multiple users by holding Ctrl while clicking each entry.
The SCALE Directory Services tutorials contains options to edit directory domain and account settings, set up Id mapping, and configure authentication and authorization services in TrueNAS SCALE.
When setting up directory services in TrueNAS, you can connect TrueNAS to either an Active Directory or an LDAP server but not both.
To view Idmap and Kerberos Services, click Show next to Advanced Settings.
The Active Directory (AD) service shares resources in a Windows network. AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.
When joined to an AD domain, you can use domain users and groups in local ACLs on files and directories. You can also set up shares to act as a file server.
Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.
Users can configure AD services on Windows or Unix-like operating systems using Samba version 4.
To configure an AD connection, you must know the AD controller domain and the AD system account credentials.
Users can take a few steps before configuring Active Directory (AD) to ensure the connection process goes smoothly.
Obtain the AD admin account name and password.
After taking these actions, you can connect to the Active Directory domain.
To confirm that name resolution is functioning, you can use the Shell and issue a ping
command and a command to check network SRV records and verify DNS resolution.
To use dig
to verify name resolution and return DNS information:
Go to System Settings > Shell and type dig
to check the connection to the AD domain controller.
The domain controller manages or restricts access to domain resources by authenticating user identity from one domain to the other through a login credentials, and it prevents unauthorized access to these resources. The domain controller applies security policies to request-for-access domain resources.
When TrueNAS sends and receives packets without loss, the connection is verified.
Press Ctrl + C to cancel the ping
.
Also using Shell, check the network SRV records and verify DNS resolution enter command host -t srv <_ldap._tcp.domainname.com>
where <_ldap._tcp.domainname.com> is the domain name for the AD domain controller.
Active Directory relies on the time-sensitive Kerberos protocol. TrueNAS adds the AD domain controller with the PDC Emulator FSMO Role as the preferred NTP server during the domain join process. If your environment requires something different, go to System Settings > General to add or edit a server in the NTP Servers window.
Keep the local system time sync within five (5) minutes of the AD domain controller time in a default AD environment.
Use an external time source when configuring a virtualized domain controller. TrueNAS generates alerts if the system time gets out-of-sync with the AD domain controller time.
TrueNAS has a few options to ensure both systems are synchronized:
To connect to Active Directory, in SCALE:
Go to Credentials > Directory Services click Configure Active Directory to open the Active Directory configuration screen.
Enter the domain name for the AD in Domain Name and the account credentials in Domain Account Name and Domain Account Password.
Select Enable to attempt to join the AD domain immediately after saving the configuration. SCALE populates the Kerberos Realm and Kerberos Principal fields on the Advanced Options settings screen.
TrueNAS offers advanced options for fine-tuning the AD configuration, but the preconfigured defaults are generally suitable.
When the import completes, AD users and groups become available while configuring basic dataset permissions or an ACL with TrueNAS cache enabled (enabled by default).
Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab. TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.
If the cache becomes out of sync or fewer users than expected are available in the permissions editors, resync it by clicking Settings in the Active Directory window and selecting Rebuild Directory Service Cache.
When creating the entry, enter the TrueNAS hostname in the name field and make sure it matches the information on the Network > Global Configuration screen in the Hostname and NetBIOS fields.
You can disable your AD server connection without deleting your configuration or leaving the AD domain. Click Settings to open the Active Directory settings screen, then select the Enable checkbox to clear it, and click Save to disable SCALE AD service. This returns you to the main Directory Services screen where you see the two main directory services configuration options.
Click Configure Active Directory to open the Active Directory screen with your existing configuration settings. Select Enable again, click Save to reactivate your connection to your AD server.
TrueNAS SCALE requires users to cleanly leave an Active Directory if you want to delete the configuration. To cleanly leave AD, use the Leave Domain button on the Active Directory Advanced Settings screen to remove the AD object. Remove the computer account and associated DNS records from the Active Directory.
If the AD server moves or shuts down without you using Leave Domain, TrueNAS does not remove the AD object, and you have to clean up the Active Directory.
TrueNAS has an Open LDAP client for accessing the information on an LDAP server. An LDAP server provides directory services for finding network resources like users and their associated permissions.
You can have either Active Directory or LDAP configured on SCALE but not both.
To configure SCALE to use an LDAP directory server:
Go to Credentials > Directory Services and click Configure LDAP.
Enter your LDAP server host name. If using a cloud service LDAP server, do not include the full URL.
Enter your LDAP server base DN. This is the top of the top level of the LDAP directory tree to use when searching for resources.
Enter the bind DN (administrative account name for the LDAP server) and the bind password.
Select Enable to activate the server
Click Save.
If you want to further modify the LDAP configuration, click Advanced Options. See the LDAP UI Reference article for details about advanced settings.
To disable LDAP but not remove the configuration, clear the Enable checkbox. The main Directory Services screen returns to the default view showing the options to configure Active Directory or LDAP. To enable LDAP again, click Configure LDAP to open the LDAP screen with your saved configuration. Select Enable again to reactivate your LDAP directory server configuration.
To remove the LDAP configuration, click Settings to open the LDAP screen. Clear all settings and click Save.
Kerberos is a computer network security protocol. It authenticates service requests between trusted hosts across an untrusted network (i.e., the Internet).Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!
If you configure Active Directory in SCALE, SCALE populates the realm fields and the keytab with 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 uses realms and keytabs to authenticate clients and servers. A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client. By default, TrueNAS creates a Kerberos realm for the local system. A keytab (“key table”) is a file that stores encryption keys for authentication.
TrueNAS SCALE allows users to configure general Kerberos settings, as well as realms and keytabs.
TrueNAS automatically generates a realm after you configure AD.
Users can configure Kerberos realms by navigating to Directory Services and clicking Add in the Kerberos Realms window.
Enter the realm and key distribution (KDC) names, then define the admin and password servers for the realm.
Click Save.
TrueNAS automatically generates a keytab after you configure AD.
A Kerberos keytab replaces the administration credentials for Active Directory after intial configuration. Since TrueNAS does not save the Active Directory or LDAP administrator account password in the system database, keytabs can be a security risk in some environments.
When using a keytab, create and use a less-privileged account to perform queries. TrueNAS stores that account password in the system database.
After generating the keytab, go back to Directory Services in TrueNAS and click Add in the Kerberos Keytab window to add it to TrueNAS.
To make AD use the keytab, click Settings in the Active Directory window and select it using the Kerberos Principal dropdown list.
When using a keytab with AD, ensure the keytab username and userpass match the Domain Account Name and Domain Account Password.
To make LDAP use a keytab principal, click Settings in the LDAP window and select the keytab using the Kerberos Principal dropdown list.
If you do not understand Kerberos auxiliary parameters, do not attempt to configure new settings!
The Kerberos Settings screen includes two fields used to configure auxiliary parameters.
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!
Idmap settings exist for the purpose of integration with an existing directory domain to ensure that UIDs and GIDs assigned to Active Directory users and groups have consistent values domain-wide. The correct configuration therefore relies on details that are entirely external to the TrueNAS server, e.g., how the AD administrator has configured other Unix-like computers in the environment.
The default is to use an algorithmic method of generating IDs based on the RID component of the user or group SID in Active Directory.
Only administrators experienced with configuring Id mapping should attempt to add new or edit existing idmaps. Misconfiguration can lead to permissions incorrectly assigned to users or groups in the case where data is transferred to/from external servers via ZFS replication or rsync (or when access is performed via NFS or other protocols that directly access the UIDs/GIDs on files).
The Idmap directory service lets users configure and select a backend to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. Users must enable the Active Directory service to configure and use identity mapping (Idmap).
Users can click Add in the Idmap window to configure backends or click on an already existing Idmap to edit it.
TrueNAS automatically generates an Idmap after you configure AD or LDAP.
From the Directory Services screen, click Show to the right of Advanced Settings and then click Confirm to close the warning dialog.
Click Add on the Idmap widget to open the Idmap Settings screen.
Select the type from the Name field dropdown. Screen settings change based on the selection.
Select the Idmap Backend type from the dropdown list. Screen settings change based on the backend selected.
Enter the required field values.
Click Save.
TrueNAS backup credentials store cloud backup services credentials, SSH connections, and SSH keypairs. Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
The Cloud Credentials widget on the Backup Credentials screen allows users to integrate TrueNAS with cloud storage providers.
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
To maximize security, TrueNAS encrypts cloud credentials when saving them. However, this means that to restore any cloud credentials from a TrueNAS configuration file, you must enable Export Password Secret Seed when generating that configuration backup. Remember to protect any downloaded TrueNAS configuration files.
Authentication methods for each provider could differ based on the provider security requirements. You can add credentials for many of the supported cloud storage providers from the information on the Cloud Credentials Screens. This article provides instructions for the more involved providers.
We recommend users open another browser tab to open and log into the cloud storage provider account you intend to link with TrueNAS.
Some providers require additional information that they generate on the storage provider account page. For example, saving an Amazon S3 credential on TrueNAS could require logging in to the S3 account and generating an access key pair found on the Security Credentials > Access Keys page.
Have any authentication information your cloud storage provider requires on-hand to make the process easier. Authentication information could include but are not limited to user credentials, access tokens, and access and security keys.
To set up a cloud credential, go to Credentials > Backup Credentials and click Add in the Cloud Credentials widget.
Select the cloud service from the Provider dropdown list. The provider required authentication option settings display.
For details on each provider authentication settings see Cloud Credentials Screens.
Click Verify Credentials to test the entered credentials and verify they work.
Click Save.
The process to set up the Storj-TrueNAS account, buckets, create the S3 access and download the credentials is documented fully in Adding a Storj Cloud Sync Task in the Adding Storj Cloud Credentials section.
If adding an Amazon S3 cloud credential, you can use the default authentication settings or use advanced settings if you want to include endpoint settings.
Cloud storage providers using OAuth as an authentication method are Box, Dropbox, Google Drive, Google Photo, pCloud and Yandex.
BackBlaze B2 uses an application key and key ID to authenticate credentials.
Google Cloud Storage uses a service account json file to authenticate credentials.
Microsoft OneDrive Cloud uses OAuth authentication, an access token, and Drives list, account type and IDs to authenticate credentials.
OpenStack Swift authentication credentials change based on selections made in AuthVersion. All options use the user name, API key or password and authentication URL, and can use the optional endpoint settings.
Some providers can automatically populate the required authentication strings by logging in to the account.
The SSH Connections and SSH Keypairs widgets on the Backup Credentials screen display a list of SSH connections and keypairs configured on the system. Using these widgets, users can establish Secure Socket Shell (SSH) connections.
To begin setting up an SSH connection, go to Credentials > Backup Credentials and click the Add button on the SSH Connections widget.
This procedure uses the semi-automatic setup method for creating an SSH connection with other TrueNAS or FreeNAS systems.
This procedure provides instructions on setting up an SSH connection to a non-TrueNAS or non-FreeNAS system. To manually set up an SSH connection, you must copy a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.
This procedure covers adding a public SSH key to the admin account on the TrueNAS SCALE system and generating a new SSH Keypair to add to the remote system (TrueNAS or other).
TrueNAS generates and stores RSA-encrypted SSH public and private keypairs on the SSH Keypairs widget found on the Credentials > Backup Credentials screen. Keypairs are generally used when configuring SSH Connections or SFTP Cloud Credentials. TrueNAS does not support encrypted keypairs or keypairs with passphrases.
TrueNAS automatically generates keypairs as needed when creating new SSH Connections or Replication tasks. To manually create a new keypair, click Add on the SSH Keypairs widget. Click Generate New on the SSH Keypairs screen. Give the new keypair a unique name and click Save. The keypair displays on the SSH Keypairs widget.
Click the vertical ellipsis
at the bottom of the SSH Keypairs configuration screen to download these strings as text files for later use.Use the Credentials > Certificates screen Certificates, Certificate Signing Requests (CSRs), Certificate Authorities (CA), and ACME DNS-Authenticators widgets to manage certificates, certificate signing requests (CSRs), certificate authorities (CA), and ACME DNS-authenticators.
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.
The Certificates screen widgets display information for certificates, certificate signing requests (CSRs), certificate authorities(CAs), and ACME DNS-authenticators configured on the system, and provide the ability to add new ones. 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.
By default, TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can import and create more certificates by clicking Add in the Certificates window.
To add a new certificate:
Click Add on the Certificates widget to open the Add Certficates wizard.
First, enter a name as certificate identifier and select the type.
The Identifier and Type step lets users name the certificate 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.
Next, specify the certificate options. Select the Key Type as this selection changes the settings displayed. The Certificate Options step provides options for choosing 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.
Now enter the certificate location and basic information.
The Certificate Subject step 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.
Lastly, select any extension types you want to apply. Selecting Extended Key displays settings for Key Usage settings as well. Select any extra constraints you need for your scenario. The Extra Constraints step contains certificate extension options.
Review the certificate options. If you want to change something Click Back to reach the screen with the setting option you want to change, then click Next to advance to the Confirm Options step.
Click Save to add the certificate.
To import a certificate, first select Import Certificate as the Type and name the certificate.
Next, if the CSR exists on your SCALE system, select CSR exists on this system and then select the CSR.
Copy/paste the certificate and private Keys into their fields, and enter and confirm the passphrase for the certificate if one exists.
Review the options, and then click Save.
TrueNAS SCALE allows users to automatically generate custom domain certificates using Let’s Encrypt.
Go to Credentials > Certificates and click ADD in the ACME DNS-Authenticators widget.
Enter the required fields depending on your provider, then click Save.
For Cloudflare, enter either your Cloudflare Email and API Key, or enter an API Token. If you create an API Token, make sure to give the token the permission Zone.DNS:Edit as it’s required by certbot.
For Route53, enter your Access Key ID and Secret Access Key.
Next, click ADD in the Certificate Signing Requests widget.
You can use default settings except for the Common Name and Subject Alternate Names fields.
Enter your primary domain name in the Common Name field, then enter additional domains you wish to secure in the Subject Alternate Names field.
For example, if your primary domain is domain1.com, entering www.domain1.com
secures both addresses.
Click the icon next to the new CSR.
Fill out the ACME Certificate form. Under Domains, select the ACME DNS Authenticator you created for both domains, then click Save.
You can create testing and staging certificates for your domain.
The Certificate Authorities widget lets users set up a certificate authority (CA) that certifies the ownership of a public key by the named subject of the certificate.
To add a new CA:
First, add the name and select the type of CA.
The Identifier and Type step lets users name the CA and choose whether to create a new CA or import an existing CA.
Users can also select a predefined certificate extension from the Profiles drop-down list.
Next, enter the certificate options. Select the key type. The Key Type selection changes the settings displayed. The Certificate Options step provides options for choosing what 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.
Now enter the certificate subject information.
The Certificate Subject step 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.
Lastly, enter any extra constraints you need for your scenario. The Extra Constraints step contains certificate extension options.
Review the CA options. If you want to change something Click Back to reach the screen with the setting option you want to change, then click Next to advance to the Confirm Options step.
Click Save to add the CA.
The Certificate Signing Requests widget allows users configure the message(s) the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
To add a new CSR:
First enter the name and select the CSR type.
The Identifier and Type step lets users name the certificate signing request (CSR) and choose whether to create a new CSR or import an existing CSR.
Users can also select a predefined certificate extension from the Profiles drop-down list.
Next, select the certficate options for the CSR you selected. The Certificate Options step provides options for choosing what 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.
Now enter the information about the certificate.
The Certificate Subject step 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.
Lastly, enter any extra constraints you need for your scenario. The Extra Constraints step contains certificate extension options.
Review the certificate options. If you want to change something Click Back to reach the screen with the setting option you want to change, then click Next to advance to the Confirm Options step.
Click Save to add the CSR.
Automatic Certificate Management Environment (ACME) DNS authenticators allow users to automate certificate issuing and renewal. The user must verify ownership of the domain before TrueNAS allows certificate automation.
ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.
The system requires an ACME DNS Authenticator and CSR to configure ACME certificate automation.
To add an authenticator,
Click Add on the ACME DNS-Authenticator widget to open the Add DNS Authenticator screen.
Enter a name, and select the authenticator you want to configure. The selection changes the screen settings.
If you select Cloudflare as the authenticator, you must enter your Cloudflare account email address, API key, and API token.
If you select Route53 as the authenticator, you must enter your Route53 Access key ID and secret access key.
Click Save to add the authenticator.
Two-factor authentication (2FA) is great for increasing security.
TrueNAS offers 2FA to ensure that entities cannot use a compromised administrator root password to access the administrator interface.
To use 2FA, you need a mobile device with the current time and date, and that has Google Authenticator installed. Other authenticator applications can be used, but you will need to 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. Make sure Network Time Protocol (NTP) is functional before enabling is strongly recommended!
Unauthorized users cannot log in since they do not have the randomized 6-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 Credentials > 2FA to open the Two-Factor Auth screen.
Click Enable Two Factor Authentication. The Enable Two-Factor Authentication confirmation dialog opens. Click Confirm.
Enable Two Factor Authentication toggles to Disable Two-Factor Authentication to turn 2FA off.
The Scan this QR Code dialog opens. Use Google Authenticator to scan the code.
Click Save. If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.
Start Google Authenticator on the mobile device and scan the QR code. After scanning the code click Close to close the dialog on the Two-Factor Auth screen.
Go to Credentials > 2FA to open the Two-Factor Auth screen. Click Disable Two-Factor Authentication.
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 CLI, enter:
midclt call auth.twofactor.update '{ "enabled":false }'
After disabling 2FA, if you want to enable it again at some point in the future, go to Credentials > 2FA to open the Two-Factor Auth screen. Click Enable Two-Factor Authentication.
To change the system-generated Secret and Provisioning URI values, click Renew Secret. If you want to save these values in a text file, click the
icon in the field to display the alphanumeric string and either enter or copy/paste the value into a text file. Keep all login codes in protected and backed up location.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 User name 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 Credentials > 2FA.
Go to System Settings > Services and edit the SSH service.
a. Set Log in as Root 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.
TrueNAS Enterprise
KMIP is only available for TrueNAS SCALE Enterprise licensed systems. Contact the iXsystems Sales Team to inquire about purchasing TrueNAS Enterprise licenses.
The Key Management Interoperability Protocol (KMIP) is an extensible client/server communication protocol for storing and maintaining keys, certificates, and secret objects. KMIP on TrueNAS SCALE Enterprise integrates the system within an existing centralized key management infrastructure and uses a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
With KMIP, keys created on a single server are then retrieved by TrueNAS. KMIP supports keys wrapped within keys, symmetric, and asymmetric keys. KMIP enables clients to ask a server to encrypt or decrypt data without the client ever having direct access to a key. You can also use KMIP to sign certificates.
To connect TrueNAS to a KMIP server, import a certificate authority (CA) and Certificate from the KMIP server, then configure the KMIP options.
For security reasons, we strongly recommend protecting the CA and certificate values.
Go to Credentials > KMIP.
Enter the central key server host name or IP address in Server and the number of an open connection on the key server in Port. Select the certificate and certificate authority that you imported from the central key server. To ensure the certificate and CA chain is correct, click on Validate Connection. Click Save.
When the certificate chain verifies, choose the encryption values, SED passwords, or ZFS data pool encryption keys to move to the central key server. Select Enabled to begin moving the passwords and keys immediately after clicking Save.
Refresh the KMIP screen to show the current KMIP Key Status.
If you want to cancel a pending key synchronization, select Force Clear and click Save.
The Virtualization section allows users to set up Virtual Machines (VMs) to run alongside TrueNAS. Delegating processes to VMs reduces the load on the physical system, which means users can utilize additional hardware resources. Users can customize six different segments of a VM when creating one in TrueNAS SCALE.
A virtual machine (VM) is an environment on a host computer that you can use as if it is a separate, physical computer. Users can use VMs to run multiple operating systems simultaneously on a single computer. Operating systems running inside a VM see emulated virtual hardware rather than the host computer physical hardware. VMs provide more isolation than Jails but also consume more system resources.
Before creating a VM, you need an installer
To create a new VM, go to Virtualization and click Add to open the Create Virtual Machine configuration screen. If you have not yet added a virtual machine to your system you can click Add Virtual Machines to open the same screen.
Select the operating system you want to use from the Guest Operating System dropdown list.
Compare the recommended specifications for the guest operating system with your available host system resources when allocating virtual CPUs, cores, threads, and memory size.
Change other Operating System settings per your use case.
Select UTC as the VM system time from the System Clock dropdown if you do not want to use the default Local setting.
Select the virtual console option from the Display Type dropdown. VNC is the most widely used option with the best display but is slower than SPICE. SPICE has faster data transfer speed but a lower quality display, and is not as secure as VNC.
Change the default IP address in Bind if you want use a specific address as the primary network interface, otherwise leave it set to 0.0.0.0.
Click Next.
Enter the CPU and memory settings for your VM.
If you selected Windows as the Guest Operating System, the Virtual CPUs field displays a default value of 2. The VM operating system might have operational or licensing restrictions on the number of CPUs.
Do not allocate too much memory to a VM. Activating a VM with all available memory allocated to it can slow the host system or prevent other VMs from starting.
Leave CPU Mode set to Custom if you want to select a CPU model.
Specify the amount of RAM you want for the VM if you want to use more or less than the default. We recommend increasing this value, but your configuration depends on the resources available for your VM.
Click Next.
Configure disk settings.
Select Create new disk image to create a new zvol on an existing dataset.
Select Use existing disk image to use an existing zvol for the VM.
Select either AHCI or VirtIO from the Select Disk Type dropdown list. We recommend using AHCI or Windows VMs.
Select the location for the new zvol from the Zvol Location dropdown list.
Enter a value in Size (Examples: 500KiB, 500M, and 2TB) to indicate the amount of space to allocate for the new zvol.
Click Next.
Cofigure the network interface.
Select the network interface type from the Adapter Type dropdown list. Select Intel e82585 (e1000) as it offers a higher level of compatibility with most operating systems, or select VirtIO if the guest operating system supports para-virtualized network drivers.
Select the network interface card to use from the Attach NIC dropdown list.
Click Next.
Upload installation media for the operating system you selected.
You can create the VM without an OS installed. To add it either type the path or browse to the location and select it.
To upload an
Click Upload to begin the upload process. After the upload finishes, click Next.
Specify a GPU.
The VirtIO network interface requires a guest OS that supports VirtIO para-virtualized network drivers.
iXsystems does not have a list of approved GPUs at this time but does have drivers and basic support for the list of nvidia Supported Products.
Confirm your VM settings, then click Save.
After creating the VM, you can add or remove virtual devices.
Expand the VM entry on the Virtual Machines screen and click device_hub Devices.
Device notes:
After creating the VM and configuring devices for it, manage the VM by expanding the entry on the Virtual Machines screen.
An active VM displays options for settings_ethernet Display and keyboard_arrow_right Serial Shell connections.
If the display connection screen appears distorted, try adjusting the display device resolution.
Use the State toggle or click stop Stop to follow a standard procedure to do a clean shutdown of the running VM. Click power_settings_new Power Off to halt and deactivate the VM, which is similar to unplugging a computer.
If the VM you created has no Guest OS installed, The VM State toggle and stop Stop button might not function as expected. The State toggle and stop Stop button send an ACPI power down command to the VM operating system, but since an OS is not installed, these commands time out. Use the Power Off button instead.
When the VM is configured in TrueNAS and has an OS
Some operating systems can require specific settings to function properly in a virtual machine. For example, vanilla Debian can require advanced partitioning when installing the OS. Refer to the documentation for your chosen operating system for tips and configuration instructions.
After creating the VM, the next step is to add virtual devices for that VM.
Go to Virtualization > Virtual Machines and locate the VM you want to modify. Click anywhere on a VM entry on the Virtual Machines widget to expand it and show the options for the VM.
Click device_hub Devices to open the devices screen associated with the VM. From this screen, you can edit, add, or delete devices. Click the
icon at the right of each listed device to see device options.The devices for the VM display as a list.
Device notes:
Before adding, editing, or deleting a VM device, stop the VM if it is running. Click the State toggle to stop or restart a VM.
Select Edit to open the Edit type Device screen where type is the device type selected. You can change the type of virtual hard disk, the storage volume to use, or change the device boot order.
Deleting a device removes it from the list of available devices for the selected VM.
You can now go to Virtualization > Virtual Machines and restart the VM.
Select CD-ROM in Device Type on the Add Device screen and set a boot order.
Select NIC in the Device Type on the Add Devicecreen to add a network interface card for the VM to use.
Select Disk in Device Type on the Add Device screen to configure a new disk location, drive type and disk sector size, and boot order.
Select PCI Passthrough Device in the Device Type on the Add Device screen to configure the PCI passthrough device and boot order.
Depending upon the type of device installed in your system, you may see a warning: PCI device does not have a reset mechanism defined. You may experience inconsistent or degraded behavior when starting or stopping the VM. Determine if you want to proceed with this action in such an instance.
Select USB Passthrough Device as the Device Type on the Add Device screen to configure the USB passthrough device, and set a boot order.
Select Display as Device Type on the Add Device screen to configure a new display device.
If you want to access your TrueNAS SCALE directories from a VM, you have multiple options. If your system has more than one physical interface, you can assign your VMs to a NIC other than the primary one your TrueNAS server uses. This method makes communication more flexible, but does not offer the potential speed of a bridge.
If you have only one physical interface, you must create a bridge interface for the VM to use.
If the only interface you have is a single physical interface, complete the following steps in order to create a network bridge:
- If you have apps running, disable them before proceeding.
- Clear the DHCP checkbox on the single physical interface you have, but don’t apply the changes.
- Create a bridge interface and add your physical interface as a member. Configure relevant networking options such as DHCP.
- Then apply the changes and connect to the UI with the new networking settings.
- These steps are outlined below.
Go to Virtualization, find the VM you want to use to access TrueNAS storage, and toggle it off.
Go to Network > Interfaces and find the active interface you used as the VM parent interface. Note the interface IP Address and subnet mask. Click the interface.
The Edit Interface screen appears. If selected, clear the DHCP checkbox. Note the IP address and mask under Aliases. Click the X next to the listed alias to remove the IP address and mask. The Aliases field now reads No items have been added yet. Click Save.
The Interfaces widget displays the edited interface with no IP information.
To set up a bridge interface, from the Network screen:
Select Bridge from the Type dropdown list. You cannot change the Type field value after you click Save.
Enter a name for the interface. Use the format bondX, vlanX, or brX where X is a number representing a non-parent interface. Read-only when editing an interface. You cannot change the Name of the interface after you click Save.
(Optional but recommended) Enter any notes or reminders about this particular bridge in the Description field.
Select the interfaces on the Bridge Members dropdown list.
Next to Aliases click Add to enter the IP address for this bridge interface. (Optional) click Add to display an additional IP address field for each additional IP address you want to add.
To determine if network changes are suitable, click Test Changes.
Once TrueNAS finishes testing the interface, click Save Changes if you want to keep the changes. Click Revert Changes to discard the changes and return to the previous configuration.
The new bridge interface displays with associated IP information.
Go to Virtualization, expand the VM you want to use to access TrueNAS storage, and click Devices. Click more_vert in the NIC row and select Edit. Select the new bridge interface from the Nic to Attach dropdown list, then click Save.
You can now access your TrueNAS storage from the VM. You might have to set up shares or users with home directories to access certain files.
The first time you open the Applications screen, the UI asks you to choose a storage pool for applications.
We recommend keeping the container use case in mind when choosing a pool. Select a pool with enough space for all the application containers you intend to use. TrueNAS creates an ix-applications dataset on the chosen pool and uses it to store all container-related data. The dataset is for internal use only. Set up a new dataset before installing your applications if you want to store your application data in a location separate from other storage on your system. For example, create the datasets for the Nextcloud application, and, if installing Plex, create the dataset(s) for Plex data storage needs.
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 > 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.
Official applications are pre-configured and only require a name during deployment.
A button to open the application web interface displays when the container deploys and activates.
You can adjust the container settings by editing a deployed official container. Saving any changes redeploys the container.
Official applications use the default system-level Kubernetes Node IP settings in Apps > Settings > Advanced Settings.
You can change the Kubernetes Node IP to assign an external interface to your apps, separate from the web UI interface.
We recommend using the default Kubernetes Node IP (0.0.0.0) to ensure apps function correctly.
To deploy a custom application container in the SCALE web interface, go to Apps and click Launch Docker Image to open the Docker image wizard screens and settings.
Custom applications use the system-level Kubernetes Node IP settings by default. You can assign an external interface to custom apps by setting one on the Networking section of the Launch Docker Image form.
Unless you need to run an application separately from the Web UI, we recommend using the default Kubernetes Node IP (0.0.0.0) to ensure apps function correctly.
You can upgrade apps as they receive big-fixing updates or QOL changes. To upgrade an app to the latest version, click the in an app widget to see the list of app options, then select Upgrade.
To upgrade multiple apps, select the checkbox in the widget of each app you want to update, then click Bulk Actions and select Upgrade.
To delete an application, click Stop and wait for the status to show stopped. Click the in an app widget to see the list of app options, then select Delete.
If you attempt to delete the application before it fully deploys, a dialog opens with a list of other applications on your system using the same resources.
Click Confirm and then OK to delete the application.
If you only select Confirm to delete the application and do not select Delete docker images used by the app, the docker image remains on the image list on the Manage Docker Images screen. To remove the image, go to Manage Docker Images, click the and then Delete.
Click Confirm and Force delete, then click Delete to remove the docker image from the system.
TrueNAS SCALE comes with a pre-built official catalog of iXsystems-approved Docker apps that includes Plex, MinIO, Nextcloud, Chia, and IPFS.
Users can also configure custom apps catalogs, although iXsystems does not directly support any non-official apps in a custom catalog.
TrueNAS uses outbound ports 80/443 to retrieve the Official catalog.
To manage and add catalogs, click on the Manage Catalogs tab on the Applications screen.
Users can edit, refresh, delete, and view the summary of a catalog by clicking the more_vert button next to the intended catalog.
Edit opens the Edit Catalog screen where users can change the name TrueNAS uses to look up the catalog or change the trains from which the UI should retrieve available applications for the catalog.
Refresh re-pulls the catalog from its repository and applies any updates.
Delete allows users to remove a catalog from the system. Users cannot delete the default Official catalog.
Summary lists all apps in the catalog and sorts them train, app, and version.
Users can filter the list by Train type (All, charts, or test), and by Status (All, Healthy, or Unhealthy).
To add a catalog, click the Add Catalog button at the top right of on the Manage Catalogs tab. Fill out the Add Catalog form. As an example, the data below to add the Truecharts catalog to SCALE.
Enter the name in Catalog Name, for example, type truecharts.
Leave the Force Create checkbox clear.
Select a valid git repository in Repository. For example, https://github.com/truecharts/catalog for TrueCharts.
Now select the train TrueNAS should use to retrieve available application information of the catalog. For example, select stable or incubator for the TrueCharts example.
Finially, enter the git repository branch TrueNAS should use for the catalog in Branch. For example, for TrueCharts, enter main.
Click Save.
SCALE includes the ability to run Docker containers using Kubernetes.
Always read through the Docker Hub page for the container you are considering installing so that you know all of the settings that you need to configure. To set up a Docker image, first, determine if you want the container to use its dataset. If yes, create a dataset for host volume paths before you click Launch Docker Image.
If your application requires directory paths, specific datasets, or other storage arrangements, configure these before you start the Launch Docker Image wizard.
You cannot exit the configuration wizard and save settings to create data storage or directories in the middle of the process. If you are unsure about any configuration settings, review the Launch Docker Image UI reference article before creating a Docker image.
To create directories in a dataset on SCALE, use System Settings > Shell before you begin installing the container.
When you are ready to create a container, go to the APPS screen, select the Available Applications tab, and then click Launch Docker Image.
Fill in the Application Name and the current version information in Version. Add the GitHub repository URL in Image Repository for the docker container.
Enter the Github repository for the application you want to install in Image Repository. If the application requires it, enter the correct setting values in Image Tag and select the Image Pull Policy to use.
If the application requires it, enter the executables you want or need to run after starting the container in Container Entrypoint. Click Add for Container CMD to add a command. Click Add for Container Arg to add a container argument.
Enter the Container Environment Variables. Not all applications use environment variables. Check the Docker Hub for details on the application you want to install to verify which variables that particular application requires.
Enter the networking settings.
a. Enter the external network interface to use. Click Add to display the Host Interface and IPAM Type fields required when configuring network settings.
b. Scroll down to select the DNS Policy and enter any DNS configuration settings required for your application.
Enter the Port Forwarding settings. Click Add for all ports you need to enter. TrueNAS SCALE requires setting all Node Ports above 9000.
Enter the required Container Port and Node Port settings, and select the protocol for these ports. Repeat for all ports.
Add the Storage settings. Click Add for each application host path. Add any memory-backed or other volumes you want to use.
You can add more volumes to the container later if they are needed.
Enter any additional settings required for your application, such as workload details or adding container settings for your application.
Select the Update Strategy to use. The default is Kill existing pods before creating new ones.
Set any resource limits you want to impose on this application.
Enter or select any Portal Configuration settings to use.
Click Save to deploy the container. If you correctly configured the app, the widget displays on the Installed Applications screen.
When complete, the container becomes active. If the container does not automatically start, click Start on the widget.
Click on the App card reveals details.
Define any commands and arguments to use for the image. These can override any existing commands stored in the image.
You can also define additional environment variables for the container. Some Docker images can require additional environment variables. Check the documentation for the image you are trying to deploy and add any required variables here.
To use the system IP address for the container, set Docker Host Networking. TrueNAS does not give the container a separate IP address, and the container port number appends to the end of the system IP address. See the Docker documentation for more details.
Users can create additional network interfaces for the container if needed. Users can also give static IP addresses and routes to a new interface.
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.
Choose the protocol and enter port numbers for both the container and node. You can define multiple ports to forward to the workload.
The node port number must be over 9000. Ensure no other containers or system services are using the same port number.
You can mount SCALE storage locations inside the container. To mount SCALE storage, define the path to the system storage and the container internal path for the system storage location to appear. You can also mount the storage as read-only to prevent using the container to change any stored data. For more details, see the Kubernetes hostPath documentation.
Users can create additional Persistent Volumes (PVs) for storage within the container. PVs consume space from the pool chosen for application management. You need to name each new dataset and define a path where that dataset appears inside the container.
To view created container datasets, go to Datasets and expand the dataset tree for the pool you use for applications.
Users developing applications should be mindful that if an application uses Persistent Volume Claims (PVC), those datasets are not mounted on the host and therefore are not accessible within a file browser. Upstream zfs-localpv uses this behavior to manage PVC(s).
If you want to consume or have file browser access to data that is present on the host, set up your custom application to use host path volumes.
Alternatively, you can use the network to copy directories and files to and from the pod using k3s kubectl
commands.
To copy from a pod in a specific container:
k3s kubectl cp <file-spec-src> <file-spec-dest> -c <specific-container>
To copy a local file to the remote pod:
k3s kubectl cp /tmp/foo <some-namespace>/<some-pod>:/tmp/bar
To copy a remote pod file locally:
k3s kubectl cp <some-namespace>/<some-pod>:/tmp/foo /tmp/bar
To access the shell in an active container, first, identify the namespace and pod for the container. In the Scale UI, go to System Settings > Shell to begin entering commands:
To view container namespaces: k3s kubectl get namespaces
.
To view pods by namespace: k3s kubectl get -n <NAMESPACE> pods
.
To access container shell: k3s kubectl exec -n <NAMESPACE> --stdin --tty <POD> -- /bin/bash
.
The TrueNAS community creates and maintains numerous applications intended to expand system functionality far beyond what is typically expected from a NAS.
The TrueNAS catalog is loaded by default and is used to populate the Apps > Available Applications tab. To view the catalog settings, select the Manage Catalogs tab.
Applications are provided “as-is” and can introduce system stability or security issues when installed. Some applications deploy as the root user for initial configuration before operating as a non-root user. Make sure the application is required for your specific use requirements and doesn’t violate your security policies before installation.
The remaining tutorials in this section are for specific applications that are commonly used or replace some functionality that was previously built-in with TrueNAS.
SCALE includes Chia in its Official Apps catalog. Chia Blockchain is a new cryptocurrency that uses Proof of Space and Time. Instead of using expensive hardware that consumes exorbitant amounts of electricity to mine cryptos, it leverages existing empty hard disk space on your computer(s) to farm cryptos with minimal resources, such as electricity.
Click on the Chia app Install button in the Available Applications list.
Name your App and click Next. In this example, the name is chia1.
Leave Enable Custom Host Path for Chia Configuration Volume and Enable Custom Host Path for Chia Plots Volume unchecked and click Next.
Click Next in the Chia Environment Variables screen. You add one later.
Confirm the options and click Submit.
Continue through the wizard and create the new application. After a minute or two the new Chia container starts and shows ACTIVE status. Click the three-dot menu on the top-right and launch the Shell.
Leave the defaults for the pod (there is only one) and use the selected /bin/bash shell.
The first time Chia launches, it automatically creates a new private key set (for plotting purposes) and wallet. However, the private key set is not preserved across container restarts. To make sure your keys and wallet persist, save the Mnemonic Seed that was created and make sure it gets used at each container initialization. To do this, start by displaying the current key information by running the following shell command:
/chia-blockchain/venv/bin/chia keys show --show-mnemonic-seed
We suggest you make a backup copy of the information provided here for your reference in case you lose the keyfile. To make sure the same key is used for this container going forward, you save the mnemonic-seed phrase to one of your host volumes on TrueNAS.
Copy and paste the 24 secret words of the mnemonic seed into a new shell command:
echo "my unique 24 secret words here" > /plots/keyfile
Now exit the shell and go back to the Installed Apps page. Click Edit on your Chia container.
Scroll down until you find the Container Environment Variables section and add a new variable as shown below:
If you entered the command correctly, you should see some output that looks like the screenshot.
Save the change, and the chia container should restart automatically. To confirm your changes have persisted you can log into the containers shell again and run the same /chia-blockchain/venv/bin/chia keys show --show-mnemonic-seed
command to show your keys. If the keys are identical to what you previously recorded, then you are done! This Chia container persists across reboots, upgrades, and re-deployments.
At this point, you are ready to begin farming Chia. This is a CLI process and beyond the scope of this quick how-to, but we recommend you start by reading up on their CLI reference materials, Quick Start guide and other documentation.
The SCALE Apps catalogue now includes Collabora from the developers of Nextcloud.
With Collabora, you can host your online office suite at home.
To integrate Collabora correctly, you must have a Nextcloud account with Collabora added.
Click on the Collabora app Install button in the Available Applications list.
Name your app and click Next. In this example, the name is collabora1.
Select a Timezone and, if you wish, enter a custom Username and Password.
You can also add extra parameters to your container as you see fit. See The LibreOffice GitHub Parameters page for more.
After you select your container settings, choose a Certificate and click Next.
Enter Environmental Variables as needed, then click Next.
Choose a node port to use for Collabora (we recommend the default), then click Next.
Configure extra host path volumes for Collabora as you see fit, then click Next.
Confirm your Collabora container options and click Save to complete setup.
After a few minutes, the Collabora container displays as ACTIVE.
After it does, you can click Web Portal to access the admin console.
Storj is an open-source decentralized cloud storage (DCS) platform. Storj permits a computer running this software to configure the system as a node and to rent unused system storage capacity and bandwidth to other users.
Before you can configure your system to act as a Storj node:
Review the Storj node hardware and bandwidth considerations at Storj Node.
Update TrueNAS SCALE to the latest public release.
Create a wallet address.
Generate a Storj authentication token.
Configure your router and firewall. Open ports on your router and configure port forwarding. Configure firewall rules to allow access for these ports.
Alternatively, use a dynamic DNS (DDNS) service such as NoIP to to create a host name if you do not have a static IP address for the system nodes.
Create a publicly-available domain name to access the Storj application. Point this to your router public IP address.
Create a Storj identity and authorize it for every node. Every node must have a unique identifier on the network. Use NFS/SMB shares or or a file transfer service such as FTP to upload the credentials generated. If the identity is not present on the storage directory, it generates and authorizes one automatically. This can take a long time and consume resources of the system while it generates one.
Install the Storj application in SCALE.
Storj provides a Quickstart Node Setup Guide with step-by-step instructions to help users create a Storj node.
Use Google Chrome MetaMask extension to create a wallet address, or if you already have one, you can use the exiting wallet. See Storj Wallet Configuration.
Special considerations regarding how to protect and manage a wallet are outside the scope of this article.
Open a browser window and go to Storj Host a Node. Enter an email address to associate with the account, select the I’m not a robot checkbox, then click Continue.
Copy the auth token to use later in this procedure. Keep this token in a secure location.
To allow the Storj application to communicate with Storj and the nodes, configure your router with port forwarding and the firewall to allow these ports to communicate externally:
With the TrueNAS system up and running, then check your open port using something like https://www.yougetsignal.com/tools/open-ports/. If your port forwarding is working, port 20988 is open.
This enables QUIC, which is a protocol based on UDP that provides more efficient usage of the Internet connection with both parallel uploads and downloads.
Create a DDNS host name that points to your router WAN IP address, and provide a domain name to use for access the Storj application. You can use a dynamic DNS service that allows you to set up a DDNS host name. You can use a service such as NoIP to create a domain name (i.e., name.ddns.net) and then point it at the WAN IP address of your router.
Use nislookup name.ddns.net
to verfiy it works.
Create three new datasets, one a parent to two child datasets nested under it.
Enter a name for the first dataset in Name. For example, storj-node, and click Save.
Select the new dataset storj-node, click Add Dataset again to create a new child dataset. For example, config.
Click Save.
Select the storj-node dataset again, click Add Dataset and create the second child dataset. For example, identity.
Click Save.
TrueNAS displays two nested datasets config and identity underneath the storj-node dataset.
Go to Apps, click on Available Applications, then scroll down to the Storj application, and click Install to open the Storj configuration wizard.
Accept the default name or enter a new name for your Storj application.
You can enter a name for the Storj app using lowercase alphanumeric characters that begin and end with an alphanumeric characters. Do not use a hyphenas the first or last character. For example, storjnode, or storj-node, but not -storjnode or storjnode-.
Enter the authentication token copied from Storj in Configure Auth token for Storj Node. Enter the email address associated with the token in Configure Email for Storj.
Enter the storage domain (i.e., the public network DNS name) added for Storj in Add Your Storage Domain for Storj. If using Dynamic DNS (DDNS), enter that name here as well. For example, name.ddns.net.
Accept the default values in Owner User ID and Owner Group ID. Either accept the default or change the value in Termination Grace Period.
Configure the storage size (in GB) you want to share. Enter the value in Configure Storage Size You Want to Share in GB’s.
Enter the host paths for the new datasets created for the Storj application. Select Enable Custom Host Path for Storj Configuration Volume and browse to the newly created dataset (config). Next, select Configure Identity Volume for Storage Node and browse to the second newly created dataset (identity).
Enter the web port 28967 in Web Port for Storj, and 20988 in Node Port for Storj.
The time required to install the Storj App varies depending on your hardware and network configuration. When complete, the Installed Applications screen displays the Storj app with the status of active.
Enviromental variables are optional. If you want to include additional variables, see Storj Environment Variables for a list. Click Add for each variable you want to add.
Click the Web Portal button to view additional details about the application.
The Storj Node dashboard displays stats for the storage node. These could include bandwidth utilization, total disk space, and disk space used for the month. Payout information is also provided.
This section has tutorials for using the MinIO apps available for TrueNAS SCALE.
This tutorial provides instructions on migrating from the MinIO S3 Filesystem service deployed through the TrueNAS S3 service, deprecated in SCALE Bluefin and removed in Cobia, to the latest release of the MinIO Server application in Bluefin.
MinIO has deprecated both the S3 Gateway and Filesystem services. MinIO no longer supports these offerings, do not provide a direct upgrade path for either, and require users to migrate from these S3 services to a later release of the MinIO Server.
TrueNAS SCALE offers access to the current MinIO release through the SCALE Bluefin MinIO app. Using the SCALE MinIO app simplifies the installation process by allowing users to install and deploy MinIO in a container pod. SCALE handles the MinIO download and installation process so users only configure their app deployment through the easy to use SCALE app screens. After completing the SCALE MinIO app installation, users log into the MinIO web portal to customize their MinIO deployments.
Community users can follow these instructions to migrate the TrueNAS S3 service to the MinIO Server application, and migrate the MinIO S3 service deployment to new MinIO Server deployment.
TrueNAS Enterprise
TrueNAS Enterprise customers are strongly encouraged to contact iXsystems Support for assistance with the migration process.
The migration path involves downloading and installing a MinIO Client (MC) release with the required feature and function support to migrate the MinIO S3 deployment.
Users must upgrade SCALE to the latest release of Bluefin and complete the migration process before upgrading to TrueNAS SCALE Cobia or a later major version.
Next, using the MinIO web portal, create a new MinIO app deployment and then migrate the MinIO S3 service deployment to it.
After migrating data, you can either create an archive of the TrueNAS S3 service or delete it.
Finally, you can upgrade Bluefin to Cobia.
TrueNAS SCALE upgraded to the latest publicly available release of Bluefin.
A TrueNAS system with double the storage capacity used by the S3 service and that does not cause the pool to exceed 80% utilization.
A TrueNAS self-signed certificate for the MinIO Enterprise app (not required for the community Charts app).
New port number for the MinIO Charts app. Do not use the same port numbers as the S3 service (9000 and 9001). Refer to Default Ports to identify available port numbers. The MinIO Enterprise app can use the default port numbers 30000 and 30001.
A MinIO Client (MC) release that supports the commands and functions required to migrate from the S3 service to later MinIO releases. Download and install a MinIO Client (MC) within the RELEASE.2022-06-26T18-51-48Z and RELEASE.2022-10-29T10-09-23Z range.
This procedure uses the MinIO Client (MC), TrueNAS SCALE, and the MinIO web portal.
Create a new dataset named data for the MinIO app. Do not use the same dataset(s) or path(s) consumed by the existing S3 service! For example, if the the existing S3 service path is /tank/s3/data, create a new dataset and path /tank/minio/data to use for the MinIO app.
You need at least double the storage capacity of the current S3 MinIO deployment on the TrueNAS SCALE system. Data storage should not cause the pool to exceed 80% utilization through the migration process.
This tutorial uses the same system for the S3 service and the MinIO app deployment. Using a secondary system for storage capacity slows data transfer rates to and from the server.
Identify two new port numbers to use for the community Charts MinIO app. The community Charts MinIO app default ports are the same as the S3 service so select new ports to use. Do not use the existing MinIO S3 service ports (9000 and 9001). See Default Ports for a list of assigned port numbers before deciding on the transitional app port numbers. The Enterprise MinIO app uses ports 30000 and 30001.
Download and install a MinIO Client release on your computer to facilitate the migration. Windows, Linux, and Mac version are available. Select a version that is between RELEASE.2022-06-26T18-51-48Z and RELEASE.2022-10-29T10-09-23Z. Versions outside of this range do not support the commands required to migrate the S3 service deployment to newer MinIO releases. Attempting to use a release outside the provided range can result in migration failure and the MinIO app failing to launch. This procedure uses MC RELEASE.2022-10-29T10-09-23Z.
This procedure uses the Windows Subsystem for Linux (WSL) to install the client, and assumes user familiarity with WSL or standard Linux CLI. You cannot use other PowerShell or other Command Propmpt to execute this command. Open the WSL command-line tool, then enter this command to install the MC client software:
/mnt/wsl/minio-client$ curl https://dl.min.io/client/mc/release/linux-amd64/archive/mc.RELEASE.2022-10-29T10-09-23Z \
--create-dirs \
-o $HOME/minio-binaries/mc
chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/
After installation completes, enter mc --version
to verify a compatible version installed.
Log into the MinIO web portal to migrate the S3 service configuration settings and bucket(s) with bucket settings.
The S3 service does not support commands in the MinIO MC admin
utility needed to export/import configuration data from the the S3 service due to the age of the release.
Therefore, to migrate the S3 service deployment to the MinIO app deployment you must manually recreate all S3 configuration settings and buckets in the new MinIO deployment.
mc mirror
command (see step 8).Install the TrueNAS MinIO app.
TrueNAS Enterprise
TrueNAS Enterprise customers with a active support contract can contact iXsystems Support for assistance with the MinIO Enterprise app.
The MinIO Enterprise app requires you to create a self-signed certificate.
Create an alias for both the MinIO service deployment and the MinIO app deployment using the MC client software. Use either the Linux or WSL command line to enter this command twice, first for the S3 Service alias, then for the MinIO app alias:
mc alias set newalias path admin pa$$w0rd
Where:
Mirror the S3 service deployment to move bucket data contents to the MinIO app deployment buckets.
This process can take days to complete based on the amount of data in the S3 service deployment.
Mirror each bucket, one at a time, and waiting until the first bucket mirror operation completes before starting the next mirror operation. Enter this command using in the WSL or Linux command line tool:
mc mirror –preserve –watch source/bucket target/bucket
Where:
Wait for the mirror operation to complete before migrating the next bucket.
The --watch
flag monitors the S3 service deployment for new data throughout the process, which allows using the S3 service until the migration process completes but this greatly slows the data transfer.
The --watch
flag does not end when the transfer completes as it continually looks for new files added to the source.
The transfer rate does not reach zero as it is an average throughout the transfer.
To verify the transfer completed look at the number of objects and usage sizes of the source and target buckets.
Objects should match and the usage size should be similar but can differ slightly due to rounding differences between version.
Verify the migration is successful, then archive the S3 service. Check the MinIO app deployment to make sure it has all the settings, users, groups, policies, and that you can access stored data in the buckets. If everything is correct and you can access your data, either create an S3 archive copy, offline to a backup server, or delete the S3 dataset to free up storage capacity on the TrueNAS SCALE server.
Stop the S3 service in SCALE and disable Start Automatically, then end the MC mirror command using the WSL or Linux CLI (Ctrl C).
Edit the MinIO Charts app configuration port numbers to use the default 9000 and 9001.
This article applies to the public release of the MinIO Official Charts application.
MinIO fails to deploy if you update your version 2022-10-24_1.6.58 Minio app to 2022-10-29_1.6.59 or later using the TrueNAS web UI.
Your app logs display an error similar to the following:
ERROR Unable to use the drive /export: Drive /export: found backend type fs, expected xl or xl-single: Invalid arguments specified.
If you get this error after upgrading your MinIO app, use the app Roll Back function and return to 2022-10-24_1.6.58 to make your MinIO app functional again.
You need WSL2 (Windows Subsystem for Linux) if you are using a Windows computer.
If your system has sharing (SMB, NFS, iSCSI) configured, disable the share service before adding and configuring a new MinIO deployment. After completing the installation and starting MinIO, enable the share service.
If the dataset for the MinIO share has the same path as the MinIO application, disable host path validation before starting MinIO. To use host path validation set up a new dataset for the application with a completely different path. For example, for the share /pool/shares/minio and for the application /pool/apps/minio.
When adding a new MinIO deployment, verify your storage settings are correct in the MinIO wizard. If not set, click Add and enter the required information.
To manually update your MinIO application:
Follow the instructions here to make a new, up-to-date MinIO deployment in TrueNAS. Make sure it is version 2022-10-29_1.6.59 or later.
Download the MinIO Client here for your OS and follow the installation instructions. The MinIO Client (mc) lets you create and manage MinIO deployments via your system command prompt.
Open a terminal or CLI.
If you are on a Windows computer, open PowerShell and enter wsl
to switch to the Linux subsystem.
Change directories to the folder that contains
Add your old deployment to mc by entering: ./mc alias set old-deployment-name http://IPaddress:port/ rootuser rootpassword
.
Add your new deployment to mc using the same command with the new alias: ./mc alias set new-deployment-name http://IPaddress:port/ rootuser rootpassword
.
To port your configuration from your old MinIO deployment to your new, export your old MinIO app configurations by entering ./mc.exe admin config export old-deployment-name > config.txt
.
MinIO Client exports the config file to the current directory path.
Next, import the old app config file into the new app by entering: ./mc.exe admin config import old-deployment-name < config.txt
.
Restart the new MinIO app to apply the configuration changes.
./mc.exe admin service restart new-minio-deployment
Export the old app bucket metadata by entering ./mc.exe admin cluster bucket export old-minio-deployment
.
Import the metadata into the new app with ./mc.exe admin cluster bucket import new-minio-deployment cluster-metadata.zip
Export the old app IAM settings by entering ./mc.exe admin cluster iam export old-minio-deployment
.
Import the IAM settings into the new app with ./mc.exe admin cluster iam import new-minio-deployment alias-iam-info.zip
.
Create buckets in your new MinIO app to move data and objects to.
Move the objects and data from your old MinIO app to your new one using ./mc.exe mirror --preserve --watch source/bucket target/bucket
.
Repeat for every bucket you intend to move.
After moving all data from the old app to the new one, return to the TrueNAS UI Apps screen and stop both MinIO apps.
Delete the old MinIO app. Edit the new one and change the API and UI Access Node Ports to match the old MinIO app.
Restart the new app to finish migrating.
When complete and the app is running, restart any share services.
This article applies to the public release of the MinIO Official Charts application.
On TrueNAS SCALE 20.12-ALPHA and later, users can create a MinIO S3 distributed instance to scale out and handle individual node failures. A node is a single TrueNAS storage system in a cluster.
The examples below use four TrueNAS systems to create a distributed cluster. For more information on MinIO distributed setups, refer to the MinIO documentation.
Before configuring MinIO, you must create a dataset and shared directory for the persistent MinIO data. Go to Datasets and select the pool or dataset where you want to place the MinIO dataset. For example, /tank/apps/minio or /tank/minio. You can use either an existing pool or create a new one.
After creating the dataset, create the directory where MinIO stores information the application uses. There are two ways to do this, one as the root user and the other as the local administrator (admin). The root user can use either SCALE Shell or create a share that then creates the directory. The local administrator account (admin) can only create the share, then creates the directory. MinIO uses /data but allows users to replace this with the directory of their choice.
If logged in as root, go to System Settings > Shell, change to the /pool/dataset directory and then use the mkdir /mnt/data
command to create the /data directory.
If logged in as admin, create a share (i.e, an SMB share), log into that share, then create the directory.
For a distributed configuration, repeat this on all system nodes in advance.
Take note of the system (node) IP addresses or host names and have them ready for configuration. Also, have your S3 user name and password ready for later.
You can configure the MinIO application using either Launch Docker Image at the top right of the Apps screen, or the Install option on the MinIO Official Charts application widget. found on the Available Applications screen.
We recommend using the Install option on the MinIO application widget.
If your system has sharing (SMB, NFS, iSCSI) configured, disable the share service before adding and configuring a new MinIO deployment. After completing the installation and starting MinIO, enable the share service.
If the dataset for the MinIO share has the same path as the MinIO application, disable host path validation before starting MinIO. To use host path validation, set up a new dataset for the application with a completely different path. For example, for the share /pool/shares/minio and for the application /pool/apps/minio.
Turn the share service off before starting the MinIO application. After MinIO is running, enable the share service.
On your first node (system in the cluster). Go to Apps, click Available Applications, locate the MinIO Official Chart widget, and click Install to open the minio wizard.
Enter a name in Application Name (e.g. minio for a standard configuration or minio-distributed for a distributed MinIO configuration).
Select the update strategy from the Minio update strategy dropdown list. The best practice is to keep the default Create new pods and then kill old ones setting.
Next, enter the MinIO Configuration settings.
Select Enable Distributed Mode when setting up a cluster of SCALE systems in a distributed cluster. A MinIO in distributed mode allows you to pool multiple drives or TrueNAS SCALE systems (even if they are different machines) into a single object storage server for better data protection in the event of single or multiple node failures because MinIO distributes the drives across several nodes. For more information, see the Distributed MinIO Quickstart Guide.
Click Add to the right of Container Args twice to add two Arg fields to configure the Container Entrypoint arguments.
In the first Arg field, type server.
In the second Arg field, type the valid IP or host name of each TrueNAS system on the network, the MinIO port number, and the directory you created for MinIO.
Use this format:
To create a distributed cluster, add all the valid TrueNAS system (node) IP addresses/host names. Use the same order across all the nodes.
MinIO containers use server port 9000. The MinIO Console communicates using port 9001. Use the /data path that the following steps set up.
Enter the MinIO S3 root user in Root User and the S3 password in Root Password.
Next, create the Minio Environment Variables. Click Add twice to enter two blocks of settings.
Define the MINIO_ROOT USER and MINIO_ROOT_PASSWORD arguments and their values. For the values, use a name of up to 20 characters. For a password, use a string of 8 to 40 randomized characters. MinIO recommends using a long password string of unique random characters. Refer to MinIO User Management for more information.
Keep all passwords and credentials secured and backed up.
For a distributed cluster, ensure the values are identical between nodes and fill the Minio image environment values with proper random credentials.
You can configure the API and UI access node ports and the MinIO domain name if you have TLS configured for MinIO.
To store your MinIO container audit logs, select Enable Log Search API box and enter the amount of storage space logs may consume.
You can also configure a MinIO certificate if you wish.
Enter the Storage settings.
Select the dataset you created for the MinIO container for the Host Path and enter the
If you want to use a host path to store your MinIO data volume, select Enable Host Path for MinIO Data Volume and then select the path.
Under Extra Host Path Volumes, enter the
(Optional) Add the Advanced DNS Settings if you want to configure additional DNS options in Advanced DNS Settings. Click Add to add more DNS option entries. Click Next.
Click Save to complete the first node.
Now that the first node is complete, configure any remaining nodes (including datasets and directories).
After installing MinIO on all systems (nodes) in the cluster. Turn off (disable) the share service. Start the MinIO applications. When running, turn the share service back on (enable).
After you create datasets, you can navigate to the TrueNAS address at port :9000 to see the MinIO UI. After creating a distributed setup, you can see all your TrueNAS addresses.
Log in with the ROOT_USER and ROOT_PASSWORD keys you created as Container Environment Variables.
Before using SCALE to install the Netdata application you need to configure TrueNAS SCALE storage for the Netdata application to use.
Verify the local administrator account has sudo permissions enabled.
Set up an account with Netdata if you don’t already have one.
In this procedure you:
Add the storage Netdata uses
Install the Netdata app in SCALE
Netdata needs a primary dataset for the application (netdata).
SCALE Bluefin creates the ix-applications dataset in the pool you set as the application pool when you first go to the Apps screen. This dataset is internally managed so you cannot use this as the parent when you create the required Netdata dataset.
To create the Netdata dataset, go to Datasets, select the dataset you want to use as the parent dataset, then click Add Dataset to add a dataset. In this example, we create the apnetdat dataset under the root parent dataset tank.
Go to Apps to open the Applications screen and then click on the Available Applications tab.
Set the pool SCALE applications use.
If you have not installed an application yet, SCALE opens the Choose a pool for Apps dialog. Select the pool where you created the Netdata dataset from the Pools dropdown list and then click Choose to set the pool for all applications.
After SCALE finishes configuring the system to use this pool, a confirmation dialog displays. Click Close.
Locate the netdata widget and then click Install to open the netdata configuration wizard.
Enter a name for the app in Application Name and then click Next. This example uses netdata.
For a basic installation you can leave the default values in all settings. TrueNAS populates Node Port to use for Netdata UI with the default port number of 20489. If you wish to add an image environment, click the Add button and enter a Name and Value.
Storage for Netdata by default is configured without host path volumes enabled.
You can enable host paths for the Netdata Configuration, Cache and Library volumes by selecting their respective checkboxes. You can also specify additional host path volumes by clicking the Add button next to Extra Host Path Volumes, and providing the location of where the volume will be mounted inside the pod, as well as the path to the host.
The default DNS Configuration should be sufficient for a basic installation. If you want to specify additional DNS options, click the Add button next to DNS Options to enter a DNS Option Name and Option Value.
The checkbox for Enable Pod Resource limits is not selected by default.
When selected, additional fields display where you can specify CPU resource and memory limits.
Click Save. The Netdata app installation process begins. Go to Apps > Applications and click on the Installed Applications tab. The netdata widget shows the status of DEPLOYING.
Once installed, the netdata widget shows the status of ACTIVE. Clicking on the vertical ellipsis provides additional options to interact with the agent.
A successfully installed Netdata app displays in the Installed Applications tab with a status of Active.
Click on the Web Portal button. The Netdata agent dashboard displays. The Netdata agent dashboard provides a system overview that displays CPU usage and other vital statistics.
The Netdata agent displays a limited portion of the reporting capabilities of the Netdata app. Click on the Node View tab to better understand the differences between the Netdata agent and Netdata Cloud. Evaluate your system reporting needs.
To sign in to Netdata Cloud, click the Sign in to Netdata Cloud! button.
To stop the Netdata app, return to the Installed Applications tab and click the Stop button on the netdata widget.
Nextcloud is a drop-in replacement for many popular cloud services, including file sharing, calendar, groupware and more. One of its more common uses for the home environment is serving as a media backup, and organizing and sharing service. This procedure demonstrates how to set up Nextcloud on TrueNAS SCALE, and configure it to support hosting a wider variety of media file previews, including High Efficiency Image Container (HEIC), MP4 and MOV files. The instructions in this article apply to SCALE 22.12.0 and later.
Before using SCALE to install the Nextcloud application you need to configure TrueNAS SCALE storage for Nextcloud application to use.
Verify the local administrator account has sudo permissions enabled.
Set up an account with Nextcloud if you don’t already have one.
In this procedure you:
Add the storage Nextcloud uses
Install the Nextcloud app in SCALE
Nextcloud needs a primary dataset for the application (nextcloud), and four datasets, one it uses for the primary data volume (data), a postgres data volume (db) and one as a postgres backup volume (dbbackup), and an one for extra mount path volume (opt).
SCALE Bluefin creates the ix-applications dataset in the pool you set as the application pool when you first go to the Apps screen. This dataset is internally managed so you cannot use this as the parent when you create the required Nextcloud datasets.
To create the Nextcloud datasets, go to Datasets, select the dataset you want to use as the parent dataset, then click Add Dataset to add a dataset. In this example, we create the Nextcloud datasets under the root parent dataset tank.
Enter nextcloud in Name, make any other setting changes you want to make, and click Save.
Next, select the nextcloud dataset, click Add Dataset to add the data child dataset. Enter data in Name, make any other setting changes you want to make for the dataset, and click Save.
Repeat this three more times to add the other three child datasets to the nextcloud non-root parent dataset. Add one named db, the next dbbackup, and then finally opt.
When finished you should have the nextcloud parent dataset with four child datasets under it. Our example paths are:
Go to Apps to open the Applications screen and then click on the Available Applications tab.
Set the pool SCALE applications use.
If you have not installed an application yet, SCALE opens the Choose a pool for Apps dialog. Select the pool where you created the Nextcloud datasets from the Pools dropdown list and then click Choose to set the pool for all applications.
After SCALE finishes configuring the system to use this pool, a confirmation dialog displays. Click Close
Locate the nextcloud widget and then click Install to open the Nextcloud configuration wizard.
Enter a name for the app in Application Name and then click Next. This example uses nextcloud.
Enter a user name and password to use as a Nextcloud login on the Nextcloud Configuration settings screen. For a basic installation you can leave the default values in all settings except Username and Password. This example uses admin as the user. TrueNAS populates Nextcloud host with the IP address for your server and Nextcloud data directory with the correct path. The checkbox for Install ffmpeg is not selected by default. If selected, the utility FFmpeg is automatically installed when the container starts.
TrueNAS populates the Node Port to use for Nextcloud field with the correct port number. To specify an optional Nextcloud environment name and value, click the Add button.
Enter the storage settings for each of the four datasets created for Nextcloud.
a. Enter or browse to the location where you created the nextcloud/data dataset in Host Path for Nextcloud Data Volume. This example uses the /mnt/tank/nextcloud/data path.
b. Click Add to display the Mount Path in Pod and Host Path fields.
Enter the mount path in the Nextcloud container that you want to use in Mount Path in Pod. The example uses the same as the dataset path /opt.
Enter or browse to the location where you created the nextcloud/opt dataset in Host Path. This example uses the /mnt/tank/nextcloud/opt path.
c. Select Enable Host Path for Postgres Data Volume, and then enter or browse to the nextcloud/db dataset location in Host Path for Postgres Data Volume.
d. Select Enable Host Path for Postgres Backup Volume, and then enter or browse to the nextcloud/dbbackup dataset location in the Host Path for Progres Backup Volume.
Select Enable cronjobs for nextcloud on the CronJob configuration screen.
Accept the remaining setting defaults on the Scaling/Upgrade Policy and Advanced DNS Settings screens.
Scroll up to review the configuration settings and fix any errors or Save to complete the installation.
Click on the Installed Applications tab to see the nextcloud widget.
When the nextcloud widget displays ACTIVE, click Web Portal to open the NextCloud sign in screen in a new browser window.
SCALE includes the ability to run Docker containers using Kubernetes.
Always read through the Docker Hub page for the container you are considering installing so that you know all of the settings that you need to configure. To set up a Docker image, first determine if you want the container to use its own dataset. If yes, create a dataset for host volume paths before you click Launch Docker Image.
If you want to create a dataset for Pi-hole data storage, you must do this before beginning the Pi-hole application install.
When you are ready to create a container, click Apps to open the Applications screen, then click on Available Applications. Locate the pihole widget and click Install on the widget.
Fill in the Application Name and click Version to verify the default version is the only, and most current version.
Enter the password to use for the administrative user in Admin password in the Container Environment Variables section. The password entered can not be edited after you click Save. Adjust the Configure timezone setting if it does not match where your TrueNAS is located.
To add the WEBPASSWORD environment variable, click Add for Pihole Environment to add a block of environment variable settings. Enter WEBPASSWORD in Name, then a secure password like the example the one used, s3curep4$$word.
Scroll down to the Storage settings. Select Enable Custom Host Path for Pihole Configuration Volume to add the Host Path for Pihole Configuration Volume field and dataset browse option. Click the arrow to the left of
/mnt and at each dataset to expand the tree and browse to the dataset and directory paths you created before beginning the container deployment. Pi-hole uses volumes store your data between container upgrades.You need to create these directories in a dataset on SCALE using System Settings > Shell before you begin installing this container.
Click Add to display setting options to add extra host path volumes to the container if you need them.
Enter any Networking settings you want to use or customize. TrueNAS adds the port assignments Pi-hole requires in the Web Port for pihole, DNS TCP Port for pihole, and DNS UDP Port for pihole fields. TrueNAS SCALE requires setting all Node Ports above 9000. Select Enable Host Network to add host network settings. Click Add for DNS Options to add a block of DNS settings if you want to configure DNS options.
Click Add for DNS Options if you want to configure DNS for your pod. Select Enable Pod resource limits if you want to limit the CPU and memory for your Pi-hole application.
Click Save. TrueNAS SCALE deploys the container. If correctly configured, the Pi-Hole widget displays on the Installed Applications screen.
When the deployment is completed the container becomes active. If the container does not automatically start, click Start on the widget. Clicking on the App card reveals details on the app.
With Pi-hole as our example we navigate to the IP of our TrueNAS system with the port and directory address :9080/admin/.
This application in not needed when rsync is configured externally with SSH or with the TrueNAS built-in rsync task in SSH mode. It is always recommended to use rsync with SSH as a security best practice.
This application is an open source server that provides fast incremental file transfers.
Before you configure the new rsync application:
Validate that this application is needed. When rsync is configured externally with SSH or an rsync task is created in Data Protection > Rsync Tasks and Rsync Mode is SSH, the deprecated System Settings > Rsync service is not used or necessary for rsync to function.
Disable the rsync service. Go to System Settings > Services and disable the service and clear the Start Automatically checkbox. This prevents the service from re-enabling after a system restart.
When necessary, review your rsync and module service settings. Note all host path, access mode type, number of simultaneous connections, user and group IDs, the allow and deny host addresses, and any auxiliary parameter settings.
After disabling the rsync service, install the rsyncd application. Go to Apps click on Available Applications and locate the rsyncd application widget.
Click Install to open the rsyncd configuration wizard.
Accept the default value or enter a name in Application Name.
If you want to add additional parameters, click Add to the right of Auxilliary Parameters.
You can specify rsyncd global or module parameters using the Auxilliary Parameters fields.
Accept the default port number rsync listens on, or to change it, enter a new port number in Rsync Port. We recommend that you leave Host Network unselected.
To configure a module, click Add to display the Module Configuration fields. A module creates an alias for a connection (path) you want to use rsync with.
Enter a name in Module Name. Allowed characters are upper and lowercase alphanumeric characters, numbers, and the underscore (_), hyphen (-) and dot (.). Do not begin or end the name with the special characters.
Use Comment to enter an optional description that displays next to the module name when clients obtain a list of available modules. Default is to leave this field blank.
Leave Enable Module selected, then enter or browse to the location where you want to use rsync (destination path) in Host Path.
Select the type of access from the Access Mode dropdown list. Specify the maximum number of simultaneous connections you want to allow in Max Connections or accept the default 0 which means unlimited. Accept the default values in UID and GID, or change to the user and group ID you want to use for the connection.
To specify a list of allowed or denied hosts, click Add for each host you want to enter. Leave blank to allow all or deny no hosts.
Accept the default values in Resources Configuration or enter the CPU and memory values for the destination system.
Click Save.
This article provides instructions on installing the new tftpd-hpa application. It also provides instructions on migrating from the deprecated SCALE 22.12.3 TFTP service to the tftpd-hpa application.
The tftpd-hpa application is a lightweight TFTP-server container TrueNAS SCALE uses as a replacement for the SCALE service. It is not intended for use as a standalone container.
Before you configure the new tftpd-hpa application:
Disable the TFTP service. Go to System Settings > Services and disable the service and clear the Start Automatically checkbox. This prevents the service from re-enabling after a system restart.
Review your TFTP service settings and note all directory, host, auxiliary parameter, permission, and credential (username and password) settings.
To grant access to a specific user (and group) different from defaults, add the new non-root administrative user and note the UID and GID for this user.
To use a specific dataset or volume for files, create this in the Storage screen first.
After disabling the TFTP service, install the tftpd-hpa application. Go to Apps click on Available Applications and locate the tftpd-hpa application widget.
Click Install to open the tftpd-hpa configuration wizard.
Accept the default value or enter a name in Application Name.
Select the location of the TrueNAS server in Timezone.
To add environmental variables, click Add to the right of Additional Environmental Variables.
To allow creating new files, select Allow Create, then click Add to display the Name and Value fields. Enter CREATE in Name and 1 in Value. Click Add again, then enter MAPFILE in Name and "": in Value. Do not use the mapfile just enter this setting.The tftpd-hpa app uses default port 69 when Host Network is selected.
To change the default port number, select Host Network to clear the checkmark and display the TFTP Port field. Enter a new port number in TFTP Port.
Accept the default value in TFTP Boot Storage Type. To use the dataset created for TFTP file storage, select Host Path (Path that already exists on the system) in Type to displays the Host Path field. Browse to select the dataset created for TFTP file storage or enter the full path.
Click Save.
The WebDav application is a set of extensions to the HTTP protocol which allows users to collaboratively edit and manage files on remote web servers, and serves as the replacement for the built-in TrueNAS SCALE WebDAV feature.
When installed and configured with at least one share, a container launches with temporary root privileges to configure the shares and activate the service. The Fix Permissions checkbox allows TrueNAS to apply the correct permissions to the WebDAV shares and directories and simplify app deployment. After first configuration, the WebDAV container runs as the dedicated webdav user (UID: 666).
WebDAV only supports Unix-style permissions. When the application is deployed and Fix Permissions is enabled, this destroys any existing permissions scheme on the shared dataset. It is recommended to only share newly created datasets that have the Share Type set to Generic.
Before WebDAV application deployment:
Disable the WebDAV service (when active). Go to System Settings > Services and disable the service, then clear the Start Automatically checkbox to prevent the service from re-enabling after a system restart.
Review any existing WebDAV service authentication settings and note all IP addresses, port numbers, URLs and credentials (username and password).
Remove any existing WebDAV shares. Go to Shares > WebDAV and edit any existing configurations. Record the Name, Path, and Read Only settings and then delete the WebDAV share configuration.
If you want to grant access to a specific user (and group) other than the defaults, add the new non-root administrative user and take note of the UID and GID for this user. If any existing shares were created with the webdav user and group in control, note the UID and GID (666) to recreate the previous WebDAV share in the application.
After disabling the WebDAV service and clearing any existing share configurations from the Shares > WebDAV screen, install the WebDAV application. Go to Apps click on Available Applications and locate the WebDAV application widget.
Click Install to open the webdav configuration wizard.
Select the authentication from the Authentication Type dropdown.
No Authentication means any system that can discover TrueNAS can access the data shared by WebDAV. Due to security concerns, this is not recommended.
Selecting Basic Authentication displays credential settings.
Enter the username and password information for your WebDAV share (noted from the previous WebDAV service settings).
Set Enable HTTPS to add encryption to the web traffic between clients and the server. This requires opening an additional HTTPS Port and adding a system Certificate.
The truenas_default Certificate can be used as the Certificate when no other specific certificates are available.
Add your existing WebDAV share to the application. Click Add to the right of Shares in the Storage Configuration section.
Enter the Share Name. This can be the share name recorded from a configuration in Shares > WebDAV.
A share description is not required by can be a useful place to record notes about the share.
Enter or browse to the Host Path location for the WebDAV share dataset. Use a path previously used in a saved configuration from Shares > WebDAV.
Select Read Only to make the share read only and disable write access to the share. When selected, data accessed by clients cannot be modified.
Set Fix Permissions to change the Host Path filesystem permissions. The dataset owner becomes the User ID and Group ID set in the User and Group Configuration section. By default, this is the webdav user with UID and GID 666.
To specify a different user, enter the user ID (UID) and group ID (GID) in the fields for these settings. When migrating from an existing built-in WebDAV share, you might need to adjust the default to use whatever UID and GID was previously configured as the share path owner.
Click Save to save the configuration, deploy the app, and make any enabled Shares accessible.
At the end of this migration process, test access to your WebDAV share.
In a browser, this is done by opening a new tab and entering the configured protocol, system host name or IP address, WebDAV port number, and Share Name.
Example: https://my-truenas-system.com:30001/mywebdavshare
When authentication is set to something other than No Authentication, a prompt requests a user name and password. Enter the saved Username and Password entered in the webdav application form to access the shared data.
To change files shared with the WebDAV protocol, use client software such as WinSCP to connect to the share and make changes. The WebDAV share and dataset permissions must be configured so that the User ID and Group ID can modify shared files.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
This article provides installation instructions for the WG-Easy application. WG-Easy is a docker image designed to simplify setting up and managing WireGuard connections. WG-Easy provides a pre-configured environment that includes all the necessary components including a web-based user interface to manage VPN connections.
If migrating from the SCALE OpenVPN client and server services to a new application for VPN servers, locate the VPN app you want to use on the Available Appliations screen. If not listed, install the application using the Launch Docker Image option.
Before you configure a new VPN application:
Disable OpenVPN services. Go to System Settings > Services, disable the services, and clear the Start Automatically checkboxes. This prevents the services from re-enabling after a system restart.
Review your client and server service settings. Note all certificate, device type, port, protocol, TLS crypt authentication, and additional parameter settings.
To install the wg-easy application:
Go to Apps click on Available Applications and locate the wg-easy application widget.
Click Install to open the wg-easy configuration wizard.
Accept the default value or enter a name in Application Name.
Enter the configuration settings. Enter the public host name or IP of your VPN server in Hostname or IP.
If you use or want to protect access to the WG-Easy web UI, enter a password in Password for WebUI.
Accept the default values in Persistent Keep Alive and Clients MTU or enter the values you want to use. To change the time the connection remains alive, enter a value in seconds in Persistent Keep Alive. When set to zero, connections are not kept alive.
Accept the default IPs in Clients IP Address Range and Clients DNS Server or enter the IP addresses the client uses.
To specify allowed IP addresses, click Add to the right of Allowed IPs for each IP address you want to enter. If you do not specify allowed IPs, the application uses 0.0.0.0/0.
To specify environment variables, click Add to the right of WG-Easy Environment for each environment variable you want to add. Variables you can add are listed in the table below.
Enter your storage settings. Select Enable Custom Host Path for WG-Easy Configuration Volume to add the Host Path for WG-Easy Configuration Volume field. Enter or browse to select the mount path for the host path.
To add additional host path volumes, click Add to the right of Extra Host Path Volumes.
Enter the path in Mount Path in Pod where you want to mount the volume inside the pod. Enter or browse to the host path for the WG-Easy application dataset.
Accept the default port numbers in WireGuard UDP Node Port for WG-Easy and WebUI Node Port for WG-Easy. WireGuard always listens on 51820 inside the Docker container. Refer to the TrueNAS default port list for a list of assigned port numbers. To change the port numbers, enter a number within the range 9000-65535.
To add DNS configuration options, click Add to the right of DNS Options.
Accept the default values in Resources Configuration or select Enable Pod resource limits to enter new CPU and memory values for the destination system.
Click Save.
TrueNAS is certified with leading hypervisors and backup solutions to streamline storage operations and ensure compatibility with your existing IT infrastructure. TrueNAS Enterprise storage appliances deliver a wide range of features and scalability for virtualization and private cloud environments, with the ability to create off-site backups with scheduled sync and replication features.
TrueNAS Enterprise
TrueNAS applications expand the capabilities of your system by adding third-party software but can add significant risk to system stability and security. It is not recommended to deploy applications on SCALE Enterprise High Availability (HA) systems.
SCALE Enterprise licensed systems do not have applications available by default. This feature is enabled as part of the Enterprise license after consulting with iXsystems. Applications should only be installed with the assistance of an iXsystems Support.
There are general best practices to keep in mind when using applications with TrueNAS SCALE:
We recommend users keep the container use case in mind when choosing a pool. Select a pool that has enough space for all the application containers you intend to use. TrueNAS creates an ix-applications dataset on the chosen pool and uses it to store all container-related data. This is for internal use only. If you intend to store your application data in a location that is separate from other storage on your system, create a new dataset.
Since TrueNAS considers shared host paths non-secure, apps that use shared host paths (such as those services like SMB are using) fail to deploy. Best practice is to create datasets for applications that do not share the same host path as an SMB or NFS share.
Kubernetes is an open-source container orchestration system that manages container scheduling and deployment, load balancing, auto-scaling and storage. The default system-level Kubernetes Node IP settings can be found in Apps > Settings > Advanced Settings.
Docker is an open platform for developing, shipping, and running containerized applications. The Launch Docker Image button starts the Docker configuration wizard. You cannot interrupt the configuration wizard and save settings to leave and go create data storage or directories in the middle of the process. We recommend having your Docker configuration information ready before starting the wizard. You should have acces to information such as:
TrueNAS SCALE allows you to configure an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings. You should know your Kerberos realm and keytab information. You may need to supply your LDAP server host name, LDAP server base and bind distinguished names (DN) and the bind password.
Determine the container and node port numbers. TrueNAS SCALE requires that the node port be above 9000. Ensure that the ports are not already in use.
iXsystems Support can assist Enterprise customers with configuring directory service settings in SCALE with the information customers provide, but they do not configure customer Active Directory system settings.
TrueNAS Enterprise
The instructions in this article apply to the Official TrueNAS Enterprise MinIO application. This smaller version of MinIO has been tested and polished for a safe and supportable experience for TrueNAS Enterprise customers. To use the complete MinIO app without iXsystems support, see the application that is available in the Community Apps catalog.
We recommend that TrueNAS SCALE Enterprise (HA) systems not deploy applications.
SCALE Enterprise single controller systems with the applications and virtual machines license feature have access to the MinIO Official Enterprise widget.
Community users can add this version of MinIO application by going to Manage Catalogs. Edit the Official catalog by selecting enterprise in Preferred Trains, and then click Save. Both the Official Charts and Enterprise MinIO widgets display on the Available Applications screen.
If your system has active sharing configurations (SMB, NFS, iSCSI), disable these sharing services in System Settings > Services before adding and configuring the MinIO application. Start any sharing services after MinIO completes the install and starts.
If you created a dataset for MinIO shares with the same path as the MinIO application, disable host path validation. To use host path validation, create datasets for the share and application with unique paths. For example, /pool/shares/minio for the share and /pool/apps/minio for the application.
This basic procedure covers the required Enterprise MinIO App settings. It does not provide instructions for optional settings.
Go to Apps, click on Available Applications and locate the MinIO Enterprise train application widget.
Click Install on the MinIO Official Enterprise widget to open the minio installation wizard.
Accept the default or enter a name for your MinIO application deployment.
Version populates with the current MinIO version.
Enter the MinIO access key in Root User and the secret key in Root Password.
TrueNAS populates the User and Group Configuration and Network Configuration settings with the default port values for MinIO Enterprise.
Do not select Host Network.
Select the certificate from the Certificate dropdown. If migrating from the TrueNAS S3 service, select the S3 MinIO certificate.
Scroll down to the Storage Configuration section.
Select the storage type you want to use. Default is ixVolume (Dataset created automatically by the system). This creates a dataset for your deployment and populates the rest of the storage fields.
To use an existing dataset, select Host Path (Path that already exists on the system). Mount Path populates with /data or /data#, where # is a number to distinguish multiple instances of MinIO such as in a cluster configuration. Browse to the location of the dataset and click on it to populate the Host Path.
The remaining minio wizard settings are optional.
Click Save to complete the installation.
When migrating from the deprecated S3 service for MinIO to the MinIO Enterprise train application, before you install the MinIO Enterprise application:
Disable the S3 service. Go to System Settings > Services and disable the service and clear the Start Automatically checkbox. This prevents the service from re-enabling after a system restart.
Review your S3 service and MinIO settings. Note all IP addresses, port numbers, TLS server host name, access and secret keys, storage, and certificate settings.
You can use the dataset created for S3 MinIO as the dataset for the MinIO Enterprise application or create a new dataset in the MinIO Enterprise application wizard.
If you want to grant access to a specific user (and group) other than using the defaults, add the new non-root administrative user and take note of the UID and GID for this user.
After disabling the S3 service, install the MinIO Enterprise train application.
Follow the instructions in Installing MinIO Enterprise to complete the process.
The Kubernetes Settings screen allows users to customize network, system, and cluster settings for all apps in TrueNAS SCALE.
TrueNAS SCALE uses host path safety checks to ensure that host path volumes are secure when creating apps. We recommend creating datasets for applications that do not share the same host path as an SMB or NFS share.
Since TrueNAS considers shared host paths non-secure, apps that use shared host paths (such as an SMB shared dataset) fail to deploy.
If you group share and application data under a common dataset (such as media) where both use a path such as /tank/media/, the application fails to deploy.
You can still group shares and applications under media, but you must alter the path for shares and apps, such as /tank/media-shares or /tank/media/shares/sharename, and /tank/media-apps or /tank/media/apps/appname.
The paths differ enough to use host path validation and avoid issues that prevent application deployment.
We do not recommend disabling host path safety checks since shared host paths are non-secure.
If you want apps to deploy in a shared host path, disable Enable Host Path Safety Checks in Applications > Settings > Advanced Settings
Disabling host path safety checks might be helpful if you intend to have an app running in a shared dataset. For example, if you have apps that perform virus detection or media management and want them to work on files in your shared dataset.
TrueNAS Enterprise
Syncthing is available to Enterprise systems with the appropriate VM and applications license. Community users can add Syncthing to the list of available applications by adding Enterprise to the Official catalog on the Manage Catalogs screen.
Syncthing is tested and validated to work in harmony with TrueNAS platforms and underlying technologies such as ZFS to offer a turnkey means of keeping data across many systems. It can seamlessly integrate with TrueNAS.
Syncthing is a file synchronization application that provides a simple and secure environment for file sharing between different devices and locations.
Use it to synchronize files between different departments, teams, or remote workers.
Syncthing does not use or need a central server or cloud storage. All data is encrypted and synchronized directly between devices to ensure files are protected from unauthorized access.
Syncthing is easy to use and configure. You can install on a wide range of operating systems, including Windows, macOS, linux, FreeBSD, iOS or Android. The Synchthing web UI provides users with easy management and configuration of the application software.
You can add a dataset for Syncthing storage (for example, syncthing) before you install the application or create the dataset through the application installation wizard.
Decide on a consistent file-naming convention to avoid conflict situations where data does not or cannot synchronize because of file name conflicts. Path and file names in the Syncthing application are case sensitive. Creating a file named MyData.txt is not the same mydata.txt file in Syncthing.
If not already complete, set the pool for applications to use.
Go to Apps > Available Applications, locate the Syncthing application widget.
Click Install to open the sycnthing configuration wizard.
Accept the default value or enter a name in Application Name.
Select the timezone where the TrueNAS server is located from the Timezone dropdown list.
Accept the default user and group ID settings.
If selected, Host Network binds to the default host settings programmed for Syncthing. To manually enter your local network settings, select Host Network to clear the checkmark and display the TCP Port (File Transfer) and QUIC (UDP) Port (File Transfer) fields.
We recommend you accept the default port settings. If you plan to change these values, see [Default Ports]({{> relref “DefaultPorts.md” }}) to see which port numbers are available.
Select the certificate from the Certificates dropdown list.
Configure the storage settings. To use the dataset TrueNAS creates for Syncthing, leave Type set to ixVolume (Dataset created automatically by the system). To use a dataset you created for Syncthing, select Host Path (Path that already exists on the system). Enter or browse to delect the dataset you created and to populate the Host Path field (for example, /mnt/tank/syncthing/config).
To add a dataset path inside the container for where to mount the storage, click Add to the right of Additional Storage, then enter the mount path to use.
Enter or browse to select the host path you added for the container pod to use (for example, /mnt/tank/syncthing/data1). You can add a dataset in the Host Path field by typing / followed by the dataset name to the end of the path (for example /nmt/pool/adddatasetname).
Click Add for each dataset mount and host path you want to add (for example, /mnt/tank/syncthing/data2).
Accept the default resource configuration values for CPU and memory, or enter new values you want to use for Syncthing.
Click Save.
After installing the application, go to Installed Applications and click Start on the Syncthing application widget. Next open the Syncthing web UI and set up a user name and password.
After installing and starting the Syncthing application, launch the Syncthing webUI. Go to Actions > Settings and set a user password for the web UI.
The Syncthing web UI allows administrators to monitor and manage the synchronization process, view logs, and adjust settings.
Folders list configured sync folders, details on sync status and file count, capacity, etc. To change folder configuration settings, click on the folder.
This Device displays the current system IO status including transfer/receive rate, number of listners, total uptime, sync state, and the device ID and version.
Actions displays a dropdown list of options that includes general and global settings. You can manage directional settings for sync configurations, security, encryption, and UI server settings through the Actions options.
To change or enter a directory paty for a folder you want to share, click on a folder and select Edit. We recommend each shared folder have sync folder to allow for more granular traffic and data flow. Syncthing creates a default sync folder in the main user or HOME directory during installation of the application.
The Sharing tab shows the devices synced with the current folder (for example, the Home_Sync folder).
Untrusted Device Password is a beta feature and not trusted for production environments. This feature is for an edge cases where two users want to share data on a given device but cannot risk interception of data. Only trusted users with the code can open the file(s) with shared data.
File Versioning applies to changes received from other devices. For example, Bill turns on versioniong and Alice changes a file. Syncthing archives the old version on Bill’s computer when it syncs the change from Alice. But if Bill changes a file locally on his computer, Syncthing does not and cannot archive the old version.
For more information on specific file versioning, see Versioning
Go to Actions > Advanced to access advanced settings. These setting options allow you to set up network isolation, directory services, database, and bandwidth throttling, and to change device-specific settings and global default settings.
Incorrect configuration can damage folder contents and render Syncthing inoperable!
Go to Logs to access current logs and debug files. The Log tab displays current logs, and the Debugging Facilities tab provides access to debug logging facilities. Select different parameters to add to the logs and assist with debugging specific functionalities.
You can forward logs to a specific folder or remote device.
Syncthing includes the ability to maintain ownership and extend attributes during transfers between nodes (systems). This ensures ACLs and permissions remain consistent across TrueNAS SCALE systems during one and bi-directional Syncthing moves. You can configure this setting on a per folder basis.
TrueNAS has a built-in reporting engine that provides helpful graphs and information about the system.
Reporting data is saved to permit viewing and monitoring usage trends over time. This data is preserved across system upgrades and restarts.
Because reporting data is written frequently do not store it on the boot pool or operating system device.
TrueNAS clears the report history when you change the report CPU, graph age, or graph points options.
Data files are saved in
Click the settings to open the Reports Configuration configuration screen where you control how TrueNAS displays the graphs.
Select the general options you want to use in your TrueNAS.
Specify either the host name or IP address of the Graphite server you want to use.
Click Save.
To increase TrueNAS reporting functionality connect it to our TrueCommand multi-system management software.
TrueCommand Reports offer enhanced features like creating custom graphs and comparing utilization across multiple systems.
Click on and drag a certain range of the graph to expand the information displayed in that selected area in the Graph. Click on the icon to zoom in on the graph. Click on the icon to zoom out on the graph. Click the to move the graph forward. Click the to move the graph backward.
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 block (iSCSI) shares targets, Windows SMB shares, Unix (NFS) shares, and WebDAV shares.
When creating zvols for shares, avoid giving them names with capital letters or spaces since they can cause problems and failures with iSCSI and NFS shares.
Since the Apple Filing Protocol (AFP) for shares is deprecated and no longer receives updates, it is not in TrueNAS SCALE.
However, users can sidegrade a TrueNAS CORE configuration into SCALE, so TrueNAS SCALE migrates previously-saved AFP configurations into SMB configurations.
To prevent data corruption that could result from the sidegrade operation, in TrueNAS SCALE, go to Windows (SMB) Shares, select the
for the share, then select Edit to open the Edit SMB screen. Click Advanced Options and scroll down to the Other Options section. Select Legacy AFP Compatibility to enable compatibility for AFP shares migrated to SMB shares. Do not select this option if you want a pure SMB share with no AFP relation.Netatalk service is no longer in SCALE as of version 21.06. AFP shares automatically migrate to SMB shares with the Legacy AFP Compatibility option enabled. Do not clear the Legacy AFP Compatibility checkbox, as it impacts how data is written to and read from shares. Any other shares created to access these paths after the migration must also have Legacy AFP Compatibility selected.
Once you have sidegraded from CORE to SCALE, you can find your migrated AFP configuration in Shares > Windows Shares (SMB) with the prefix AFP_. To make the migrated AFP share accessible, start the SMB service.
Since AFP shares migrate to SMB in SCALE, you must use SMB syntax to mount them.
On your Apple system, press +K or go to Go > Connect to Server….
Enter smb://ipaddress/mnt/pool/dataset, where:
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 may 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.
To get started with iSCSI shares, make sure you have already created a zvol or a dataset with at least one file to share.
Go to Shares and click Configure in the Block (iSCSI) Shares Targets window. You can either use the creation wizard or set one up manually.
TrueNAS SCALE offers two methods to add an iSCSI block share: the setup wizard or the manual steps using the screen tabs. Both methods cover the same basic steps but have some differences.
The setup wizard requires you to enter some settings before you can move on to the next screen or step in the setup process. It is designed to ensure you configure the iSCSI share completely, so it can be used immediately.
The manual process has more configuration screens over the wizard and allows you to configure the block share in any order. Use this process to customize your share for special uses cases. It is designed to give you additional flexibility to build or tune a share to your exact requirements.
Have the following ready before you begin adding your iSCSI block share:
This section walks you through the setup process using the wizard screens.
This procedure walks you through adding each configuration setting on the seven configuration tab screens. While the procedure places each tab screen in order, you can select the tab screen to add settings in any order.
TrueNAS SCALE allows users to add iSCSI targets without having to set up another share.
To turn on the iSCSI service, from the Block (iSCSI) Shares Targets widget click the
and select Turn On Service. You can also go to System Settings > Services and locate iSCSI on the list and click the Running toggle to start the service.Set iSCSI to start when TrueNAS boots up, go to System Settings > Services and locate iSCSI on the list. Select Start Automatically.
Clicking the edit returns to the options in Shares > Block (iSCSI) Shares Targets.
Connecting to and using an iSCSI share can differ between operating systems.
This article provides instructions on setting up a Linux and Windows system to use the TrueNAS iSCSI block share.
In this section, you start the iSCSI service, log in to the share, and obtain the configured basename and target. You also partition the iSCSI disk, make a file system for the share, mount it, and share data.
This section provides instructions on setting up Windows iSCSI Initiator Client to work with TrueNAS iSCSI shares.
TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage in an iSCSI share.
To expand a Zvol LUN, go to Datasets and click the Zvol LUN name. The Zvol Details widget displays. Click the Edit button.
Enter a new size in Size for this zvol, then click Save.
TrueNAS prevents data loss by not allowing users to reduce the Zvol size. TrueNAS also does not allow users to increase the Zvol size past 80% of the pool size.
You need to know the path to the file to expand a file-based LUN. Go to Shares and click Configure in the Block (iSCSI) Shares Targets window, then select the Extents tab.
Click the more_vert next to the file-based LUN and select Edit.
Highlight and copy the path to the extent, then close the Edit Extent window.
Go to System Settings > Shell and input sudo truncate -s +[size] [path to file]
, where [size] is how much space you want to grow the file by, and [path to file] is the file path you copied earlier. Then press Enter.
In our example, the command looks like this: sudo truncate -s +1g /mnt/tankgrem3/test83/filelun
Lastly, go back to the extent in Shares > Block (iSCSI) Shares.
Click the Configure button in the window header, then click the Extents tab. Lastly, click the more_vert next to the file-based LUN and select Edit. Make sure the Filesize for the file-based LUN is set to 0 so that the share uses the actual file size. Click Save to retain any changes.
Creating a Network File System (NFS) share on TrueNAS makes a lot of data available for anyone with share access. Depending on the share configuration, it can restrict users to read or write privileges.
NFS treats each dataset as its own file system. When creating the NFS share on the server, the specified dataset is the location that client accesses. If you choose a parent dataset as the NFS file share location, the client cannot access any nested or child datasets beneath the parent.
If you need to create shares that include child datasets, SMB sharing is an option. Note that Windows NFS Client versions currently support only NFSv2 and NFSv3.
Before creating an NFS share, create the dataset you want the share to use for data storage.
It is best practice to use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
We recommend creating a new dataset with the Share Type set to Generic for the new NFS share.
Go to Shares > Unix (NFS) Shares and click Add to open the Add NFS Share configuration screen.
Enter the path or use the
icon to the left of /mnt to locate the dataset and populate the path.Enter text to help identify the share in Description.
If needed, enter allowed networks and hosts.
If needed, adjust access permissions.
Click Save to create the share.
After adding the first NFS share, the system opens an enable service dialog.
Enable Service turns the NFS service on and changes the toolbar status to Running. If you wish to create the share without immediately enabling it, select Cancel.
If you want to enter allowed networks, click Add to the right of Add Networks. Enter an IP address in Authorized Networks 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.
If you want to enter allowed systems, click Add to the right of Add hosts. Enter a host name or IP address to allow that system access to the NFS share. Click Add for each allowed system you want to define. Defining authorized systems restricts access to all other systems. Press the X to delete the field and allow all systems access to the share.
If you want to tune the NFS share access permissions or define authorized networks, click Advanced Options.
Select Read-Only to prohibit writing to the share.
To map user permissions to the root user, enter a string or select the user from the Maproot User dropdown list. To map the user permissions to all clients, enter a string or select the user from the Mapall User dropdown list.
To map group permissions to the root user, enter a string or select the group from the Maproot Group dropdown list. To map the group permissions to all clients, enter a string or select the group from the Mapall Group dropdown list.
Select an option from the Security dropdown. If you select KRB5 security, you can use a Kerberos ticket. Otherwise, everything is based on IDs.
To edit an existing NFS share, go to Shares > Unix Shares (NFS) and click the share you want to edit. The Edit NFS screen settings are identical to the share creation options.
To begin sharing, click the
on the toolbar and select Turn On Service. Turn Off Service displays if NFS is on. Turn On Service displays if NFS is off.Or you can go to System Settings > Services, locate NFS, and click the toggle to running. Select Start Automatically if you want NFS to activate when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
To configure NFS service settings, click edit on the System Settings > Services screen.
Unless you need specific settings, we recommend using the default NFS settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
Although you can connect to an NFS share with various operating systems, we recommend using a Linux/Unix OS.
First, download the nfs-common
kernel module.
You can do this using the installed distribution package manager.
For example, on Ubuntu/Debian, enter command sudo apt-get install nfs-common
in the terminal.
After installing the module, connect to an NFS share by entering sudo mount -t nfs {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}
.
Where {IPaddressOfTrueNASsystem} is the remote TrueNAS system IP address that contains the NFS share, {path/to/nfsShare} is the path to the NFS share on the TrueNAS system, and {localMountPoint} is a local directory on the host system configured for the mounted NFS share.
For example, sudo mount -t nfs 10.239.15.110:/mnt/Pool1/NFS_Share /mnt
mounts the NFS share NFS_Share to the local directory /mnt.
You can also use the Linux nconnect
function to let your NFS mount support multiple TCP connections.
To enable nconnect
, enter sudo mount -t nfs -o rw,nconnect=16 {IPaddressOfTrueNASsystem}:{path/to/nfsShare} {localMountPoint}
.
Where {IPaddressOfTrueNASsystem}, {path/to/nfsShare}, and {localMountPoint} are the same ones you used when connecting to the share.
For example, sudo mount -t nfs -o rw,nconnect=16 10.239.15.110:/mnt/Pool1/NFS_Share /mnt
.
By default, anyone that connects to the NFS share only has read permission. To change the default permissions, edit the share, open the Advanced Options, and change the Access settings.
You must have ESXI 6.7 or later for read/write functionality with NFSv4 shares.
SCALE 22.12.3 and continuing with SCALE 22.12.4 deprecates the built-in WebDAV sharing feature and no longer allows creating new WebDAV shares from these screens. All existing WebDAV shares remain saved and continue to be editable until the next major TrueNAS SCALE version (23.10) removes the Sharing > WebDAV and System Settings > Services > WebDAV screens from the TrueNAS web interface.
To create new or migrate existing WebDAV sharing configurations, see the webdav application tutorial
A Web-based Distributed Authoring and Versioning (WebDAV) share makes it easy to share a TrueNAS dataset and its contents over the web.
Go to Shares and click on Add on the WebDAV
widget. The first WebDAV share added to your system opens the No WebDAV screen. Click Add WebDAV to open the Add WebDAV configuration screen.Enter a share Name.
Add the path to the pool or dataset in Path. Enter or use the
icon to the left of /mnt to browse to the dataset and populate the path. An optional Description helps to identify the share. To prevent user accounts from modifying the shared data, set Read Only.To change existing ownership of all files in the share to the webdav user and group accounts leave Change User & Group Ownership selected. This default simplifies WebDAV share permission, but is unexpected, so the web interface displays a warning:
If you clear the Change User & Group Ownership checkbox this warning does not display and you must manually set shared file ownership to the webdav or www user and group accounts.
Click Save to add the share. The Enable service dialog opens. Click Enable Service to start the service or click Cancel to start the service at a later time.
To automatically start the service when TrueNAS boots, select Start Automatically.
Click edit to change the service settings.
For better data security, set Protocol to HTTPS. If you require it, you must choose an SSL certificate (freenas_default is always available). Define a number in the Port field. But do not use the default 8080 or reuse the same port number. Make sure the network is not already using the WebDAV service port.
To prevent unauthorized access to the shared data, set HTTP Authentication to either Basic or Digest and create a new Webdav Password. Do not use the default password davtest as it is a known password.
TrueNAS requires a username and password when setting the Authentication WebDAV service option to Basic or Digest. Enter the user name webdav and the password defined in the WebDAV service.Changing the HTTP Authentication setting to either Basic or No Authentication creates security risks, and mounting WebDAV shares in Windows might require adjusting the Windows registry to allow for insecure authentication methods. This is not recommended.
Click Save after making changes.
To mount the share in Windows:
Open File Explorer and right click on This PC, then click Map network drive.
Click Connect to a Web site that you can use to store your documents and pictures.
Choose a custom network location on Where do you want to create this network location?, then click Next.
Click through the screens until you see Specify the location of your website, and enter the URL to the configured WebDAV location (IP address:8080/Sharename).
Enter the WebDAV user name and password.
Click through until you can click Finish.
Confirm the WebDAV folder displays in File Explorer as a mapped hard drive.
Creating a share allows users to activate the WebDAV service.
You can enable the service from the Sharing screen Enable Service dialog or from the WebDAV
widget toolbar option. Click and then click Turn On Service. Or you can go to System Settings > Services and scroll down to WebDAV and click the toggle to Start.WebDAV shared data is accessible from a web browser.
To see the shared data, open a new browser tab and enter {PROTOCOL}://{TRUENASIP}:{PORT}/{SHAREPATH}
where the elements in curly brackets {}
are variables to replace with your chosen WebDAV share and service settings.
For example: https://10.2.1.1:8081/newdataset
This section has tutorials for creating and managing various specific configurations of SMB share.
SMB (also known as CIFS) is the native file-sharing system in Windows. SMB shares can connect to most operating systems, including Windows, MacOS, and Linux. TrueNAS can use SMB to share files among single or multiple users or devices.
SMB supports a wide range of permissions, security settings, and advanced permissions (ACLs) on Windows and other systems, as well as Windows Alternate Streams and Extended Metadata. SMB is suitable for managing and administering large or small pools of data.
TrueNAS uses Samba to provide SMB services. The SMB protocol has multiple versions. An SMB client typically negotiates the highest supported SMB protocol during SMB session negotiation. Industry-wide, SMB1 protocol (sometimes referred to as NT1) usage is deprecated for security reasons.
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.
However, most SMB clients support SMB 2 or 3 protocols, even when not default.
Legacy SMB clients rely on NetBIOS name resolution to discover SMB servers on a network. TrueNAS disables the NetBIOS Name Server (nmbd) by default. Enable it on the Network > Global Settings screen if you require this functionality.
MacOS clients use mDNS to discover SMB servers present on the network. TrueNAS enables the mDNS server (avahi) by default.
Windows clients use WS-Discovery to discover the presence of SMB servers, but you can disable network discovery by default depending on the Windows client version.
Discoverability through broadcast protocols is a convenience feature and is not required to access an SMB server.
Adding an SMB share to your system involves several steps to add the share and get it working.
Set up a dataset for the new share.
Create local user accounts. You can also use directory services like Active Directory or LDAP to provide additional user accounts.
Modify the dataset ACL. After adding or modifying local users, edit the dataset permissions.
Create the SMB share. You can create a basic SMB share, or for more specific share types or feature requirements, use the Advanced Options instructions before saving the share.
After adding the share, start the service and mount it to your other system.
Before creating the SMB share, create the dataset you want the share to use for data storage.
It is best practice to use a dataset instead of a full pool for SMB or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
We recommend creating a new dataset with the Share Type set to SMB for the new SMB share.
TrueNAS creates the ZFS dataset with these settings:
ACL Mode set to Restricted The ACL Type influences the ACL Mode setting. When ACL Type is set to Inherit, you cannot change the ACL Mode setting. When ACL Type is set to NFSv4, you can change the ACL Mode to Restricted.
Case Sensitivity set to Insensitive
TrueNAS also applies a default access control list to the dataset. This default ACL is restrictive and only grants access to the dataset owner and group. You can modify the ACL later according to your use case.
Use Credentials > Local Users to add new users to your TrueNAS.
By default, all new local users are members of a built-in SMB group called builtin_users.
You can use the group to grant access to all local users on the server or add more groups to fine-tune permissions to large numbers of users.You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without the smb flag.
After creating a dataset and accounts, you need to investigate your access requirements and adjust the dataset ACL to match. Many home users typically add a new ACL entry that grants FULL_CONTROL to the builtin_users group with the flags set to INHERIT.
You cannot access SMB shares with the root user. Always change SMB dataset ownership to the intended SMB user.
To create a basic Windows SMB share, go to Shares.
Click on Windows Shares (SMB) to select it and then click Add. The Add SMB configuration screen displays the Basic Options settings.
Enter the SMB share Path and Name.
The Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
The Name is the SMB share name, which forms part of the share pathname when SMB clients perform an SMB tree connect. Because of how the SMB protocol uses the name, it must be less than or equal to 80 characters. It cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. If you do not enter a name, the share name becomes the last component of the path. If you change the name, follow the naming conventions for:
(Optional) Select a preset from the Purpose dropdown list to apply and lock or unlock pre-determined Advanced Options settings for the share. To retain control over all the share Advanced Options settings, select No presets.
(Optional) Enter a Description to help explain the share purpose.
Select Enabled to allow sharing of this path when the SMB service is activated. Leave it cleared if you want to disable the share without deleting the configuration.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
Enable the SMB service when prompted.
For a basic SMB share, you do not need to use the Advanced Options settings, but if you set Purpose to No Presets, click Advanced Options to finish customizing the SMB share for your use case.
The following are possible use cases, but for all settings, see SMB Shares Screens.
To add ACL support to the share, select Enable ACL, and then see Managing SMB Shares for more on configuring permissions for the share and the file system.
If you want to allow guest access to the share, select Allow Guest Access.
To prohibit writes to the share, select Export Read-Only.
To restrict share visibility to users with read or write access to the share, select Access Based Share Enumeration. See the smb.conf manual page.
Use the Host Allow and Host Deny options to allow or deny specific host names and IP addresses.
AFP shares are deprecated and not available in SCALE. To customize your SMB share to work with a migrated AFP share or with your MacOS, use the Advanced Options settings provided for these use cases.
To connect to an SMB share, you must start the related system service. You can start the service from the Windows SMB Share header on the Sharing screen or in System Settings > Services.
From the Sharing screen, click on the Windows (SMB) Shares
to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.Each SMB share on the list also has a toggle to enable or disable the service for that share.
To make SMB share available on the network, go to System Settings > Services and click the toggle for SMB. Set Start Automatically if you want the service to activate when TrueNAS boots.
Configure the SMB service by clicking edit. Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.
The instructions in this section cover mounting the SMB share on a system with the following operating systems.
Verify that your Linux distribution has the required CIFS packages installed.
Have the information on the Windows drive letter, computer name, and share name ready before you start.
Have the user name and password for the user assigned to the pool or for the guest if the share has guest access ready before you begin.
Mounting on a FreeBSD system involves creating the mount point, then mounting the volume.
To access SMB share management options from the Sharing > Windows (SMB) Shares screen you need to access the Sharing >SMB screen that lists all SMB shares on the system. To access this, after going to Shares, click the Windows (SMB) Shares
launch icon.To manage an SMB share use the Sharing > SMB details screen. Click the for the share you want to manage.
Click on the dropdown list option for the operation you want to perform.
Click Edit to open the Edit SMB screen where you can change any setting for the share.
Click Edit Share ACL to open the Sharing > SMB > Share ACL screen where you can add or edit ACL entries.
Click Edit Filesystem ACL to open the Storage > Edit ACL screen. The dataset Share Type option determine the ACL type and therefore the ACL Editor screen that opens.
Click Delete to open a delete confirmation dialog where you delete the share and remove it from the system. Delete does not affect shared data.
You have two options that modify ACL permissions for SMB shares:
To modify SMB share ACL permissions that apply to the users and groups and permissions of the entire SMB share use Edit Share ACL.
To modify ACL permissions at the dataset level for the users and groups that own or have specific permissions to the shared dataset.
See both the Permissions article for more details on configuring ACLs and Edit ACL Screen article for more information on the ACL editor screens and setting options.
Also see Tuning the Dataset ACL for an example of modifying ACL permissions for an SMB share.
To configure an Access Control List (ACL) entry for an SMB share use the Edit Share ACL option. This opens the SMB> Share ACL screen. This screen is separate from file system permissions and applies at the entire SMB share level. Changes made to permissions on this screen for the selected SMB share do not apply to other file sharing protocol clients or other SMB shares that export the same share Path.
You cannot access SMB shares with the root user. Always change SMB dataset ownership to the intended SMB user.
This ACL determines the browse list if you enable Access Based Share Enumeration. See SMB Share Screens for more information on settings.
Open is the default.
From the main Sharing screen, click on either Windows (SMB) Share or View Details to open the Sharing > SMB details screen. Click the
icon for the SMB share you want to edit ACL permissions for and then click Edit Share ACL.Either select new values for the ACL entry or click Add to add a new block of Add share_ACL settings. Click Save when you finish your changes.
To configure an Access Control List (ACL) entry for the SMB share the path (defined in Path) at the dataset level, use the Edit Filesystem ACL option.
The ACL type setting on the Add Dataset or Edit Dataset configuration screen, in Advanced Options, determines the ACL editor screen or windows you see when you click Edit Filesystem ACL.
If you set the dataset ACL Type to POSIX, the Select a preset ACL window displays first. After you select a preset and click Continue a POSIX type ACL Editor screen displays.
If you set the dataset ACL Type to NFSv4, the NFSv4 type ACL Editor displays.
Since SCALE gives users the option to use either POSIX or NFSv4 share ACL types, the ACL Editor screen differs depending on which ACL type the file system uses.
Both the POSIX and NFSv4 ACL Editors allow you to define ACL user accounts or groups that own or have specific permissions to the shared dataset. The User and Group values show which accounts own or have full permissions to the dataset. Change the default settings to your preferred primary account and group and select Apply permissions recursively before saving any changes.
To define permissions for a specific user account or group for this SMB share at the dataset level, click Add Item. Select a User or Group from the Who dropdown list, then select a specific user or group account. Define how the settings apply to the account, then specify the permissions to apply. For example, to only allow the newuser user permission to view dataset contents but not make changes, set the ACL Type to Allow and Permissions to Read.
See both the Permissions for more details on configuring ACLs and Edit ACL Screen for information on the ACL editor screens and setting options.
To rewrite the current ACL with a standardized preset, click Use Preset and select an option:
When finished, click Save Access Control List to add this to the Access Control List.
If the file system uses a POSIX ACL, the first option presented is to select a preset.
To rewrite the current ACL with a standardized preset, click Use Preset and select an option:
SCALE uses predefined setting options to establish an SMB share that fits a predefined purpose, such as for a share enabled for a basic time machine share.
To set up a basic time machine share:
Create the user(s) that use this share. Go to Credentials > Local User and click Add.
Create a dataset for the share to use.
Create the share with Purpose set to Basic time machine share.
After creating the share, enable the SMB service.
When adding a share, first create the dataset you plan to use for the new share.
To create a dataset using the default settings, go to Datasets. Default settings include the settings datasets inherit from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown.
Select SMB for the Share Type or leave it set to Generic, then click Save.
You can create datasets optimized for SMB shares or with customized settings for your dataset use cases.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but it is not used for application data storage. If you want to store data by application, create the dataset first, then deploy your application. When creating a dataset for an application, select App as the Share Type setting. This optimizes the dataset for use by an application.
Review the Share Type and Case Sensitivity options on the configuration screen before clicking Save. You cannot change these or the Name setting after clicking Save.
Select this dataset as the mount path when you create your SMB share that uses the Basic time machine share setting.
Go to System Settings > Services and scroll down to SMB.
Click the toggle to turn off the SMB service if it is running, then click edit Configure to open the SMB Service settings screen..
Click Advanced Settings.
Verify or select Enable Apple SMB2/3 Protocol Extension to enable it, then click Save
Click the toggle to restart the SMB service.
Go to Shares and click Add on the Windows SMB Share widget to open the Add SMB Share screen.
Enter the SMB share Path and Name.
The Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
The Name is the SMB share name, which forms part of the full share pathname when SMB clients perform an SMB tree connect. Because of how the SMB protocol uses the name, it must be less than or equal to 80 characters. It cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. If you do not enter a name, the share name becomes the last component of the path. If you change the name, follow the naming conventions for:
Select a Basic time machine share from the Purpose dropdown list.
(Optional) Enter a Description to help explain the share purpose.
Select Enabled to allow sharing of this path when the SMB service is activated. Leave it cleared if you want to disable the share without deleting the configuration.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
You can also choose to enable the SMB service at this time.
Enable Shadow Copies exports ZFS snapshots as Shadow Copies for Microsoft Volume Shadow Copy Service (VSS) clients.
Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. You can use shadow copies to restore previous versions of files from within Windows Explorer.
By default, all ZFS snapshots for a dataset underlying an SMB share path are presented to SMB clients through the volume shadow copy service or are accessible directly with SMB when the hidden ZFS snapshot directory is within the SMB share path.
Before you activate Shadow Copies in TrueNAS, there are a few caveats:
Shadow Copies might not work if you haven’t updated the Windows system to the latest service pack. If previous versions of files to restore are not visible, use Windows Update to ensure the system is fully up-to-date.
Shadow Copies support only works for ZFS pools or datasets.
You must configure SMB share dataset or pool permissions appropriately.
To enable shadow copies, go to Shares > Windows (SMB) Shares and click Windows (SMB) Shares
launch icon to display the list view Sharing > SMB screen.Click the
for the share you want to change, and then click Edit. The Edit SMB screen displays.Scroll down to the bottom and click Advanced Options.
Scroll down to Other Options and select Enable Shadow Copies.
Click Save
Users with an SMB client cannot delete Shadow copies. Instead, the administrator uses the TrueNAS web interface to remove snapshots.
Disable shadow copies for an SMB share by clearing the Enable shadow copies checkbox on the Edit SMB screen for the SMB share.
Disabling does not prevent access to the hidden
TrueNAS offers the Use as Home Share option for organizations or SMEs that want to use a single SMB share to provide a personal directory to every user account. Each user is given a personal home directory when connecting to the share. These home directories are not accessible by other users. Only one share can be used as the home share, but other non-home shares can be created.
Creating an SMB home share requires configuring the system storage and joining Active Directory.
First, go to Storage and create a pool.
Next, set up the Active Directory that you want to share resources with over your network.
Go to Storage and open the more_vert next to the root dataset in the pool you just created, then click Add Dataset.
Name the dataset and set Share Type to SMB.
After creating the dataset, go to Storage and open more_vert next to the new dataset. Select View Permissions, then click edit.
Click the Group dropdown list and change the owning group to your Active Directory domain admins.
Click Use an ACL Preset and choose NFS4_HOME. Then, click Continue.
Go to Shares > Windows (SMB) Shares and click Add.
Set the Path to the prepared dataset.
The Name automatically becomes identical to the dataset. Leave this as the default. If you change the name follow the naming conventions for:
Set the Purpose to No presets, then click Advanced Options and set Use as Home Share. Click Save.
Enable the SMB service in System Settings > Services to make the share is available on your network.
Go to Credentials > Local Users and click Add. Create a new user name and password. By default, the user Home Directory title comes from the user account name and is added as a new subdirectory of Home_Share_Dataset.
If existing users require access to the home share, go to Credentials > Local Users and edit an existing account.
Adjust the user home directory to the appropriate dataset and give it a name to create their own directory.
After adding the user accounts and configuring permissions, users can log in to the share and see a folder matching their user name.
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.
There are normalize forms for a unicode character with diacritical marks: decomposed (NFD) and pre-composed (NFC).
Take for example the character ä (a + umlaut) and the encoding differences between NFC (b’\xc3\xa4’) and NFD (b’a\xcc\x88’).
The MacOS SMB client historically and at present forces normalization of unicode strings to NFC prior to generating network traffic to the remote SMB server.
The practical impact of this is that a file that contains NFD diacritics on a remote SMB server (TrueNAS, Windows, etc.) might be visible in the directory listing in the MacOS SMB client and thereby Finder, but any operations on the file (edits, deletions, etc.) have undefined behaviors since a file with NFC diacritics does not exist on the remote server.
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
>>> os.unlink('220118_M_HAN_MGK_X_4_Entwässerung.pdf')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
FileNotFoundError: [Errno 2] No such file or directory: '220118_M_HAN_MGK_X_4_Entwässerung.pdf'
>>> os.listdir(".")
['220118_M_HAN_MGK_X_4_Entwässerung.pdf']
Above is a short example of a MacOS SMB client attempting to delete a file with NFD normalization on remote Windows server.
Short of Apple providing a fix for this, the only strategy for an administrator to address these issues is to rename the files with pre-composed (NFC) form. Unfortunately, normalization is not guaranteed to be lossless.
For more information see Unicode Normalization Forms or Combining Diacritical Marks.
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.
If you already have clients connected to SMB shares, disconnect them before activating multichannel.
After you connect a client to their SMB share, open Powershell as an administrator on a client, then enter Get-SmbMultichannelConnection
. The terminal should list multiple server IPs.
You can also enter Get-SmbMultichannelConnection | ConvertTo-Json
and ensure CurrentChannels
is more than 1.
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, adding custom system controls, kernel-level settings, scheduled scripting or commands, 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 enter commands directly into the TrueNAS Operating System. Shell accepts Unix-like commands, and there is an experimental TrueNAS-specific command-line interface (CLI) for configuring the system separately from the web interface.
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. SCALE is currently a Prerelease Train. Prerelease Trains have various preview/early build releases of the software.
SCALE has several trains available for updates. However, the web interface only displays trains you can select as an upgrade. To view a list of the available trains, click on the arrow to the right of your current train.
For more information on other available trains, see TrueNAS Upgrades.
See the Software Status page for the latest recommendations for software usage. Bluefin and Nightlies are non-production trains. If you are using a non-production train, be prepared to experience bugs or problems. Testers are encouraged to submit bug reports and debug files at https://github.com/truenas/documentation/pull/1809/files#diff-ec4462e55ad21a92f5368a10510591a6ae7fe1ed297916798828c05f752ff25fR24.
The TrueNAS SCALE Update screen lets users update their system using two different methods: manual or automatic.
We recommend updating TrueNAS when the system is idle (no clients connected, no disk activity, etc). Most updates require a system reboot.
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.
Select the Check for Updates Daily and Download if Available option to automatically download updates.
If an update is available, click Apply Pending Update to install it.
To do a manual update, click Download Updates and wait for the file to download to your system.
Download the SCALE Manual Update File.
To manually update TrueNAS, click Install Manual Update File and save your configuration.
Select a temporary location to store the update file and click Choose File. Select the
After updating, you might find that you can update your storage pools and boot-pool to enable some supported and requested features that are not enabled on the pool.
Go to System Settings > Shell and enter zpool status
to show which pools you can update.
To update the pools, enter zpool upgrade poolname
, where poolname is the name of the storage pool or boot-pool you want to update.
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.
Upgrading from Bluefin to Cobia when applications are deployed is a one-way operation.
You cannot return to or roll back to an earlier SCALE release by simply activating an earlier release boot environment. You also cannot easily roll back app on-disk data after updating the structure to Cobia. After upgrading to Cobia, deployed apps do not work in the earlier release boot environment because the path to system dataset/ix-applications/docker does not exist in Cobia and is not restored when rolling back.
When apps are deployed in an earlier SCALE major version, you must take snapshots of all datasets that the deployed apps use, then create and run replication tasks to back up those snapshots. After rolling back to the earlier version from 23.10 (Cobia), these snapshots are used to restore the applications datasets to their pre-upgrade condition and allow previously installed apps to resume normal functionality.
At minimum, you need pre-upgrade snapshots of the ix-applications dataset and a recursive snapshot of ix-applications to get the docker dataset, and then snapshots of all datasets apps use as host paths. Without these snapshots, to downgrade to Bluefin requires deleting the app(s) and redeploying it/them.
It is recommended to use replication tasks to copy snapshots to a remote server used for backups of your data. If you do not have a remote server to store backup snapshots, you can create a new pool and dataset on the system for local replications, but this is not a recommended general backup strategy.
When you rollback the TrueNAS SCALE system from Cobia to an earlier SCALE major version, copy the snapshots from the remote backup server to the local system in a new temporary dataset. Create a new dataset on the same pool as the ix-applications dataset (the pool apps use).
Verify your Bluefin apps are running (not stopped or in the deploying state), and that you have access to your data and the application web portals.
Create and run replication tasks to a remote server. See Setting Up a Remote Replication Task for more information. Before upgrading to Cobia, create and replicate snapshots for:
If a Bluefin app uses host path(s) to existing datasets, such as with the MinIO and the /data dataset, create and run remote replication tasks for these datasets. If you nested these datasets for apps under a parent dataset, set up a recursive remote replication of the parent dataset to create the snapshots of all the nested child datasets the apps use.
Upgrade to Cobia and save the configuration file. This is always recommended so you can restore your system configuration if necessary.
Do not replicate remote backup snapshots into the ix-applications dataset! Create a dataset or use an existing dataset on the same pool as the ix-applications dataset to hold these snapshots.
Select the earlier release boot environment, make it the active boot environment, then reboot the system. See Managing Boot Environments for more information.
Go to the remote system and create and run a replication task to copy the snapshots back to the system you rolled back to an earlier SCALE release. Alternately, create a Pull replication task on the rolled-back system to bring the snapshots from the remote system to the local system.
Replicate each snapshot: the ix-applications, ix-applications/docker, and all snapshots of datasets set up as host paths in an application.
When moving a snapshot from a different pool on the same server, replicate to a dataset on the same pool as the ix-applications dataset (for example, tank/repsnaps if ix-applications is in the tank pool).
Go to the location of the snapshots, then:
a. Roll back to the ix-applications snapshot taken before the upgrade. This updates the migration JSON files to the pre-upgrade version of the files.
b. Locate the ix-applications/docker snapshot, click on it to expand it, then click Clone to Dataset. Rename the dataset to poolname/ix-applications/docker to create the missing docker dataset from this snapshot.
c. Roll back the snapshots for any dataset used as a host path in an application to the snapshots taken before the upgrade.
Go to Shell or open an SSH session and verify the docker dataset exists. Enter:
cd /mnt/poolname/ix-applicationsls
Where poolname is the name of the pool assigned as the pool for applications to use and with the ix-applications dataset.
The command output now show the docker dataset.
Reboot the system.
The applications now show on the Applications > Installed Applications screen. It takes a while for apps to return to the Active state.
TrueNAS Enterprise
This procedure only applies to SCALE Enterprise (HA) systems. If attempting to migrate from CORE to SCALE, see [Migrating from TrueNAS CORE]/gettingstarted/migrate/migratingfromcore/
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.
Sudo settings changed in 22.12.1. 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.If you plan to set up a cluster that includes this TrueNAS SCALE, wait to download your system configuration file until after the cluster is set up and working.
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 the selecting Save Password Secret Seed.
TrueNAS Enterprise
Enterprise High Availability (HA) systems should never reset their system configuration to defaults. Contact iXsystems Support when a system configuration reset is required.
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 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.
The TrueNAS SCALE General Settings section provides settings options for support, graphic user interface, localization, NTP servers, and system configuration.
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 > 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.
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.
Advanced Settings provides configuration options for the console, syslog, sysctl, replication, cron jobs, init/shutdown scripts, system dataset pool, isolated GPU device(s), and self-encrypting drives.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers 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, and setting the maximum number of simultaneous replication tasks the system can perform.
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.
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 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.
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
The Syslog widget on the System > Advanced screen allows users determine how and when the system sends log messages to the 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 logging level the syslog server uses when creating system logs from Syslog Level the dropdown list. The system only sends logs matching this level.
Select Use System Dataset to store system logs on the system dataset. Leave clear to store system logs in /var/
on the operating system device.
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.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers 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 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 Inti/Shutdown Script configuration screen populated with the settings for that script.
You can change from a command to a script, modify the script or command as needed.
To disable but not delete the command or script, clear the Enabled checkbox.
Click Save.
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.
The Isolate GPU PCI’s ID widget on the System > Advanced screen allows you to isolate a GPU installed in your system for use by a virtual machine (VM).
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers 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 displays an graphics processing unit (GPU) device(s) configured on your system.
Click Configure to open the Isolate GPU PCI’s ID screen where you can select a GPU to isolate it for GPU passthrough. GPU passthrough allows the TrueNAS SCALE kernel to directly present an internal PCI GPU to a virtual machine (VM).
The GPU device acts like the VM is driving it, and the VM detects the GPU as if it is physically connected. Select the GPU device ID from the dropdown list. To isolate a GPU you must have at least two in your system; one allocated to the host system for system functions and the other available to isolate for use by a VM or application. Isolating the GPU prevents apps and the system from accessing it.
Click Save.
TrueNAS supports a ZFS feature known as boot environments. These are snapshot clones that TrueNAS can boot into. Only one boot environment can be used for booting.
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.
The option to activate a boot environment only displays for boot entries not set to Active
Cloning copies the selected boot environment into a new entry.
You can change the name of any boot environment on the System Settings > Boot screen.
Deleting a boot environment removes it from the System Settings > Boot screen and from the boot menu.
Keep toggles with the Unkeep option, and they determine whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.
You can make a new boot environment to your TrueNAS.
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.
You an attach or replace the boot environment.
You can perform a manual data integrity check (scrub) of the operating system device at any time.
Sometimes, rolling back to an older boot environment can be useful. For example, if an update process does not go as planned, it is easy to roll back to a previous boot environment. TrueNAS automatically creates a boot environment when the system updates.
Use the Activate option on the more_vert for the desired boot environment.
This changes the Active column to Reboot for the boot environment, and means the boot environment becomes active on the next system boot. The system configuration also changes to the state it was in when the boot environment was created.
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.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
Dynamic Domain Name Service (DDNS) is useful when you connect TrueNAS to an Internet service provider (ISP) that periodically changes the system’s IP address. With Dynamic DNS, the system automatically associates its current IP address with a domain name and continues to provide access to TrueNAS even if the system IP address changes.
DDNS requires registration with a DDNS service such as DynDNS before configuring TrueNAS. Have the DDNS service settings available or open in another browser tab when configuring TrueNAS. Log in to the TrueNAS web interface and go to System Settings > Services > Dynamic DNS.
Select the provider from the dropdown list, or if not listed, select Custom Provider. If you select Custom Provider also enter the DynmicDNS server name in Custom Server and the path to the server obtained from that provider in Custom Path.
Select CheckIP Server SSL if you want to use HTTPS to connect to the CheckIP server, and then enter the name and port number of the server that reports the external IP addresses and the path to the CheckIP server.
Select SSL if you want to use HTTPS to connect o the server that updates the DNS record.
Enter the fully qualified domain name of the host with the dynamic IP address in Domain Name.
Enter the number of seconds for how often you want to check the IP address in Update Period.
Click Save.
Start the DDNS service after choosing your Provider options and saving the settings.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
This article provides instructions on how to move from using the deprecated dynamic DNS service to the new ddns-updater application.
The ddns-updater application is a lightweight universal dynanmic DNS (DDNS) updater with web UI. When installed, a container launches with root privileges in order to apply the correct permissions to the ddns-updater directories. Afterwards, the containter runs as a non-root user.
Before you configure the new ddns-updater application:
Disable the Dynamic DNS service. Go to System Settings > Services, disable the service, and clear the Start Automatically checkbox. This prevents the service from re-enabling after a system restart.
Review your Dynamic DNS service settings and note all provider, domain, IP address, port number, URL, and credential (username and password) settings.
If establishing a new provider, create the user account before proceeding. Otherwise, use the existing provider details.
If you want to grant access to a specific user (and group) other than using the defaults, add the new non-root administrative user and take note of the UID and GID for this user.
After disabling the dynamamic DNS service, install the ddns-updater application. Go to Apps, click on Available Applications, and locate the ddns-updater application widget.
Click Install to open the ddns-updater configuration wizard.
Select the timezone that applies to your server location from the Timezone dropdown list.
Click Add to the right of DNS Provider Configuration to display provider setting options. Select the DDNS provider from the Provider dropdown list. Each provider displays the settings required to establish a connection with and authenticate to that provider.
The SCALE service dynamic DNS list includes providers not on the ddns-Updater application list. If the service configuration uses a service not in the application, create a new account with a provider on the list in the ddns-updater application.
The update period default for the SCALE service is different from the application. Accept the default settings.
To use a notification service, enter the service in Shoutrrr Addresses. Shoutrrr addresses are a way to make sending notifications easy by standardizing them. Enter the shoutrrr gopher notification service(s) addresses and separate each entry with a comma.
Enter either the IPv4 or IPv6 HTTP public provider and then the public IP fetcher type you want to use to obtain the public IP address, or select All providers in each field.
Select Host Network to bind to the host network, but we recommend leaving this disabled.
Select the DDNS Updater Data Storage option from the Type dropdown list. Options are the iXVolume or host path.
Click Save.
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]](/scaletutorials/storage/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 NFS service when TrueNAS boots.
Unless a specific setting is required, we recommend using the default NFS settings.
Select the IP address from the Bind IP Addresses dropdown list if you want to use a specific static IP address, or to list on all available addresses leave this blank.
Enter an optimal number of threads used by the kernel NFS server in Number of threads.
If you are using NFSv4 select Enable NFSv4. NFSv3 ownership model for NFSv4 clears, allowing you to select 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:
Select Serve UDP NFS clients if NFS clients need to use UDP.
Select Allow non-root mount only if required by the NFS client to allow serving non-root mount requests.
Select Support > 16 groups when a user is a member of more than 16 groups. This 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.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
To configure VPN service, go to Apps > Available Applications to locate and install a VPN application.
A virtual private network (VPN) is an extension of a private network over public resources. It lets clients securely connect to a private network even when remotely using a public network. TrueNAS provides OpenVPN as a system-level service to provide VPN server or client functionality. TrueNAS can act as a primary VPN server that allows remote clients to access system data using a single TCP or UDP port. Alternatively, TrueNAS can integrate into a private network, even when the system is in a separate physical location or only has access to publicly visible networks.
Before configuring TrueNAS as either an OpenVPN server or client, you need an existing public key infrastructure (PKI) with Certificates and Certificate Authorities created in or imported to TrueNAS.
In general, configuring TrueNAS OpenVPN (server or client) includes selecting networking credentials, setting connection details, and choosing additional security or protocol options.
Go to System Settings > Services and find OpenVPN Client. Click the edit to configure the service.
Manage Certificates opens the Accounts > Certificates screen.
Choose the certificate to use as an OpenVPN client. The certificate must exist in TrueNAS and be active (unrevoked). Enter the Remote OpenVPN server’s hostname or IP address.
Continue to review and choose any other Connection Settings that fit your network environment and performance requirements. The Device Type must match the OpenVPN server Device Type. Nobind prevents using a fixed port for the client and is enabled by default so the OpenVPN client and server run concurrently.
Finally, review the Security Options and ensure they meet your network security requirements. If the OpenVPN server uses TLS Encryption, copy the static TLS encryption key and paste it into the TLS Crypt Auth field.
Go to System Settings > Services and find OpenVPN Server. Click the edit to configure the service.
Manage Certificates opens the Accounts > Certificates screen.
Choose a Server Certificate for the OpenVPN server. The certificate must exist in TrueNAS and be active (unrevoked).
Now define an IP address and netmask for the OpenVPN Server. Select the remaining Connection Settings that fit your network environment and performance requirements. If using a TUN Device Type, you can choose a virtual addressing topology for the server in Topology:
TrueNAS applies the Topology selection to any connected clients.
When TLS Crypt Auth Enabled is selected, TrueNAS generates a static key for the TLS Crypt Auth field after saving the options. To change this key, click Renew Static Key. Clients connecting to the server require the key. TrueNAS stores keys in the system database and includes them in client config files. We recommend always backing up keys in a secure location.
Finally, review the Security Options and choose settings that meet your network security requirements.
After configuring and saving your OpenVPN Server, generate client configuration files to import to any OpenVPN client systems connecting to this server. You need the certificate from the client system already imported into TrueNAS. To generate the configuration file, click Download Client Config and select the Client Certificate.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
This service is not needed when rsync is configured externally with SSH or with the TrueNAS built-in rsync task in SSH mode. It is always recommended to use rsync with SSH as a security best practice.
When necessary to enable an rsync server with modules, go to Apps > Available Applications and install the new rsyncd application.
Rsync is a utility that copies data across a network. The Services > Rsync screen has two tabs: Configure and Rsync Module. Use the Configure screen to add the TCP port number for the rsync service. Port 22 is reserved for TrueNAS.
Use the Rsync Module screen to configure an rsync module on a TrueNAS system. You must configure at least one rsync module for the service to function.
Go to Services and click the Configure icon for Rsync to open the Configure screen.
Enter a new port number if not the default in TCP Port. This is the port the rsync server listens on.
Enter any additional parameters from rsyncd.conf(5) you want to use in Auxiliary Parameters.
Click Save.
To configure an rsync module click Add or Add Rsync Modules on the Services > Rsync > Rsync Module screen.
Click either Add RSYNC Modules if a remote module does not exist, or Add to open the Add Rsync screen to configure a module to use as the mode.
Enter a name, and then either enter the path or use the
to the left of /mnt to browse to the pool or dataset to store received data. Click on the dataset or zvol name to populate the path field. To collapse the dataset tree, click the to the left of /mnt again.Select Enable to activate the module for use with the rsync service.
Select the permission access level in Access Mode.
Select the user and group that runs the rsync command during file transfer to and from this module.
Enter any allow and or deny hosts. Separate multiple entries by pressing Enter after each entry in Hosts Allow and/or Hosts Deny.
When a Hosts Allow list is defined, only the IPs and hostnames on the list are able to connect to the module.
Enter any additional rsync configuration parameters from rsyncd.conf(5) in Auxiliary Parameters.
Click Save.
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.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
Follow the migration and installation instructions in Migrating from S3 Service and Configuring MinIO Enterprise to move from the deprecated S3 service.
S3 allows you to connect to TrueNAS from a networked client system with the MinIO browser, s3cmd, or S3 browser.
Having large numbers of files (>100K for instance) in a single bucket with no sub-directories can harm performance and cause stability issues.
Go to the System Settings > Services and find S3, then click edit to open the Services > S3 screen to configure the service.
First, select a clean dataset, one that does not have existing data files. If you do not have a clean dataset, create a dataset. MinIO manages files as objects that you cannot mix with other dataset files.
Configure the remaining options as needed in your environment and start the service after saving any changes.
When Enable Browser is selected, test the MinIO browser access by opening a web browser and typing the TrueNAS IP address with the TCP port.
You must allow the port entered in the Services > S3 screen Port through the network firewall to permit creating buckets and uploading files.
Example: https://192.168.0.3:9000
.
MinIO supports two different connection methods.
Linux or macOS users must have the s3cmd service installed before beginning this setup. On Windows, users can also refer to S3Express for a similar command-line experience.
Ubuntu or other Linux distributions can access the configuration by runnings3cmd --configure
to walk through critical settings.
Enter the specified access key and the secret key.
Enter the TrueNAS IP address followed by TCP port under S3 Endpoint
, and reply N
to the DNS-style bucket+hostname.
Save the file.
On Linux, the default is in the home directory
If the connection has issues, open nano .s3cfg
or vi .s3cfg
or gedit .s3cfg
depending on the preferred text editor.
For other operating systems,
Scroll down to the host_bucket area and ensure the configuration removed the %(bucket)s.
portion and the address points to the IP_address:TCP_port for the system.
Correct Example
host_base = `192.168.123.207:9000`
host_bucket = `192.168.123.207:9000`
Incorrect Example
host_base = `192.168.123.207`
host_bucket = `%(bucket)s.192.168.123.207`
Poll the buckets using s3cmd ls
to see the buckets created with the MinIO browser.
For more information on using MinIO with s3cmd
, see https://docs.minio.io/docs/s3cmd-with-minio.html and https://s3tools.org/s3cmd.
The Windows PC S3 browser is another convenient way to connect to the MinIO S3 from TrueNAS.
To set it up, first install the S3 browser.
After installation completes, add a new account.
In the settings, select S3 Compatible Storage as the Account Type, then enter the MinIO access point similar to the s3cmd
setup (TrueNAS_IP_address:9000 or other port if set differently).
Select the SSL settings appropriate for the particular setup.
The S3 browser assumes SSL by default, but it can be unset for a LAN attached session.
It is possible to access, create new buckets, or upload files to created buckets.
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.
When using SMB1 clients, select Enable SMB1 support to allow legacy SMB1 clients to connect to the server.
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.
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.
Available Management Information Bases (MIBs) are located in ls /usr/local/share/snmp/mibs
.
Here is a sample of the directory contents:
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.
To allow SSH for the admin user, select Log in as Admin with Password if not already selected. To allow SSH for the root user, select Log in as Root with Password. Select Allow Password Authentication to allow password authentication for the SSH login.
Click Save. Select Start Automatically and enable the SSH service.
If your configuration requires more advanced settings, click Advanced Settings. The basic options display at the top of the Advanced Settings screen. Configure the options as needed to match your network environment.
We recommend you add these SSH service options in Auxiliary Parameters:
ClientAliveInterval
if SSH connections tend to drop.MaxStartups
value (10 is default) when you need more concurrent SSH connections.To configure ciphers to allow or disallow use ssh -Q cipher
to display a list then add them, separating each with a comma (,). Include the dash (-) before the cipher to exclude from the default set.
Remember to enable the SSH service in System Settings > Services after making changes. To create and store specific SSH connections and keypairs, go to Credentials > Backup Credentials.
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 and decide if you need Log in as Root with Password and Log in as Admin with Password.
Review the remaining options and configure them according to your environment or security needs.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.
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.
SCALE 22.12.3 deprecates several built-in features. SCALE 23.10 replaces deprecated features with applications that perform their roles. See SCALE Feature Deprecations for more details about feature deprecation and replacement.
To use TFTP, go to Apps > Available Applications and install the tftpd-hpa application.
The File Transfer Protocol (FTP) is a simple option for data transfers. The SSH and Trivial FTP options provide secure or simple config file transfer methods respectively.
Options for configuring FTP, SSH, and TFTP are in System Settings > Services. Click the edit to configure the related service.
The Trivial File Transfer Protocol (TFTP) is a lightweight version of FTP typically used to transfer configuration or boot files between machines, such as routers, in a local environment. TFTP provides a limited set of commands and provides no authentication.
If TrueNAS is only storing images and configuration files for network devices, configure and start the TFTP service. Starting the TFTP service opens UDP port 69.
Select the path to where you want to store files, and then select the file access permissions for both user and group. If you want to allow new file transfers select Allow new Files.
Add the host and port connection settings and select the user that can access TFTP services.
Enter any additional TFTP settings in the Auxiliary Parameters field.
Click Save and then start the service.
TrueNAS uses Network UPS Tools NUT to provide UPS support. After connecting the TrueNAS system UPS device, configure the UPS service by going to System settings > Services, finding UPS, and clicking edit.
See UPS Service Screen for details on the UPS service settings.
TrueNAS Enterprise
TrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
Some UPS models are unresponsive with the default polling frequency (default is two seconds).
TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.
If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10
.
upsc(8) can get status variables like the current charge and input voltage from the UPS daemon.
Run this in System Settings > Shell using the syntax upsc ups@localhost
.
The upsc(8) manual page has other usage examples.
upscmd(8) can send commands directly to the UPS, assuming the hardware supports it. Only users with administrative rights can use this command. You can create them in the Extra Users field.
SCALE 22.12.3 and continuing with SCALE 22.12.4 deprecates the built-in WebDAV sharing feature and no longer allows creating new WebDAV shares from these screens. All existing WebDAV shares remain saved and continue to be editable until the next major TrueNAS SCALE version (23.10) removes the Sharing > WebDAV and System Settings > Services > WebDAV screens from the TrueNAS web interface.
To create new or migrate existing WebDAV sharing configurations, see the webdav application tutorial
The Services > WebDAV configuration screen displays settings to customize the TrueNAS WebDAV service.
You can access it from System Settings > Services screen. Locate WebDAV and click edit to open the screen, or use the Config Service option on the WebDAV widget options menu found on the main Sharing screen.
Select Start Automatically to activate the service when TrueNAS boots.
If you require it, you must choose an SSL certificate (freenas_default is always available). All Protocol options require you to define a number in the Port field. Make sure the network is not already using the WebDAV service port.
Select the protocol option from the Protocol dropdown list. For better security, select HTTPS.
Enter a port number for unencrypted connections in HTTP Port. The default 8080 is not recommended. Do not reuse a port number.
Select the authentication method from the HTTP Authentication dropdown list. Select Basic Authentication for unencrypted or Digest Authentication for encrypted. No Authentication to not use any authentication method. To prevent unauthorized access to the shared data, set the HTTP Authentication to either Basic or Digest and create a new Webdav Password.
Enter and then confirm a password but do not use the know default davtest password.
Click Save.
Start the service.
The SCALE Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information. When Shell setting is TrueNAS CLI screen opens in the TrueNAS CLI.
If logged in as the root user, the Shell screen opens at the root prompt. To enter the TrueNAS CLI, enter cli
at the root prompt.
See SCALE CLI Reference Guide for more information on using the TrueNAS CLI.
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 uses in Shell.
Admin users can set the Shell to default to the TrueNAS CLI by selecting TrueNAS CLI in Shell on the Edit User screen. 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.
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.
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.
Because TrueNAS is both open source and complicated, the massive user community often creates tutorials for specific hardware or use cases. User-created tutorials in this section are provided “as-is” and are not officially supported by iXsystems, Inc.