Back to Docs Hub
To view or search through documentation for previous TrueNAS SCALE major versions, use the Version dropdown at the top of this page.
This section guides you through installing TrueNAS SCALE, or migrating from CORE to SCALE, and using the UI to access and configure TrueNAS SCALE. Configuration includes setting up initial storage, backup, and data sharing, and expanding TrueNAS with different application solutions.
The SCALE Evaluation Guide also provides video tutorials for installing and exploring the full potential of TrueNAS SCALE.
TrueNAS EnterpriseThis Table of Contents is a specific article arrangement that guides deploying TrueNAS Enterprise hardware purchased from iXsystems, inc.
24.10 Electric Eel
This page tracks the latest development roadmap and release notes for the next upcoming TrueNAS SCALE major version, 24.10 (Electric Eel). 24.04 (Dragonfish) release notes are available with that version’s documentation.
24.10 (Electric Eel) will bring many new features and improvements to the TrueNAS SCALE experience:
Expand a RaidZ pool with individual disks (OpenZFS feature sponsored by iXsystems) (NAS-123548).
Improve storage deduplication feature with better performance and consistency (OpenZFS feature sponsored by iXsystems) (NAS-127088).
New UI page with streamlined functionality for iX-Storj Cloud Backups (NAS-127165).
New advanced search for finding pages and settings in the SCALE UI (NAS-127224).
Dashboard reworked with more widgets, data reporting, and customization (NAS-127217).
Align Enclosure Management code with CORE and improve the feature’s performance (NAS-123474).
Preserve SMB alternate data streams when ingesting data from remote servers (NAS-127114).
Rewrite TrueNAS installer to better support future development efforts (NAS-127092).
Polish UI table presentation and integrate with global search (NAS-127222).
Replace nslcd with sssd to improve Kerberos, NFS, and SMB support in non-AD environments (NAS-127073).
Generate a unique system ID for each SCALE install (NAS-123519).
To see the latest on each feature in active development, click one of the NAS-###### development project links above.
Early releases of a major version are intended for testing and feedback purposes only.
For adventurous users that want to experiment with the latest feature development, nightly build .iso and .update files are available.
More details are available from Software Releases.
The release names and dates provided here are tentative and can change at any time.
SCALE™ | Enterprise™
TrueNAS SCALE is an appliance built from specific Linux packages.
Attempting to update SCALE with apt
or methods other than the SCALE web interface can result in a nonfunctional system.
All auxiliary parameters can change between TrueNAS major versions due to security and development changes. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
Click the component version number to see the latest release notes for that component.
Component | Version |
---|---|
Linux Kernel | 6.6.20 |
NVIDIA Driver | 545.23.08-2 |
OpenZFS | 2.2.99-2 |
TrueNAS integrates many features provided by the upstream OpenZFS project. Any new feature flags introduced since the previous OpenZFS version that was integrated into TrueNAS (OpenZFS 2.1.11) are listed below:
Feature Flag | GUID | Notes |
---|---|---|
raidz expansion | org.openzfs:raidz_expansion | |
redaction list spill | com.delphix:redaction_list_spill |
For more details on feature flags, see OpenZFS Feature Flags and OpenZFS zpool-feature.7.
This article tracks any TrueNAS SCALE features that are being deprecated in the latest nightly development versions. Items are added and possibly removed as SCALE development continues to evolve.
From repurposed systems to highly custom builds, the fundamental freedom of TrueNAS is the ability to run it on almost any x86 computer.
Processor | Memory | Boot Device | Storage |
---|---|---|---|
2-Core Intel 64-Bit or AMD x86_64 processor | 8 GB Memory | 16 GB SSD boot device | Two identically-sized devices for a single storage pool |
The TrueNAS installer recommends 8 GB of RAM. TrueNAS installs, runs, and operates jails. It also hosts SMB shares and replicates TBs of data with less. iXsystems recommends the above for better performance and fewer issues.
You do not need an SSD boot device, but we discourage using a spinner or a USB stick. We do not recommend installing TrueNAS on a single disk or striped pool unless you have a good reason to do so. You can install and run TrueNAS without any data devices, but we strongly discourage it.
TrueNAS does not require two cores, as most halfway-modern 64-bit CPUs likely already have at least two.
For help building a system according to your unique performance, storage, and networking requirements, keep reading.
The heart of any storage system is the symbiotic pairing of its file system and physical storage devices. The ZFS file system in TrueNAS provides the best available data protection of any file system at any cost and makes effective use of both spinning-disk and all-flash storage or a mix of the two. ZFS is prepared for the eventual failure of storage devices, and is highly configurable to achieve the perfect balance of redundancy and performance to meet any storage goal. A properly-configured TrueNAS system can tolerate multiple storage device failures and recreate its boot media with a copy of the configuration file.
TrueNAS can manage many storage devices as part of a single storage array. With more Enterprise-level tuning in the mature 13.0 release and similar tuning in the upcoming SCALE Cobia release, TrueNAS can manage as many as 1,250 drives in a single storage array!
Choosing storage media is the first step in designing the storage system to meet immediate objectives and prepare for future capacity expansion.
These storage device media arrange together to create powerful storage solutions.
TrueNAS SCALE does not officially support T10-DIF drives. Users on our forums have developed a workaround for using T10-DIF drives in TrueNAS SCALE, but using unsupported storage devices imposes data-loss risks.
Zpool layout (the organization of LUNs and volumes, in TrueNAS/ZFS parlance) is outside of the scope of this guide. The availability of double-digit terabyte drives raises a question TrueNAS users now have the luxury of asking: How many should I use to achieve my desired capacity? You can mirror two 16 TB drives to achieve 16 TB of available capacity, but that does not mean you should. Mirroring two large drives offers the advantage of redundancy and balancing reads between the two devices, which could lower power draw, but little else. The write performance of two large drives is similar to that of a single drive. By contrast, an array of eight 4 TB drives offers a wide range of configurations to optimize performance and redundancy at a lower cost. If configured as striped mirrors, eight drives could yield four times greater write performance with a similar total capacity. You might also consider adding a hot-spare drive with any zpool configuration, which lets the zpool automatically rebuild itself if one of its primary drives fails.
Spinning disk hard drives have moving parts that are highly sensitive to shock and vibration and wear out with use. Consider pre-flighting every storage device before putting it into production, especially:
smartctl -t long /dev/
), and after the test completes (could take 12+ hrs)smartctl -a /dev/
)smartctl -a /dev/ | grep Current_Pending_Sector
)smartctl -a /dev/ | grep Reallocated_Sector_Ct
)smartctl -a /dev/ | grep UDMA_CRC_Error_Count
)diskinfo -wS
) Unformatted drives only!smartctl -a /dev/ | grep Power_On_Hours
)nvmecontrol logpage -p 2 nvme0 | grep “Percentage used”
)Take time to create a pool before deploying the system.
Subject it to as close to a real-world workload as possible to reveal individual drive issues and help determine if an alternative pool layout is better suited to that workload.
Be cautious of used drives, as vendors might not be honest or informed about their age and health.
Verify vendors have not recertified all new drives by checking the hours using smartctl(8)
.
A drive vendor could also zero the hours of a drive during recertification, masking the drive age.
iXsystems tests all storage devices it sells for at least 48 hours before shipment.
The uncontested most popular storage controllers used with TrueNAS are the 6 and 12 Gbps (Gigabits per second, sometimes expressed as Gb/s) Broadcom (formerly Avago, formerly LSI) SAS host bus adapters (HBA).
Controllers ship embedded on some motherboards but are generally PCIe cards with four or more internal or external SATA/SAS ports.
The 6 Gbps LSI 9211 and rebranded siblings with the LSI SAS2008 chip, such as the IBM M1015 and Dell H200, are legendary among TrueNAS users who build systems using parts from the second-hand market.
Flash using the latest IT or Target Mode firmware to disable the optional RAID functionality found in the IR firmware on Broadcom controllers.
For those with the budget, newer models like the Broadcom 9300/9400 series give 12 Gbps SAS capabilities and even NVMe to SAS translation abilities with the 9400 series.
TrueNAS includes the sas2flash
, sas3flash
, and storcli
commands to flash or perform re-flashing operations on 9200, 9300, and 9400 series cards.
Onboard SATA controllers are popular with smaller builds, but motherboard vendors are better at catering to the needs of NAS users by including more than the traditional four SATA interfaces. Be aware that many motherboards ship with a mix of 3 Gbps and 6 Gbps onboard SATA interfaces and that choosing the wrong one could impact performance. If a motherboard includes hardware RAID functionality, do not use or configure it, but note that disabling it in the BIOS might remove some SATA functionality, depending on the motherboard. Most SATA compatibility-related issues are immediately apparent.
There are countless warnings against using hardware RAID cards with TrueNAS. ZFS and TrueNAS provide a built-in RAID that protects your data better than any hardware RAID card. You can use a hardware RAID card if it is all you have, but there are limitations. First and most importantly, do not use their RAID facility if your hardware RAID card supports HBA mode, also known as passthrough or JBOD mode (there is one caveat in the bullets below). When used, it allows it to perform indistinguishably from a standard HBA. If your RAID card does not have this mode, you can configure a RAID0 for every disk in your system. While not the ideal setup, it works in a pinch. If repurposing hardware RAID cards with TrueNAS, be aware that some hardware RAID cards:
A direct-attached system, where every disk connects to an interface on the controller card, is optimal but not always possible. A SAS expander (a port multiplier or splitter) enables each SAS port on a controller card to service many disks. You find SAS expanders only on the drive backplane of servers or JBODs with more than twelve drive bays. For example, a TrueNAS JBOD that eclipses 90 drives in only four rack units of space is not possible without SAS expanders. Imagine how many eight-port HBAs you need to access 90 drives without SAS expanders.
While SAS expanders, designed for SAS disks, can often support SATA disks via the SATA Tunneling Protocol or STP, we still prefer SAS disks for reasons mentioned in the NL-SAS section above (SATA disks function on a SAS-based backplane). Remember that you cannot use a SAS drive in a port designed for SATA drives.
A much-cited study floating around the Internet asserts that drive temperature has little impact on drive reliability. The study makes for a great headline or conversation starter, but carefully reading the report indicates that they tested the drives under optimal environmental conditions. The average temperature that a well-cooled spinning hard disk reaches in production is around 28 °C, and one study found that disks experience twice the number of failures for every 12 °C increase in temperature. Before adding drive cooling that often comes with added noise (especially on older systems), know that you risk throwing money away by running a server in a data center or closet without noticing that the internal cooling fans are at their lowest setting. Pay close attention to drive temperature in any chassis that supports 16 or more drives, especially if they are exotic, high-density designs. Every chassis has certain areas that are warmer for whatever reason. Watch for fan failures and the tendency for some models of 8 TB drives to run hotter than other drive capacities. In general, try to keep drive temperatures below the drive specification provided by the vendor.
TrueNAS has higher memory requirements than many Network Attached Storage solutions for good reason: it shares dynamic random-access memory (DRAM or simply RAM) between sharing services, add-on plugins, jails, and virtual machines, and sophisticated read caching. RAM rarely goes unused on a TrueNAS system, and enough RAM is vital to maintaining peak performance. You should have 8 GB of RAM for basic TrueNAS operations with up to eight drives. Other use cases each have distinct RAM requirements:
Electrical or magnetic interference inside a computer system can cause a spontaneous flip of a single bit of RAM to the opposite state, resulting in a memory error. Memory errors can cause security vulnerabilities, crashes, transcription errors, lost transactions, and corrupted or lost data. So RAM, the temporary data storage location, is one of the most vital areas for preventing data loss.
Error-correcting code or ECC RAM detects and corrects in-memory bit errors as they occur. If errors are severe enough to be uncorrectable, ECC memory causes the system to hang (become unresponsive) rather than continue with errored bits. For ZFS and TrueNAS, this behavior virtually eliminates any chances that RAM errors pass to the drives to cause corruption of the ZFS pools or file errors.
To summarize the lengthy, Internet-wide debate on whether to use error-correcting code (ECC) system memory with OpenZFS and TrueNAS:
Most users strongly recommend ECC RAM as another data integrity defense.
However:
Choosing ECC RAM limits your CPU and motherboard options, but that can be beneficial. Intel® limits ECC RAM support to workstation and server motherboards. The 13th generation of their consumer CPUs, such as the Core i5 and i7, support ECC as long as they are paired with a workstation motherboard chipset, such as the W680. Refer to Intel ARK for a full list of Intel CPUs with ECC support.
Which CPU to choose can come down to a short list of factors:
Watch for VT-d/AMD-Vi device virtualization support on the CPU and motherboard to pass PCIe devices to virtual machines. Be aware if a given CPU contains a GPU or requires an external one. Also note that many server motherboards include a BMC chip with a built-in GPU. See below for more details on BMCs.
AMD CPUs are becoming more popular thanks to the Ryzen and EPYC (Naples/Rome) lines. Support for these platforms is limited on FreeBSD and, by extension, TrueNAS CORE. However, Linux has more support, and TrueNAS SCALE should work with AMD CPUs without issue.
As a courtesy to further limit the motherboard choices, consider the Intelligent Platform Management Interface or IPMI (a.k.a. baseboard management controller, BMC, iLo, iDrac, and other names depending on the vendor) if you need:
TrueNAS relies on its web-based user interface (UI), but you might occasionally need console access to make network configuration changes. TrueNAS administration and sharing use a single network interface by default, which can be challenging when you upgrade features like LACP aggregated networking. The ideal solution is to have a dedicated subnet to access the TrueNAS web UI, but not all users have this luxury. The occasional visit to the hardware console is necessary for global configuration and system recovery. The latest TrueNAS Mini and R-Series systems ship with full-featured, HTML5-based IPMI support on a dedicated gigabit network interface.
The top criteria to consider for a power supply unit (or PSU) on a TrueNAS system are:
Select a PSU rated for the initial and a future load placed on it. Have a PSU with adequate power to migrate from a large-capacity chassis to a fully-populated chassis. Also, consider a hot-swappable redundant PSU to help guarantee uptime. Users on a budget can keep a cold spare PSU to limit their potential downtime to hours rather than days. A good, modern PSU is efficient and integrates into the IPMI management system to provide real-time fan, temperature, and load information.
Most power supplies carry a certified efficiency rating known as an 80 Plus rating. The 80 plus rating indicates the PSU loses the power drawn from the wall as heat, noise, and vibration instead of powering your components. If a power supply needs to draw 600 watts from the wall to provide 500 watts of power to your components, it operates at 500/600 = ~83% efficiency. The other 100 watts get lost as heat, noise, and vibration. Power supplies with higher ratings are more efficient but also far more expensive. Do some return-on-investment calculations if you are unsure what efficiency to buy. For example, if an 80 Plus Platinum PSU costs $50 more than the comparable 80 Plus Gold, it should save you at least $10 per year on your power bill for that investment to pay off over five years. You can read more about 80 Plus ratings in this post.
TrueNAS allows the system to communicate with a battery-backed, uninterruptible power supply (UPS) over a traditional serial or USB connection to coordinate a graceful shutdown in the case of power loss. TrueNAS works well with APC brand UPS, followed by CyberPower. Consider budgeting for a UPS with pure sine wave output. Some models of SSD can experience data corruption on power loss. If several SSDs experience simultaneous power loss, it could cause total pool failure, making a UPS a critical investment.
The network in Network Attached Storage is as important as storage, but the topic reduces to a few key points:
Higher-band hardware is becoming more accessible as the hardware development pace increases and enterprises upgrade more quickly. Home labs can now deploy and use 40 GB and higher networking components. Home users are now discovering the same issues and problems with these higher speeds found by Enterprise customers.
iXsystems recommends using optical fiber over direct attached copper (DAC) cables for the high-speed interconnects listed below:
iXsystems also recommends using optical fiber for any transceiver form factors mentioned when using fiber channels. Direct attached copper (DAC) cables can create interoperability issues between the NIC, cable, and switch.
Finally, the ultimate TrueNAS hardware question is whether to use actual hardware or choose a virtualization solution. At the heart of the TrueNAS design is OpenZFS. OpenZFS works best with physical storage devices. It is aware of their strengths and compensates for their weaknesses.
TrueNAS developers virtualize TrueNAS every day as part of their work, and it is intended only for use as a development environment.
While possible to deploy TrueNAS in a virtual environment, we do not recommend doing so for regular deployment of TrueNAS when storing production or critical data. Virtualizing TrueNAS and using virtual disks for your zpool is fine for ad hoc proof-of-concept, but it is not a supported configuration and might result in data corruption.
When the need arises to virtualize TrueNAS (for ad hoc proof-of-concept):
This section provides instructions for users that are installing TrueNAS SCALE the first time on their own system hardware and for users that need to do a clean install of SCALE.
TrueNAS Enterprise
The installation process covers installing SCALE using an
TrueNAS SCALE uses DHCP to provide the initial system IP address. After that, either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the SCALE UI to make network changes and complete the initial configuration.
Finally, it covers backing up your system configuration to a file and saving an initial system debug file.
SCALE users installing and configuring SCALE on their own servers should use the information in this article to prepare for their SCALE system deployments.
For SCALE support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.
If you are not the administrator responsible for network access in your company, contact your network administrator for assistance. If your company obtains network hardware and support from an Internet or cable service provider, contact them for assistance with where to obtain this information.
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration. An additional USB port is required when using a USB storage device to install TrueNAS from an .iso file.
Intelligent Platform Management Interface (IPMI) servers provide access to servers and allow remote users to install software and configure or administrate systems at the console level, or as though you are in the room with the server when you are working remotely.
To provide for remote administration of your TrueNAS SCALE system, assign access through an IPMI server to the TrueNAS server. To make this possible assign an IP address to use for access and set up administrator credentials (user name and password) to access the TrueNAS IPMI connections.
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
If you obtained network equipment and Internet service access from either an Internet or cable service provider, contact their support departments for assistance with network addresses.
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection. TrueNAS uses either SMTP to send mail from SCALE to administrator or designated individual email addresses for system alert notifications.
If you do not know this information and do not have a network administrator in your company, or if you are a home user, contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
This section does not apply to small companies with very few users or home deployments of SCALE.
TrueNAS SCALE works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap. Active Directory and LDAP configuration settings have similar requirements.
TrueNAS Enterprise
Because there are many possible scenarios for network configurations, this section covers the basics of the access and information required to configure SCALE to work in your network environment. If you are the individual tasked with installing and configuring the TrueNAS SCALE server but are not responsible for network services in your company, contact your network administrator to request they provision and verify new IP address assignments and provide the other information for access.
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration. An additional USB port is required when using a USB storage device to install TrueNAS from an .iso file.
The Intelligent Platform Management Interface (IPMI) provides a way for system administrators to remotely access their TrueNAS system. Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server. TrueNAS Enterprise systems sold by iXsystems provide IPMI network ports, but other hardware might not have IPMI ports.
iXsystems requires access through your IPMI server to access the TrueNAS server to provide remote administration support. To make this possible:
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
If you have an HA system with two controllers, you must assign a total of three IP addresses:
iXsystems Support can assist you with any questions you have with these network requirements. Provide the information listed to iXsystems when requested to expedite configuring your system network settings.
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection. TrueNAS uses either SMTP to send mail from SCALE to administrator or designated individual email addresses for system alert notifications.
Have your network administrators provide the SMTP addresses to allow TrueNAS to send emails from your network.
TrueNAS SCALE works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap. Active Directory and LDAP configuration settings have similar requirements.
SCALE users installing and configuring SCALE on their home server should follow the instructions in this article to prepare for their SCALE system deployment.
For SCALE support or assistance refer to the TrueNAS community forums, Discord, or the tutorials included in the TrueNAS Documentation Hub.
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration. An additional USB port is required when using a USB storage device to install TrueNAS from .iso file.
Intelligent Platform Management Interface (IPMI) servers provide a way for system administrators to remotely access and control systems. Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server. Home users with compatible hardware have the option to use an IPMI connection to remotely administer their system over the Internet.
To make this remote access possible you need an IPMI capable system or service:
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
Home users obtaining network equipment and Internet service access from either an Internet or cable service provider can contact the provider support departments for assistance with network addresses.
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection. TrueNAS uses either SMTP to send mail from SCALE to either the administrator or designated individual email addresses for system alert notifications.
Contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
After you download the .iso file, you can start installing TrueNAS SCALE!
This article describes verifying the .iso file and installing SCALE using that file, and selecting the type of installation as either on physical hardware or a virtual machine (VM).
TrueNAS EnterpriseSCALE Enterprise customers should receive their systems already installed and ready for UI configuration. If there are any issues with SCALE that requires you to install or re-install SCALE on your TrueNAS server, contact iXsystems Support for assistance.
Enterprise customers with High Availability (HA) systems should not attempt to re-install their systems on their own. The dual controller install process is complicated and the risk of causing serious network issues is high. Contact iXsystems Support for assistance!
The iXsystems Security Team cryptographically signs TrueNAS .iso files so that users can verify the integrity of their downloaded file. This section demonstrates how to verify an .iso file using the Pretty Good Privacy (PGP) and SHA256 methods.
You need an OpenPGP encryption application for this method of ISO verification.
SHA256 verification uses the checksum to validate/verify the file.
You can install SCALE on either physical hardware or a virtual machine.
Prior to starting the update process, confirm that the system storage has enough space to handle the update. The update stops if there is insufficient space to complete.
TrueNAS SCALE is very flexible and can run on any x86_64 compatible (Intel or AMD) processor. SCALE requires at least 8GB of RAM (more is better) and a 20GB Boot Device.
Physical hardware requires burning the TrueNAS SCALE installer to a device, typically a CD or removable USB device. This device is temporarily attached to the system to install TrueNAS SCALE to the system permanent boot device.
Before you begin:
With the installer added to a device (CD or USB), you can now install TrueNAS SCALE onto the desired system using the TrueNAS installer.
Insert the install media and reboot or boot the system. At the motherboard splash screen, use the hotkey defined by your motherboard manufacturer to boot into the motherboard UEFI/BIOS.
Choose to boot in UEFI mode or legacy CSM/BIOS mode. When installing TrueNAS, make the matching choice for the installation. For Intel chipsets manufactured in 2020 or later, UEFI is likely the only option.
If your system supports SecureBoot, and you have not disabled it or set it to Other OS, do it now, so you can boot the install media.
Select the install device as the boot drive, exit, and reboot the system. If the USB stick is not shown as a boot option, try a different USB slot. Slots available for boot differs by hardware.
If you are doing a clean install from the SCALE .iso file as part of migrating from a different version of TrueNAS CORE or SCALE, or to recover from a serious issue that requires you to re-install SCALE from the .iso, have your network configuration information ready to use after the installation completes. Also have your SCALE system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered SCALE clean-install system.
After the system boots into the installer, follow these steps.
Because TrueNAS SCALE is built and provided as an .iso file, it works on all virtual machine solutions (VMware, VirtualBox, Citrix Hypervisor, etc). This section describes installing on a VM using VMware Workstation Player on Windows.
Regardless of virtualization application, use these minimum settings:
When installing TrueNAS in a VMWare VM, double-check the virtual switch and VMWare port group. A misconfigured virtual switch or VMWare port group can cause network connection errors for TrueNAS systems with additional applications installed inside the TrueNAS VM. Enable MAC spoofing and promiscuous mode on the switch first, and then the port group the VM is using.
Jail Networking
If you have installed TrueNAS in VMware, you need functional networking to create a jail.
For the jail to have functional networking, you have to change the VMware settings to allow Promiscuous, MAC address changes, and Forged Transmits.
Setting | Description |
---|---|
Promiscuous Mode | When enabled at the virtual switch level, objects defined within all portgroups can receive all incoming traffic on the vSwitch. |
MAC Address Changes | When set to Accept, ESXi accepts requests to change the effective MAC address to a different address than the initial MAC address. |
Forged Transmits | When set to Accept, ESXi does not compare source and effective MAC addresses. |
The procedure for creating a TrueNAS VM is the same for most hypervisors.
This example describes installing TrueNAS SCALE using VMWare Player 15.5.
After installing SCALE on a virtual machine (VM), add virtual disks to the VM. You need a minimum of two disks, 16 GB each. One disk is for the boot environment the other for data storage.
Just as with installing SCALE on physical hardware, complete the installation in the VM by booting into the TrueNAS installer.
Congratulations, TrueNAS SCALE is now installed!
The next step is to configure SCALE network and general settings. Experienced users can use the Console Setup Menu to configure network settings, but if you are unfamiliar with the Console setup menu and how network configuration works, we recommend using the SCALE UI to configure settings. TrueNAS SCALE uses DHCP to assign an IP address to the primary system interface and displays it at the top of the Console Setup menu screen. Use this IP address to log into the web UI.
TrueNAS EnterpriseTrueNAS SCALE Enterprise is generally available with the release of SCALE 22.12.2. Do not attempt to install Enterprise High Availability systems with TrueNAS SCALE until it becomes generally available, unless the deployment is experimental in nature.
Installing TrueNAS SCALE on High Availability (HA) systems is complicated and should be guided by Enterprise-level support. Contact iXsystems Support for assistance whenever attempting to install TrueNAS SCALE on Enterprise HA hardware.
Do NOT use Linux or CLI commands to recover or clean-install the SCALE iso file or configure any initial configuration settings! Incorrect use of CLI commands can further disrupt your system access and can potentially do greater damage to your system. Proceed at your own risk.
This article outlines a procedure to do a clean install of a SCALE Enterprise High Availability (HA) systems using an
HA systems are dual controller systems with the primary controller referred to as controller 1 (sometimes also as controller A) and controller 2 (or controller B).
For best results, we recommend executing this procedure on both controllers at the same time. You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off. When controller 1 is completely configured, power on controller 2 to install TrueNAS and reboot the controller. When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
SCALE includes features and functions to help with completing the configuration process after installing and getting access to the SCALE web interface.
For a list of SCALE Enterprise (HA) preparation information, see Preparing for SCALE UI Configuration (Enterprise).
Have this information handy to complete this procedure:
HA system controllers each have serial numbers, the lower number assigned is for controller 1 (e.g. of two controller serial numbers assigned A1-12345 and A1-12346, the A1-12345 is for controller 1 and A1-12346 is for controller 2).
When restoring after a clean install, also have ready:
For best results, we recommend executing this procedure on both controllers at the same time. You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off. When controller 1 is completely configured, power on controller 2 to install TrueNAS and reboot the controller. When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
There are two ways to install the HA dual controller system to ensure controller 1 comes online as the primary controller:
Simultaneous installation must start with controller 1, so it comes online first. Installing each controller individually follows a particular method to ensure controller 1 comes online as the primary controller.
The sections in this article cover the primary steps as a simultaneous installation:
Download the
Log into your IPMI system using the network address assigned to controller 1, and then establish a second connection with controller 2 in a new browser session.
Install SCALE using the
Disable DHCP, then enter the network settings to controller 1 using the Console Setup Menu. Enter the IP address and netmask assigned to controller 1, then enter the global network settings for host name, domain name, and nameservers.
Use the SCALE UI for system configuration as it has safety mechanisms in place to prevent disrupting network access that could require you to repeat the clean install to access your system. However, if you are experienced with the Console Setup Menu and are using it to configure network settings you can configure the rest of the controller 1 network settings with the Console setup menu.
Log into the SCALE UI for controller 1 to sign the EULA agreement and apply the system HA license.
Disable failover to configure the rest of the network settings and edit the primary network interface on controller 1, and then enable failover.
Complete the minimum storage requirement by adding or importing one pool on controller 1.
Sign in using the Virtual IP (VIP) address.
With controller 2 powered up, on controller 1 sync to peer to complete the install and make controller 2 the standby controller.
The sections that follow describe these steps in detail.
This process of installing each controller sequentially has two methods:
This section provides an overview of the alternative method to clean install an HA system with controller 2 powered off while installing and configuring controller 1. These steps are nearly identical to the section above but controller 2 is either powered off or not installed while you install and configure controller 1.
Download the
If you are remote to the system and are installing through an IPMI connection you do not need to save the .iso file to a USB flash drive.
If you are physically present with the TrueNAS SCALE system, burn the
Use this process to install the
If you are doing a clean install from the SCALE.iso file to recover from an issue that requires you to re-install SCALE from the.iso , have your network configuration information ready to use for controller 1 after the installation completes. Do not configure network settings on controller 2. Also have your SCALE system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered SCALE clean-install system.
After installing the SCALE
To allow controller 1 to access the UI, you must disable DHCP and add the controller 1 static IP address and netmask as an alias on the primary network interface, and then enter the network settings for host name, domain name, default gateway, and the name servers (1 and 2). You can configure the rest of the HA global network settings in the SCALE web UI.
To use the Console setup menu to configure required network settings on controller 1:
Type 1 and then press Enter to open the Network Interfaces screen.
Use either Tab or the arrow keys to select the interface assigned as your primary network interface. If you have more than one interface installed and wired to your network, the primary interface is typically eno1. With the interface highlighted, press Enter to open the Update Network Interface screen.
Tab or arrow down to ipv4_dhcp and change it to no.
Tab or arrow down to the aliases setting and enter the static IP address for controller 1. Tab or arrow down to Save, and then press Enter. A pending network changes notice displays with additional options.
Type a to apply the change, then p to make it persist. Type q to return to the main Console setup menu.
Type 2 and then press Enter to open the Network Configuration screen.
Use either Tab or the arrow keys to select each field. Type the value for each field listed below. Press Enter after each value.
Field | Description/Example |
---|---|
hostname | The host name you assign to controller 1. For example m50-123-1. |
domain | The domain name for the nework controller 1. For example my.companyname.net |
ipv4gateway | The default gateway IP address for your network. |
nameserver1 nameserver2 | The IP addresses for your network DNS servers. |
Use either Tab or the arrow keys to select Save, then type q to return to the main Console setup menu.
This section only applies to controller 1. Do not configure settings on controller 2.
Use the SCALE UI to:
SCALE UI Enterprise customers see the End User License Agreement (EULA) screen the first time they log in. Sign the agreement to open the main SCALE Dashboard. Apply the system license next.
Go to System Settings > General and click Add License on the Support widget. Copy your license and paste it into the License field, then click Save License. The Reload dialog opens. Click Reload Now. Controller 1 restarts, and displays the EULA for controller 2. Sign the EULA agreement for controller 2, and add the license.
The controller 1 and 2 (or a and b) serial numbers display on the Support widget on the System Settings > General screen.
Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready to sync to peer, SCALE applies settings to controller 2 at that time.
SCALE Enterprise (HA) systems use three static IP addresses for access to the UI:
Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.
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.
To configure network settings on controller 1:
Disable the failover service. Go to System Settings > Services locate the Failover service and click edit. Select Disable Failover and click Save.
Edit the global network settings to add any missing network settings or make any changes.
Edit the primary network interface to add failover settings. Go to Network and click on the primary interface eno1 to open the Edit Interface screen for this interface.
a. Turn DHCP off if it is on. 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.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
Click Save
Click Test Changes after editing the interface settings. You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Create or import a storage pool from a backup. You must have at least one storage pool on controller 1. After saving the storage pool, controller 2 automatically restarts. Wait until it comes back online before syncing controller 1 with controller 2.
For more information on how to create a new pool click here. For more information on how to import a pool click here.
Turn the failover service back on. Go to System Settings > Services locate the Failover service and click edit.
Select Disable Failover to clear the checkmark and turn failover back on, then click Save. The system might reboot. Use IPMI to monitor the status of controller 2 and wait until the controller is back up and running.
Log out of the controller 1 UI, and log in using the VIP address.
Sync controller 1 and 2. With controller 2 powered on, but not configured, from controller 1 click Sync To Peer. Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation. This sync controller 2 with controller 1 which adds the network settings and pool to controller 2.
When the system comes back up, log into SCALE using the virtual IP address. The main Dashboard displays two System Information widgets. In standard configurations by iXsystems, Controller 1 shows its serial number and a host name that includes the letter a. Controller 2 is labeled as Standby Controller and shows its serial number and a host name that includes the letter b. Take note of this information.
If controller 2 comes online as the primary and controller 1 as the standby, you installed and configured the controllers incorrectly.
Go to System Settings > Failover, clear the Default TrueNAS Controller option, and click Save. The system reboots and fails over to the current standby controller (in this case, to controller 1).
Log back into the UI with the VIP address. Go to System Settings > Failover and select Default TrueNAS Controller to make controller 1 the primary controller.
Select Sync to Peer. SCALE makes controller 2 the standby controller and syncs the configuration on controller 1 to controller
Click Save.
The Console Setup menu displays at the end of the
By default, TrueNAS does not display the Console Setup menu with SSH or web shell connections. The admin user, the root user (if enabled), or another user with administrator or root-level permissions can start the Console Setup menu by entering this command:
/usr/bin/cli --menu
The menu provides several options:
For network configuration options 1, 2, and 3, we recommend using the SCALE UI to configure network interfaces, as it has safeguards to prevent breaking network access to SCALE.
1) Configure network interfaces
Use this to configure the primary network interface with a static IP. This is for switching away from the DHCP-assigned IP address TrueNAS provides when the system boots after installing SCALE. Also, use this to set up other network interfaces or to add alias IP addresses for the primary interface.
2) Configure network settings
Use this to set up the network default gateway, host name, domain, IPv4 gateway and DNS name servers. Configured options display in the Global Configuration widget in the web UI Network screen.
3) Configure static routes
Use this to set up static IP routes, but this is not required as part of the initial configuration setup.
4) Change local administrator password
Use to change the administrator user password. If you selected option 1 on the iso installer menu, you have already configured the admin user and password. You can use this to change the admin password before you log into the SCALE UI.
This is not the password for the root user in the CLI or the root user login password for the web UI. The root user password is disabled by default as part of security hardening. Activating the root user is not recommended.
5) Reset configuration to defaults
Use to wipe all system configuration settings and return the system to a fresh install state.
6) Open TrueNAS CLI Shell
Use to start a shell for running TrueNAS commands, or use the SCALE UI System Settings > Shell.
Type exit
to leave the shell.
7) Open Linux Shell
Use to start a shell window for running Linux CLI commands.
Configuration changes made here are not written to the database and are reset on each system boot.
We do not recommend using the Linux shell unless you are an advanced user. Type exit
to leave the shell.
8) Reboot
Use to restart the system by powering down and then automatically powering on the system.
9) Shut down
Use to power down the system.
During the first boot, TrueNAS attempts to connect to a DHCP server from all live interfaces. If it receives an IP address, the Console Setup menu displays it under The web user interface is at: so you can access the SCALE web UI.
You might be able to access the web UI using a hostname.domain
command at the prompt (default is truenas.local
) if your system:
You can either use SCALE UI or the Console Setup menu to configure your network settings for the primary network interface or other interfaces such as a link aggregate (LAGG) or virtual LAN (VLAN), or aliases for an interface, and to configure other network settings such as the default gateway, host name, domain, and the DNS name servers, or add static routes.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the SCALE UI to configure your network interfaces and other network configuration settings. The TrueNAS SCALE UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS SCALE if you make a mistake with network interface settings.
Enter 1 to display the Configure Network Interfaces screen and select the interface settings.
Follow the instructions on the screen to configure an IP for a network interface. Type n to open the new interface screen or press Enter to edit the existing interface.
You can enter aliases for an interface when you create a new one or edit an existing interface.
Type q to return to the main Console Setup menu screen.
Enter 2 to display the Network Settings screen to set up the host name, domain, default gateway and name servers. You can also add these settings using the web UI.
Enter 3 to display the Static Route Settings screen to set up static routes. You can also add static routes in the web UI.
TrueNAS uses DHCP to assign the IP address required to access the SCALE UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by SCALE, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure SCALE.TrueNAS EnterpriseFor Enterprise systems, have your network information ready to provide iXsystems Support when they guide you through your configuration.
To use the Console Setup menu to change the network interface IP address:
To configure the default gateway, host name, domain and DNS name severs using the Console Setup menu type 2 and then press Enter to open the Network Settings screen.
To configure network settings in the SCALE UI, enter the IP address displayed on the Console Setup menu screen in a browser URL field and press Enter.
Log in with the admin user name and password set for the administration user during the
Home users have a few options to allow Internet access using TrueNAS SCALE:
SCALE has implemented administrator account logins as replacements for the root user. The Local Administrator user account is the default account, and the root password is now disabled by default. If you migrate from CORE to SCALE and need to upload the CORE system configuration file, the root user password is not disabled but you must recreate the admin user account and disable the root password.
You can change the admin user password in the UI or from the Console Setup menu. You can set and enable the root user password in the UI, but for security hardening, we recommend leaving it disabled.
Changing the admin user (or root if you have not created the admin user) password disables 2FA (Two-Factor Authentication).
Disabling a password in the UI prevents the user from logging in with it. If both the root and local admin user passwords are disabled and the web interface session times out with these passwords disabled, SCALE provides a temporary sign-in screen to allow logging into the UI. Immediately go to the Credentials > Local User screen, select the admin user, click Edit and re-enable the password.
Caution! Resetting the configuration deletes all settings and reverts TrueNAS to default settings. Before resetting the system, back up all data and encryption keys/passphrases! After the system resets and reboots, you can go to Storage and click Import Pool to re-import pools.
Enter 5 in the Console Setup menu, then enter y to reset the system configuration. The system reboots and reverts to default settings.
After setting up network requirements, log into the web UI to complete your system setup by:
This section provides information and instructions for TrueNAS CORE users wanting to migrate to SCALE.
Migrating TrueNAS from CORE to SCALE is a one-way operation. Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-U6.1 (or later) release before attempting to migrate from CORE to SCALE.
Linux treats device names differently than FreeBSD so please read Component Naming for more information.
After migration, review each area of the UI that was previously configured in CORE.
Migrating TrueNAS from CORE to SCALE is a one-way operation. Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-U6.1 (or later) release before attempting to migrate from CORE to SCALE.
Although TrueNAS attempts to keep most of your CORE configuration data when upgrading to SCALE, some CORE-specific items do not transfer. These are the items that don’t migrate from CORE:
netcli
utility. A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI.
By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.0
-9
).VM storage and its basic configuration transfer over during a migration, but you need to double-check the VM configuration and the network interface settings specifically before starting the VM.
Init/shutdown scripts transfer, but can break. Review them before use.
Read this article before you attempt to migrate your CORE system to a SCALE major version.
We strongly recommend not using USB flash drives or USB-attached drives for backups as these can have issues, including with recovering backed up files. For more information on using USB drives and devices in general, read the CORE Hardware Guide. If you must use a USB type device, verify you can access files on the device before you upgrade/migrate to SCALE.
TrueNAS EnterpriseCORE Enterprise customers are encouraged to contact Support for assistance with the process of moving from CORE to SCALE, especially customers with HA systems.
Upgrade your CORE system to the most recent publicly-available CORE major maintenace release version. TrueNAS systems on 12.0x or earlier should upgrade to the latest CORE 13.0 release (e.g 13.0-U6.1 or newer) prior to migrating to SCALE. CORE systems at the latest 13.0 release can use the iso upgrade method to migrate to SCALE.
Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from CORE 12.0x or earlier releases!
Verify the root user is not locked. Go to Accounts > Users, select the root user and click Edit to view current settings and confirm Lock User is not selected.
Write down, copy, or take screenshots of settings to use in the event of a post-upgrade/migration issue or to duplicate in SCALE. Use the checklist below to guide you through this step:
System dataset - Identify your system dataset. If you want to use the same dataset for the system dataset in SCALE, note the pool and system dataset. When you set up the first required pool on SCALE import this pool first.
Deprecated services - Record the settings for services deprecated in SCALE.
VMs - If you have virtual machines configured in CORE, write down or screenshot network and other setting information.
Plugins or jails - Plugins and jails do not migrate. Record settings for each plugin/jail and back up the data associated with each.
CAs, certificates, CSRs - If you added certificate authorities, certificates, or certificate signing requests to CORE, they should migrate with the system config file, but as a precaution against possible malformed certificates copy private and public certificate keys and save each, then copy or screenshot all CA, certificate, and CSR setting. Make sure you have backed-up copies of certificates used in CORE to import or configure in SCALE.
Usernames beginning with (0-9) - Review local user account names and rename or replace these with a letter or underscore before migrating.
Tunables on CORE - SCALE does not use Tunables the way CORE does. SCALE allows adding script configurations on the System Settings > Advanced screen, using the Sysctl widget.
Init/shutdown scripts - If using init/shutdown scripts in CORE, copy them or take a screenshot to add them to SCALE.
Cron jobs - If configured in CORE, copy or use screenshots of cron job scripts if you want to add the same jobs in SCALE.
Global self-encrypting drive (SED) Password - Unlock these drives in CORE before you clean install SCALE. Write down the SED password configured in CORE to use in SCALE.
Credentials - Copy or write down the credentials for SSH connections and keypairs, and any cloud service backup providers configured in CORE if you do not have the credential settings saved in other files kept secured outside of CORE.
Data protection tasks - Write down or take screenshots of replication, periodic snapshot, cloud sync, or other task settings to reconfigure these in SCALE if you want to duplicate these tasks.
Write down or take screenshots of your network configuration information. Capture the global network settings, interfaces (LAGG, VLAN, bridge settings), static IP addresses, and aliases.
FreeBSD and Linux use different nomenclature for network interfaces, bridges, LAGGs, and VLANs. Because of the difference, network settings can either get lost or not transfer which means you have no network connectivity. You can find interface names in the CORE UI on the Network > Interfaces screen.
When using a TrueNAS Enterprise system from iXsystems, refer to the network port ID manuals of your TrueNAS Systems to find the network port assignments in TrueNAS SCALE. When using custom hardware for TrueNAS, refer to the manual or documentation provided with your system or locate this information on your server hardware and take note of it.
If there are issues after a clean install of SCALE from an
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address, or you can assign a static IP address. You must assign an IP address to each network interface card (NIC) installed in your system if you want to communicate over your network using the interfaces.
To configure your TrueNAS server to work with your network, you need:
Migrate the deprecated S3 MinIO service (if in use). See services deprecated in SCALE. This is a lenthy process depending on the amount of data stored while using the S3 service. Read and follow instructions in Migrating from MinIO S3! Make sure S3 MinIO data is backed up as a precaution. The migrating from the S3 service requires installing SCALE 22.12.3 (Bluefin). This version of SCALE provides access to both the S3 service and the MinIO app you migrate to.
If you need to do a clean install with the SCALE
Back up any critical data.
Download your system configuration file and a debug file.
After updating to the latest publicly-available release of CORE and making any changes to CORE user accounts or any other settings download these files and keep them in a safe place and where you can access them if you need to revert to CORE with a clean install using the CORE
After completing the steps that apply to your CORE system listed above, download the SCALE ISO file and save it to your computer. Burn the iso to a USB drive (see Installing on Physical Hardware in Installing SCALE) when upgrading a physical system.
The built-in services listed in this section are available in CORE, but deprecated in SCALE 22.12.3 (Bluefin) and removed in later SCALE releases. They require attention before attempting to migrate to SCALE.
Each of the sections has information that can help you determine the best steps forward to secure any critical data before attempting to migrate from CORE to SCALE. They provide details on transitioning from that service to an application with the functionality of the deprecated service.
TrueNAS SCALE has apps you can deploy as replacements for these services. SCALE 24.04 provides the option to force an upgrade without converting deprecated services to apps. The force option is not recommended for the S3 service as forcing the upgrade results in losing access to and the ability to recover the MinIO S3 data. If migrating the S3 service in Bluefin, you can also transition the other deprecated services to the applications that replace them before you upgrade to the latest major release of SCALE.
See SCALE Bluefin Deprecated Services for more information.
This article provides information and instructions for migrating non-Enterprise TrueNAS CORE to SCALE.
TrueNAS EnterpriseTrueNAS Enterprise customers should consult with iXsystems Support before attempting migrate to TrueNAS SCALE.
The process requires an extended maintenance window, requires executing steps in the correct order to prevent issues with system configuration and operation, and additional system review post-migration to catch and correct any configuration issues.
Review the Migration Preparation article for detailed recommendations and preparation steps before attempting to migrate from CORE to SCALE.
Depending on system configuration, migrating from CORE to SCALE can be more or less complicated.
Root is the default system administration account for CORE, SCALE Angelfish, and early Bluefin releases.
Users migrating from CORE to SCALE or from pre 22.12.3 releases must manually create an admin user account. Only fresh installations using an
iso file provide the option to create the admin user during the installation process.SCALE systems with only the root user account can log in to the TrueNAS web interface as the root user. After logging in as root, TrueNAS alerts you to create the local administrator account.
System administrators should create and begin using the admin login, and then disable the root user password.
SCALE 24.04 (Dragonfish) introduces administrators privileges and role-based administrator accounts. The root or local administrator user can create new administrators with limited privileges based on their needs. Predefined administrator roles are read only, share admin, and the default full access 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.
Migrating TrueNAS from CORE to SCALE is a one-way operation. Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-U6.1 (or later) release before attempting to migrate from CORE to SCALE.
You can migrate from CORE to SCALE with a clean install using an
When TrueNAS SCALE boots, you might need to use the Shell to configure networking interfaces to enable GUI accessibility. After logging in to the TrueNAS SCALE UI, use a system configuration file to restore the system settings to the SCALE installation and import the data storage pools.
Some CORE 13.0 releases can migrate using the CORE UI Upgrade function using a SCALE update file downloaded from the website. To use this method, you must upgrade to the latest maintenance release.
Earlier releases of CORE must upgrade to 13.0 and then the latest maintenance release U6.1 to use this method. If this process fails, retry using the iso file method above.
Confirm that the TrueNAS CORE system is on the latest public release, 13.0-U6.1 or newer.
Download the SCALE manual update file.
Click CHECK FOR UPDATES in the System Information card on the Dashboard or go to System > Update.
Click INSTALL MANUAL UPDATE FILE.
Click SAVE CONFIGURATION to download a backup file that can restore the system configuration in the event something goes wrong with the migration.
Select a Temporary Storage Location (either Memory Device or a Pool) for the manual update file.
Click Choose File and select the
Then click APPLY UPDATE.
After the update completes, reboot the system if it does not reboot automatically.
After TrueNAS SCALE reboots, sign in with the root user credentials used in CORE. Uploading the CORE config file deletes the admin user account created during a clean install and therefore requires you to recreate it.
After gaining access to the UI, you might need to use the Shell to configure the primary networking interfaces to enable GUI accessibility.
After booting and gaining access to the UI, go to System Settings > General and upload the system config file. This migrates your CORE settings, imports your pools, shares, etc. into SCALE.
After uploading the config file, review each area of the UI previously configured in CORE to validate pools imported and settings migrated correctly. Begin with your network settings.
Use the information gathered during your preparation to migrate to restore settings, tasks, VMs, credentials, etc. not present in SCALE after uploading the config file.
All CORE systems migrating to SCALE, and all Angelfish and early Bluefin releases of SCALE upgrading to 22.12.3+ or to later SCALE major versions should create and begin using an admin user instead of the root user. After migrating or upgrading from CORE or a pre-SCALE 22.12.3 release to a later SCALE release, use this procedure to create the Local Administrator user.
Go to Credentials > Local Users and click Add.
Enter the name to use for the administrator account. For example, admin. You can create multiple admin users with any name and assign each different administration privileges.
Enter and confirm the admin user password.
Select builtin_administrators on the Auxiliary Group dropdown list.
Add the home directory for the new admin user. Enter or browse to select the location where SCALE creates the home directory. For example, /mnt/tank. If you created a dataset to use for home directories, select that dataset. Select the Read, Write, and Execute permissions for User, Group and Other this user should have, then select Create Home Directory.
Select the shell for this admin user from the Shell dropdown list. To have System Settings > Shell open in the Console Setup Menu, select TrueNAS Console. This gives the administrator access to the TrueNAS and Linux CLI prompts.
Select the sudo authorization permissions for this admin user. Some applications, such as Nextcloud, require sudo permissions for the administrator account. For administrator accounts generated during the initial installation process, TrueNAS SCALE sets authorization to Allow all sudo commands.
Click Save. The system adds the user to the builtin-users group after clicking Save.
Log out of the TrueNAS system and then log back in using the admin user credentials to verify that the admin user credentials work properly with your network configuration.
After adding the admin user account, disable the root user password:
Go to Credentials > Local Users, click on the root user and select Edit. Click the Disable Password toggle to disable the password, then click Save.
TrueNAS Enterprise customers should consult with iXsystems Support before attempting migrate to TrueNAS SCALE.
The process requires:
Review the Migration Preparation article to see detailed notes and caveats about the migration process.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Contact Method | Contact Options |
---|---|
Web | https://support.ixsystems.com |
support@ixsystems.com | |
Telephone | Monday - Friday, 6:00AM to 6:00PM Pacific Standard Time: US-only toll-free: 1-855-473-7449 option 2 Local and international: 1-408-943-4100 option 2 |
Telephone | After Hours (24x7 Gold Level Support only): US-only toll-free: 1-855-499-5131 International: 1-408-878-3140 (international calling rates apply) |
TrueNAS SCALE incorporates all the major TrueNAS CORE storage and sharing features with a web interface based on Debian GNU/Linux. Because SCALE shares the same UI as the FreeBSD-based TrueNAS CORE, users might notice there are similarities. However, SCALE does incorporate some differences, primarily in component naming.
TrueNAS Core utilizes a numerical listing of drives in a system.
TrueNAS SCALE uses a lettered format for drive identification.
SCALE still labels NVMe drives with a numeric value.
TrueNAS CORE enumerates interface names using interface drivers, such as igb for Intel devices, followed by a number. TrueNAS CORE Enterprise systems use ix followed by a number.
TrueNAS SCALE enumerates interface names using PCI locations. By default, SCALE systems identify their network ports with eno or enp followed by a number.
TrueNAS CORE identifies bonded interfaces or link aggregations with lagg followed by a number (lagg1). TrueNAS SCALE uses bond followed by a number (bond1).
See the TrueNAS Systems section for lists of the default port names for each platform.
Early testers of TrueNAS SCALE are advised:
On June 29, 2021, a new feature was merged into the TrueNAS fork of OpenZFS[1]
for developers to test and integrate with other parts of the system. This feature included a new pool feature flag to signify an on-disk format change to how xattr names are encoded on Linux. This original version of the feature was easily activated by a default pool configuration. We quickly decided that the default configuration should not activate this feature until it is available in upstream OpenZFS, and on July 15 we merged changes[2]
which make the defaults prevent activation of the new feature.
[1]
: https://github.com/truenas/zfs/pull/8[2]
: https://github.com/truenas/zfs/pull/16
The new feature fixes a long-standing issue in ZFS on Linux, which had from its start encoded xattr names in a way that is incompatible with ZFS implementations for every other platform. As one of the planned features of TrueNAS SCALE is the easy migration of pools from TrueNAS CORE, we have been developing this and other missing features to improve feature parity and compatibility across all platforms in OpenZFS. A pull request[3]
for the xattr compatibility feature was opened with a request for comments in OpenZFS on April 20, 2021.
[3]
: https://github.com/openzfs/zfs/pull/11919
On October 6, 2021, we received feedback that the feature flag will not be needed, as a bump to the ZFS POSIX Layer version number should be sufficient. As a result, we have removed the feature flag in question from TrueNAS SCALE to prevent the feature from being enabled moving forward in the release cycle. This is an unfortunate time to receive this insight, as nightly and now beta users of SCALE will have pools created or upgrade with this flag. The impact for most users is negligible, as the pool is still fully operational with the feature flag enabled, as long as it is not active. These users will merely see the unsupported feature is present but inactive:
Users who created or upgraded a pool using a TrueNAS SCALE build from between June 29 and July 15 2021 or who have manually set xattr_compat=all
on a dataset and written an xattr will have activated the feature. Once activated, the feature cannot be deactivated until all datasets (including snapshots) that have ever utilized the feature (writing an xattr with xattr_compat=all
on Linux) have been destroyed. This can be hard to determine, as there is currently no way of checking the feature activation status of a dataset. Most people who did unwittingly activate the feature will merely see the new default value of xattr_compat=linux
when checking the property.
The feature was marked as read-only compatible, so pools with the feature active are able to be imported read-only on versions of ZFS that do not support the feature. Users are advised to check if their pool has the feature active, and if so, the pool must be backed up and recreated on a version of ZFS without the feature. Builds of SCALE as of October 9, 2021 have the feature removed.
This pool has feature@xattr_compat
enabled but not active, and can continue to be used on newer versions of TrueNAS SCALE and other ZFS systems:
Changing the xattr_compat
property and writing an xattr in the user namespace activates the feature, preventing the pool from being used on TrueNAS SCALE and other ZFS systems moving forward. The feature is only activated by writing an xattr in the user namespace with xattr_compat=all
on Linux. Once activated, it stays active even if xattr_compat=linux
is restored and the file removed:
Creating a new pool with the feature explicitly disabled and replicating the desired datasets is one workaround if your pool has the feature active:
Please keep in mind these are simplified, contrived examples. If you aren’t sure of how to replicate your pool yourself, seek help on the TrueNAS forums.
After upgrade to 22.02-RC.1, the only visible artifact of the feature is that the unsupported flag is present in zpool get all
:
root@truenas[~]# zpool get all storage | grep xattr_compat
storage unsupported@com.ixsystems:xattr_compat inactive local
The unsupported feature will not presented by zpool status
.
It is not possible to disable the feature once it is enabled; however, having the feature in the enabled state, should not cause a problem. The problem arises when the feature is active. There is currently no practical way to tell which datasets or snapshots are keeping the feature active, so while destroying all traces of it should in theory return the feature from active back to enabled, in practice it is hard to know you won’t have to end up destroying the whole pool anyway. For information on how to perform data protection procedures, please refer to the TrueNAS SCALE Data Protection documentation.
This section provides instructions for users that are configuring TrueNAS SCALE for the first time.
TrueNAS Enterprise
After completing the installation process, you can either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the SCALE UI to make network changes and complete the initial configuration.
Configuring your system includes:
Now that you have installed TrueNAS SCALE or migrated from TrueNAS CORE to SCALE, you can log into the SCALE web user interface (UI) to complete your initial system configuration and begin managing data!
Use only the web user interface (UI) to make configuration changes to the system. By default, using the LINUX shell command-line interface (CLI) to modify the system does not modify the settings database. After a system restart, changes made in the CLI revert to the original database settings, wiping away any user-made command line changes.
TrueNAS automatically creates several ways to access the UI, but you might need to adjust the default settings for your network environment.
By default, a fresh install of TrueNAS SCALE provides a default address for logging in to the web interface. To view the web interface IP address or reconfigure web interface access, either connect a monitor and keyboard to your TrueNAS system or connect with IPMI for out-of-band system management.
When powering on a TrueNAS system, the system attempts to connect to a DHCP server from all live interfaces to access the web UI. On networks that support Multicast Domain Name Services (mDNS), the system can use a host name and domain to access the TrueNAS web interface. By default, TrueNAS uses the host name and domain truenas.local. To change the host name and domain in the web interface, go to Network and click Settings on the Global Configuration widget.
To access the web interface using an IP address, either use the DHCP-assigned IP address displayed at the top of the Console Setup menu after installing SCALE or use the static IP address you assigned using the Console Setup menu.
TrueNAS EnterpriseSCALE Enterprise (HA) systems have specific network configuration requirements. Installing TrueNAS SCALE on High Availability (HA) systems and configuring networking is complicated and should be guided by Enterprise-level support. Contact iXsystems Support for assistance whenever attempting to install TrueNAS SCALE on Enterprise HA hardware or configure network settings.
Refer to the Preparing for SCALE UI Configuration (Enterprise) and Installing SCALE Enterprise (HA) for information on installing HA system and configuring networking.
Use a computer with access to the same network as the TrueNAS system. Enter the host name and domain or IP address assigned to the primary network interface in a web browser to connect to the SCALE web interface.
The browser used to access the SCALE UI can impact the quality of your user experience. We generally recommend using Firefox, Edge, or Chrome.
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.
TrueNAS SCALE plans to permanently disable root account access in a future release.
With the implementation of administrator accounts, the root user is no longer the default administrator username.
Based on the method used to install SCALE, you can be presented with different first-time login scenarios, each described below.
After setting up the admin user from one of the scenarios documented above, enter admin and the password to log into SCALE.
To modify user credentials, go to Credentials > Local Users, click anywhere on the user row, then click Edit. For more information, see Managing Users.
If logging in with the root user credentials, enter root as the user and the root password.
After logging in with the root user credentials, you must immediately create the admin user account and then disable the root user password to comply with FIPS security hardening standards.
The root user still exists but with the password disabled by default. This means only an administrative user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Follow the directions in Managing Users to create an admin user with all required settings.
If you selected the SCALE installation option 3. Configure using Web UI, the sign-in screen shows two authentication methods. One allows you to log in as root or you can create the administration account.
Select either the Administrative user or Root user (not recommended) option, then enter the password to use with that user.
If you choose Root user (not recommended) as the TrueNAS authentication method, go to the Credentials > Local Users screen and create the admin account immediately after you enter the UI. Enter the admin user name and password, make sure the password is enabled, and click Save. After setting up the admin user, click on the root user and then click Edit. Disable the root user password and then click Save. This brings the system into compliance with FIPS system security-hardening standards.
If you cannot remember the administrator password to log in to the web interface, connect a keyboard and mouse to the TrueNAS system and open the Console Setup menu to reset the admin account password.
After logging in for the first time, the main system Dashboard screen displays. The Dashboard shows different system information cards (widgets) with basic information about the installed version, systems component usage, network traffic, and configured pools or storage usage.
TrueNAS EnterpriseSCALE Enterprise users with an iXsystems-provided TrueNAS server also see an image of the system in the System Information widget. Click on the system image to open the System Settings > View Enclosure screen.
The Dashboard for non-Enterprise systems displays the TrueNAS SCALE logo on the System Information widget.
You can reorder dashboard widgets by clicking Reorder and then dragging them into your preferred order. You can also choose which widgets appear on the dashboard by clicking Configure.
The top row (toolbar) has links to outside resources and buttons to control the system. The left-hand panel lists the main feature and functional areas and lets users navigate to the various TrueNAS configuration screens.
The SCALE top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI. Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens. It also shows the name of admin user currently logged into the system to the left of the Settings and Power icons.
You can also collapse or expand the main function menu on the left side of the screen.
To monitor and manage all active sessions, go to System Settings > Advanced and locate the Access widget.
With access to the TrueNAS SCALE web interface and all the management options, you can begin configuring your system!
TrueNAS Enterprise
TrueNAS SCALE users should follow the instructions provided below to complete the initial setup and configuration of their systems.
Use the information mentioned in the installation preparation instructions article for your SCALE installation type (Enterprise, non-Enterprise, or home use) to configure your network, SMTP, or directory service settings.
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.
TrueNAS SCALE plans to permanently disable root account access in a future release.
After logging into SCALE as admin, you can begin configuring SCALE using the web interface.
TrueNAS EnterpriseTrueNAS SCALE Enterprise customers should contact iXsystems support to obtain license information for their TrueNAS system. To apply the license information, go to the System Settings > General screen and use the Update License option on the Support widget (system information card).
TrueNAS SCALE Enterprise customers with Silver or Gold Coverage support contracts can configure proactive support.
Customers with appropriate support contracts can configure Proactive Support after they apply their system license, and after acknowledging and signing the End User License Agreement (EULA).
The Support widget on the System Settings > General screen displays the Proactive Support option after entering your system license.
TrueNAS uses DHCP to assign the IP address required to access the SCALE UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by SCALE, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure SCALE.TrueNAS EnterpriseFor Enterprise systems, have your network information ready to provide iXsystems Support when they guide you through your configuration.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the SCALE UI to configure your network interfaces and other network configuration settings. The TrueNAS SCALE UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS SCALE if you make a mistake with network interface settings.
If you are unfamiliar with network services, devices, or configurations, you can find more information here to help guide you through this important and required configuration area.
TrueNAS EnterpriseYou must disable failover in the UI on SCALE Enterprise HA systems to add or change any network setting. Complete network changes and test them, then re-enable failover.
If your system has more than one network interface card (NIC) connected to your internal network (wired to your router or Internet access point), you can add an interface in SCALE. DHCP is available for only a single interface; any other physical interfaces must be configured with static IP addresses.
You can also configure virtual network interfaces such as a bridge, link aggregate (LAGG), or virtual LAN (VLAN) interface.
You can use the Console Setup menu or SCALE UI to configure network interfaces. We recommend using the web UI the Network screen to add or change network interfaces or aliases, set up link aggregate LAGG or virtual LAN VLAN interfaces, change or configure global network settings, or set up static IP addresses.
Static IP addresses and aliases provide support for various network applications.
You can configure a network interface with a static IP or add an alias IP address on the same screen in the SCALE UI. For more information on when to use an alias or a static IP address, see Managing Interfaces.TrueNAS EnterpriseSCALE Enterprise HA systems use a virtual IP (VIP) to maintain access to the UI if the system fails over to the standby controller. This VIP address might experience a minor blip at failover, but you do not need to log in with the standby controller IP address to gain access to the UI after a failover.
TrueNAS SCALE requires at least one storage pool. We recommend you create the required pool and then plan the rest of your storage needs before adding sharing, container applications, virtual machines, or data storage. When planning your data storage, consider the type of data sharing you want to do, any container applications you might want to deploy, and how you want to organize stored data.
The storage creation process begins with creating a pool, then adding datasets or zvols as needed. Creating your initial storage is explained here.
SCALE assigns the root parent dataset of the first created pool as the system dataset. If your system has enough disks to add more pools, you can change the system dataset to a root dataset of different pool.
After setting up your system storage, you can configure data sharing using one of the sharing protocols available in SCALE.
These articles provide more information on configuring data sharing and the three built-in share types available in SCALE:
Share Type | Purpose |
---|---|
SMB shares | Used for Windows shares and also to set up deprecated AFP sharing. |
NFS shares | Used for Linux-based shares. |
iSCSI shares | Used for block shares. |
Configure and enable the services you need based on what you deploy on your SCALE system.
TrueNAS EnterpriseEnterprise or SCALE systems with large numbers of disks should enable SMART service and configure SMART testing. SCALE Enterprise HA systems should enable and configure the failover service.
All systems can take advantage of the SMART service and testing with compatible attached disks. Disks that do not support SMART testing do not display the option to set up testing.
See Managing SMART Tests for information on running or managing scheduled SMART tests or Managing Disks for more information on running a manual test from a selected disk.
After completing your initial system configuration and before you begin day-to-day operations, we recommend configuring the system and data storage backup. Recommended backup options:
Keep both the system configuration file and the initial system debug file in a safe location where important files are regularly backed up. You can use the boot environment in an SSH session to restore your system to the point where you completed your system configuration, and then import data or pools to recover stored data.
TrueNAS EnterpriseFor Enterprise customers with High Availability (HA) systems, the HA restore process requires recovering both controllers. Contact iXsystems Support for assistance before attempting to recover your system. If you choose to restore access to controller 1 and the SCALE UI, contact iXsystems Support to get assistance with properly recovering your second controller.
Enterprise HA customers should not start issuing CLI commands to recover the system!
Contact iXsystems Support after you restore access to controller 1 to request further assistance and before taking actions that can disrupt or damage system access further and result in requiring a complete reinstall to recover.
After saving system configuration and debug files, we recommend setting up data storage backups using any or all of the following methods:
You can take single snapshots or schedule periodic snapshot tasks to capture changes to stored data without the storage overhead that comes with backing up through data replication, or you can use one of the replication options SCALE provides.
Another option is to create an account with a cloud storage service provider, then let SCALE manage the backups. Use the Backup Credentials screen Cloud Credentials to add authentication credentials for a supported cloud service provider, and go to Data Protection to schedule a Cloud Sync Tasks that regularly backs up your storage data to the cloud.
You can view system alerts, configure an alert service, and enter an email account to receive alerts from SCALE through the Alerts icon found on the top toolbar.
TrueNAS SCALE allows you to configure an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings. SCALE allows configuring either directory server but not both.
We do not recommended that you switch between directory services. This can result in configuration issues that could disrupt your system!
However, it is possible to change from either directory service to the other. If you want to migrate from LDAP to Active Directory, you must disable LDAP in SCALE and then remove the current directory server settings. To change from Active Directory to LDAP, use the Leave Domain option and then disable the service before attempting to configure and enable LDAP.
TrueNAS EnterpriseiXsystems Support can assist Enterprise customers with configuring directory service settings in SCALE with the information customers provide, but they cannot configure customer Active Directory system settings.
Non-Enterprise users can find support for configuring directory services in the TrueNAS Documentation Hub tutorials or in the community forums.
TrueNAS EnterpriseFor TrueNAS Enterprise customers with compatible hardware, the TrueNAS SCALE main Dashboard displays an image of the TrueNAS system server on the System Information widget. Click on the image to open the View Enclosure screen, or select the System Settings > Enclosure option on the main menu navigation panel.
The View Enclosure screen provides details on the system disks, the pools and VDEVs disks are in, the hardware details, and the disk status. Click on a drive to view the disk details. If the TrueNAS system has an expansion shelf, the Enclosure screen also displays an image of the expansion shelf populated with disks.
If using SCALE on servers not provided by TrueNAS, the System Information widget on the Dashboard displays the TrueNAS SCALE logo, and the System Settings > Enclosure option does not exist on the menu navigation panel.
SCALE provides a list of applications you can deploy on the Apps > Discover screen.
See the Apps tutorials for procedures on generically deploying and managing apps, app catalogs and images, custom apps, and specific app deployments and notes.
You can update your system with an
There are a few ways to find available updates for your instance of TrueNAS SCALE:
For all update options and procedures using the SCALE UI see Updating SCALE.
Always save the system configuration file and save a new boot environment for your current release and configuration before updating to a new incremental or full release.
It is also good practice to download a fresh debug file before and after a system update.
Now that you are logged in to the web interface, it is time to set up TrueNAS storage. These instructions describe a simple mirrored pool setup, where half the selected disks are used for storage and the other half for data protection. However, there are many configuration possibilities for your storage environment!
You can read more about these options in Creating Storage Pools. You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.
At minimum, the system needs at least two disks of identical size to create a mirrored storage pool. While a single-disk pool is technically allowed, it is not recommended. The disk used for the TrueNAS installation does not count toward this minimum.
You can configure data backups in several ways and have different requirements. Backing data up in the cloud requires a 3rd party cloud storage provider account. Backing up with replication requires you to have additional storage on the TrueNAS system or (ideally) another TrueNAS system in a different location.
Your system must have at least one storage pool configured.
After installing SCALE, enter the IP address assigned by DHCP (displayed in the Console Setup Menu) into a browser window to access the SCALE sign-in splash screen. Log in to SCALE.
Begin by configuring your first storage pool.
See Creating Storage Pools for more information on how to plan for and create pools in SCALE. If you want to create additional pools with other disks not assigned to a pool, you can do that now or as you have a need for them.
Click Create Pool to open the Pool Creation Wizard.
Enter a name of up to 50 lowercase alpha-numeric characters. Use only the permitted special characters that conform to ZFS naming conventions. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
You cannot change the pool name after creation.
Create the required data VDEV.
Select the layout from the Layout dropdown list, then either use the Automated Disk Selection fields to select and add the disks, or click Manual Disk Selection to add specific disks to the chosen Layout.
dRAID layouts do not show the Manual Disk Selection button but do show additional Automated Disk Selection fields. When configuring a dRAID data VDEV, first choose a Disk Size then select a Data Devices number. The remaining fields update based on the Data Devices and dRAID layout selections.
Click Save And Go To Review if you do not want to add other VDEV types to the pool, or click Next to move to the next wizard screens.
Add any other optional VDEVs as determined by your specific storage redundancy and performance requirements.
Click Create Pool on the Review wizard screen to add the pool.
The root dataset of the first pool you create automatically becomes the system dataset.
After adding your first pool, you can move on to creating datasets for data sharing, applications you plan to deploy, or other use cases.
New pools have a root dataset that allows further division into new non-root parent and child datasets or into storage volumes (zvols). A dataset is a file system that stores data and has specific permissions.
A zvol is a virtual block device (like a virtual disk drive) that has a predefined storage size. Zvols are generally used with the iSCSI sharing protocol and also virtual machines (VMs) for their data storage needs.
To create a dataset or zvol, you can click Datasets on the main navigation panel or go to Storage and click Manage Datasets on the Usage widget for a specific pool to open the Datasets screen.
To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select the Dataset Preset option you want to use. Options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but this dataset is not used for application data storage. If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting is found under Advanced Options and is not editable after saving the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.
Organize the pool with as many datasets or zvols you need according to your access and data sharing requirements before moving data into the pool.
See Adding or Managing Datasets for more information on configuring datasets, or Adding or Managing Zvols for more information on zvols.
After you finish creating your initial pool and the datasets or zvols, you can continue building and organizing your TrueNAS pools and datasets or move on to configuring how the system shares data.
If you do not plan to set up data sharing, you can set up backup solutions for your system and stored data.
After setting up storage on your TrueNAS, it is time to begin sharing data! There are several sharing solutions available on SCALE, but in this article we discuss the most common.
TrueNAS SCALE provides three types of sharing methods:
For more information on TrueNAS SCALE shares, see the Shares tutorials.
Regardless of what type of share you create, you need to create the user and dataset for the share.
Share users are those with permissions to access the share. You can create the user before you create the share or after creating the share. Administrators can provision share users using a directory server such as Active Directory or LDAP.
To add non-SMB share users or edit users, go to Credentials > Local Users to add or edit the user(s). Click Add to create a new or as many new user accounts as you need.
Enter the values in each required field, verify Samba Authentication is selected for SMB share users, then click Save. For more information on the fields and adding users, see Creating User Accounts.
By default, all new local users are members of a built-in group called builtin_users. You can use a group to grant access to all local users on the server or add more groups to fine-tune permissions for large numbers of users.
After creating the share user account(s), next create the share and dataset. For iSCSI shares, create the dataset then the share. You can create an SMB or NFS share while creating the dataset or create the dataset while creating the share.
For more information on adding SMB shares, see Adding SMB Shares.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled. You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To set up a basic SMB share:
Create the share and dataset.
a. Go to Shares, then click Add on the Windows (SMB) Shares widget to open the Add SMB configuration screen.
b. Select the dataset mount path or enter it in Path. You can click on the to the left of mnt, and then at the pool to expand the options. Continue expanding until reaching the dataset where you want to add the share dataset. Click on the dataset to populate the field with the full path.
c. Click Create Dataset, enter a name in the Create Dataset dialog, then click Create. The system creates the share dataset and populates both the Path and share Name fields with the name given the dataset. The dataset name becomes the share name.
d. Change any Advanced Options settings you want to customize the dataset and share. Click Enable to set up audit logging, or to change case sensitivity from the default Sensitive setting, then click Save.
Start the SMB service when prompted.
Edit the SMB share permissions to set the share owner and/or group.
a. Click on
Edit Share ACL icon to open the Edit Share ACL screen.b. Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
c. (Optional) Click Add then select Group, then the group name, and set the group permissions.
d. Click Save.
Edit the dataset for the SMB share permissions to set the share owner and/or group.
a. Click on
Edit Fileshsystem ACL icon to open the Edit ACL screen for the dataset.b. Select the Owner and Group and click Apply Owner and Apply Group. With Who set to Owner, set the permission level using Permissions and Type.
c. Click Save.
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.
Connect to the share. On a Windows 10 or later system, open the File Browsers and then:
a. Enter \\
and the TrueNAS system name or IP address in the navigation bar. A login credentials dialog displays.
b. Enter the TrueNAS user account credentials you created on the TrueNAS system.
c. Begin browsing the dataset.
For more information on creating NFS shares, see Adding NFS Shares.
To set up NFS sharing:
Add additional packages like nfs-common
to any client systems that require them.
Create the NFS share and dataset.
a. Go to Shares, then click Add on the UNIX (NFS) Share Targets to open the Add NFS configuration screen.
b. Select the dataset mount path or enter it in Path. You can click on the to the left of mnt, and then at the pool to expand the options. Continue expanding until reaching the dataset where you want to add the share dataset. Click on the dataset to populate the field with the full path.
c. Click Create Dataset, enter a name in the Create Dataset dialog, then click Create. The system creates the share dataset and populates both the Path and share Name fields with the name given the dataset. The dataset name becomes the share name.
d. Finish the NFS share configuration if you want to add network and hosts at this time, or click Advanced Options to configure additional settings.
e. Click Save.
Access the dataset.
On a Unix-like system, open a command line and enter command showmount -e {IPADDRESS}
where {IPADDRESS} is your TrueNAS system IP address.
tmoore@ChimaeraPrime:~$ showmount -e 10.238.15.194
Export list for 10.238.15.194:
/mnt/pool1/testds (everyone)
Make a local directory for the NFS mount. Enter command sudo mkdir nfstemp/
.
tmoore@ChimaeraPrime:~$ sudo mkdir nfstemp/
Mount the shared directory.
Enter command sudo mount -t nfs {IPADDRESS:dataset path}
where {IPADDRESS} is your system IP address and {:dataset path} is the full path displayed in step 3.b. above.
tmoore@ChimaeraPrime:~$ sudo mount -t nfs 10.238.15.194:/mnt/pool1/testds nfstemp/
From here, cd
into the local directory and view or modify the files as needed.
Setting up block sharing is a complicated scenario that requires detailed configuration steps and knowledge of your network environment. A simple configuration is beyond the scope of this getting started guide, but detailed articles are available in the SCALE Tutorials section.
With simple sharing now set up, you can back up your configuration and set up data backup.
After configuring your TrueNAS storage and data sharing or any other function, service, or application, it is time to ensure an effective data backup.
You should also:
You should also set up a data storage backup method using either a cloud sync or replication task.
TrueNAS provides for data backup through cloud sync or replication.
Cloud sync requires an account with a cloud storage provider and a storage location created with that provider, like an Amazon S3 bucket. SCALE supports major providers like Storj, Amazon S3, Google Cloud, Box, and Microsoft Azure, along with a variety of other vendors. These providers can charge fees for data transfer and storage, so please review the policies of your cloud storage provider before transferring your data.
You can configure TrueNAS to send, receive, or synchronize data with a cloud storage provider. The simplest way to set up a cloud sync task is using an iX-Storj account.
See Adding Cloud Credentials for information on connecting TrueNAS SCALE to other cloud storage providers.
Replication is the process of taking a moment-in-time snapshot of data and then copying that snapshot to another location. Snapshots typically use less storage than full file backups and have more management options.
You can monitor created backup tasks from the Dashboard widget.
Now that you configured your system network, storage, and the data shares you want, and you have set up your data backup solution, it is time to back up your system configuration.
After saving the system configuration, go to System Settings > Advanced and click Save Debug. After the download completes, save this initial debug file with your system configuration file.
After installing and completing your SCALE system configuration, create a boot environment to use as a restore point. If an issue occurs where you lose access to the SCALE UI, you can establish an SSH session and restore it from the boot environment. You can clone the boot environment listed after the initial-install environment and rename the clone to something you recognize, such as the release number with date and time.
Configuring TrueNAS SCALE to work with virtualized features, such as virtual machines (VMs) and applications, is part of the setup process that, when optimized, takes advantage of the network storage capabilities that SCALE offers.
This article assumes you have the latest release version of TrueNAS SCALE installed on your system. The following steps are a list of configuration prerequisites you have completed and are familiar with before beginning VM and application installations.
The primary network interface is configured as part of the SCALE installation process. Go to Network > Global Configuration screen in the TrueNAS web UI to determine if the default gateway, host name, domain, and DNS name servers have been configured correctly. See Console Setup Menu Configuration for more information on network settings.
You can configure a virtual LAN (VLAN) to route traffic for your VMs. VLAN benefits include the reduction of broadcast traffic and the ability to group resources in different physical locations into a broadcast domain. VLANs virtually segment a network. Different VLANs can communicate with each other using layer 3 devices. See Setting Up a Network VLAN for more information on creating virtual LANs (VLAN).
Storage pool creation is part of the initial process of setting up storage for SCALE. A TrueNAS dataset is a file system within a data storage pool. See Setting Up Storage to review storage pool creation and Adding and Managing Datasets for information on dataset configuration.
After creating the pool and datasets, set up shares to enable data access. Different types of data sharing methods are discussed in Setting Up Data Sharing. You should investigate more specific coverage of each share based on your use case.
SMB Shares Screens and Setting Up SMB Home Shares provide a good introduction as to how TrueNAS SCALE handles SMB shares.
See Adding NFS Shares for information on creating a basic NFS share. Adjust access permissions using the advanced options.
Certain directory services must be set up as part of SMB and NFS share configuration. See Active Directory Screen for a better understanding of how to configure Active Directory and Configuring Kerberos for an outline of required Kerberos information. For LDAP best practices see Configuring LDAP.
To run a virtual machine (VM), hardware requirements include an x86 machine running a recent Linux kernel using either an Intel processor with VT extensions or an AMD processor with SVM extensions (AMD-V). To install a VM on SCALE, first research the minimum and recommended specifications for the OS you plan to use and your full use case for that VM. Allocating too many resources to a VM can cause performance on the TrueNAS SCALE system to suffer. We recommend you plan for and ensure your SCALE system has the resources to run itself and a full VM deployment effectively.
Software requirements include an installer for the OS you intend to install on the VM.
A TrueNAS storage pool is required. We recommend you create additional datasets beneath the storage pool to organize your VM data further.
Review Virtualization Screens to determine requirements for VM installation. See Adding and Managing VMs for more information on adding or managing VMs.
The first time you open the Applications screen, it displays an Apps Service Not Configured status on the screen header.
Click Settings > Choose Pool to choose a storage pool for Apps.
A storage pool for applications must be chosen before application installation can begin. Select a pool with enough space for all the application containers you intend to use. Set up a new dataset before installing your applications if you want to store your application data in a separate location from other storage on your system.
After an Apps storage pool is configured, the status changes to Apps Service Running.
Use Discover Apps to view available applications. See Apps tutorials and Apps reference guide for more information.
For custom applications, Install Custom App details each field on the Install Custom App screen. Before beginning a custom application installation, determine the following information:
You can find additional options for configuring general network interfaces and IP addresses for application containers in Apps > Settings > Advanced Settings.
TrueNAS EnterpriseEnterprise SCALE hardware customers with support contracts can contact iXsystems Support using either the Commercial Support option on the top header of the TrueNAS Documentation Hub website, or through one of the contact options listed below.
TrueNAS SCALE users are welcome to report bugs, suggest new TrueNAS features, and vote for suggested improvements in the Jira project instance. Have questions? We recommend searching through the software documentation and community resources for answers.
Non-Enterprise SCALE customers experiencing software bugs or instability can try to find answers in the various community forums, or they can file an issue ticket through the Jira ticket reporting system for TrueNAS (details).
When reporting an issue, download a system debug file taken immediately following the issue occurrence. This captures the system configuration information and logs iXsystems needs to help resolve your issues.
Upload this debug to the private attachments area using the link provided when you open a Jira ticket. After uploading the file, link the attachment to the Jira ticket number before you click Save.
Support is also available through the TrueNAS community forums, blog, and Discord. These options are accessible on the top header of the TrueNAS Documentation Hub website and from the links at the bottom of all articles.
The TrueNAS Community is an active online resource for asking questions, troubleshooting issues, and sharing information with other TrueNAS users. You must register to post.
We encourage new users to briefly review the forum rules and helpful tips before posting.
Community Resources are user-contributed articles about every facet of using TrueNAS. They are organized into broad categories and incorporate a community rating system to better highlight content that the whole community has found helpful.
You are always welcome to network with other TrueNAS users using the various social media platforms!
We encourage TrueNAS SCALE users to report bugs and to vote for or suggest new TrueNAS features in the project Jira instance. You must have a Jira account to create a bug ticket.
If you encounter a bug or other issue while using TrueNAS SCALE, you can report issues in one of two ways:
The web interface provides a form to report issues without logging out of SCALE. The form prompts you to provide the information and attachments we need to assist users.
New Jira tickets are publicly viewable so it is possible to search the project first to see if another user already reported the issue.
Each Jira ticket sends a link to a private file attachment area to safeguard user personal and private data. We encourage users to use the link in the automated report response to keep the debug file secure and restrict access to only those that require the information to diagnose the cause of the issue reported.
If the attached files do not require privacy, attach them to the Jira ticket. All incoming tickets are triaged. If private files are attached to a new ticket, the ticket or files can be made private at that time.
System debugs contain log files which can include personal information such as usernames, and other identifying information about your system such as networking configuration, device serial numbers, etc. Users can use a file archiver utility, such as 7-Zip File Manager, to open compressed debug archives and review log contents. Redact any personal data you have concerns about sharing and save the debug file before attaching and linking it to a Jira ticket in the TrueNAS project.
The How would you rate this page? icon opens a feedback window. Alternately, go to System Settings > General, find the Support widget, and click File Ticket to see the feedback window.
The feedback window allows users to send page ratings, comments, and report issues or suggest improvements directly to the TrueNAS development team. Submitting a bug report or improvement suggestion requires a free Atlassian account.
Click between the different tabs at the top of the window to see different options for your specific feedback.
Important - Please Read This EULA Carefully
PLEASE CAREFULLY READ THIS END USER LICENSE AGREEMENT (EULA) BEFORE CLICKING THE AGREE BUTTON. THIS AGREEMENT SERVES AS A LEGALLY BINDING DOCUMENT BETWEEN YOU AND IXSYSTEMS, INC. BY CLICKING THE AGREE BUTTON, DOWNLOADING, INSTALLING, OR OTHERWISE USING TRUENAS SCALE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS AGREEMENT). IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS IN THIS AGREEMENT, DO NOT USE OR INSTALL TRUENAS SCALE SOFTWARE.
This agreement is provided in accordance with the Commercial Arbitration Rules of the American Arbitration Association (the “AAA Rules”) under confidential binding arbitration held in Santa Clara County, California. To the fullest extent permitted by applicable law, no arbitration under this EULA will be joined to an arbitration involving any other party subject to this EULA, whether through class arbitration proceedings or otherwise. Any litigation relating to this EULA shall be subject to the jurisdiction of the Federal Courts of the Northern District of California and the state courts of the State of California, with venue lying in Santa Clara County, California. All matters arising out of or relating to this agreement shall be governed by and construed in accordance with the internal laws of the State of California without giving effect to any choice or conflict of law provision or rule.
1.1 “Company”, “iXsystems” and “iX” means iXsystems, Inc., on behalf of themselves, subsidiaries, and affiliates under common control.
1.2 “TrueNAS SCALE Software” means the TrueNAS SCALE storage management software.
1.3 “TrueNAS Device” means the TrueNAS storage appliances and peripheral equipment provided by iXsystems or a third party.
1.4 “Product” means, individually and collectively, the TrueNAS SCALE Software and the TrueNAS Device provided by iXsystems.
1.5 “Open Source Software” means various open source software components licensed under the terms of applicable open source license agreements, each of which has its own copyright and its own applicable license terms.
1.6 “Licensee”, “You” and “Your” refers to the person, organization, or entity that has agreed to be bound by this EULA including any employees, affiliates, and third party contractors that provide services to You.
1.7 “Agreement” refers to this document, the TrueNAS End User License Agreement.
Subject to the terms set forth in this Agreement, iXsystems grants You a non-exclusive, non-transferable, perpetual, limited license without the option to sublicense, to use TrueNAS SCALE Software on Your TrueNAS Device(s). This use includes but is not limited to using or viewing the instructions, specifications, and documentation provided with the Product.
TrueNAS SCALE software is made available as Open Source Software, subject to the license conditions contained within that Open Source Software.
TrueNAS SCALE Software is authorized for use on any TrueNAS Device. TrueNAS Devices can include hardware provided by iXsystems or third parties. TrueNAS Devices may also include virtual machines and cloud instances. TrueNAS SCALE software may not be commercially distributed or sold without an addendum license agreement and express written consent from iXsystems. .
The TrueNAS SCALE Software is protected by copyright laws and international treaties, as well as other intellectual property laws, statutes, and treaties. The TrueNAS SCALE Software is licensed, not sold to You, the end user. You do not acquire any ownership interest in the TrueNAS SCALE Software, or any other rights to the TrueNAS SCALE Software, other than to use the TrueNAS SCALE Software in accordance with the license granted under this Agreement, subject to all terms, conditions, and restrictions. iXsystems reserves and shall retain its entire right, title, and interest in and to the TrueNAS SCALE Software, and all intellectual property rights arising out of or relating to the TrueNAS SCALE Software, subject to the license expressly granted to You in this Agreement.
The TrueNAS SCALE Software may contain iXsystems’ proprietary trademarks and collateral. By agreeing to this license agreement for TrueNAS SCALE, You agree to use reasonable efforts to safeguard iXsystems’ intellectual property and hereby agree to not use or distribute iXsystems’ proprietary intellectual property and collateral commercially without the express written consent of iXsystems. Official iXsystems Channel Partners are authorized to use and distribute iXsystems’ intellectual property through an addendum to this license agreement. By accepting this Agreement, You are responsible and liable for all uses of the Product through access thereto provided by You, directly or indirectly.
The TrueNAS SCALE software includes Open Source components and some proprietary extensions which are available through additional licences You agree to not alter the source code to take advantage of the proprietary extensions without a license to those proprietary extensions, including the TrueNAS Enterprise features sets.
4.1 Entire Agreement - This Agreement, together with any associated purchase order, service level agreement, and all other documents and policies referenced herein, constitutes the entire and only agreement between You and iXsystems for use of the TrueNAS SCALE Software and all other prior negotiations, representations, agreements, and understandings are superseded hereby. No agreements altering or supplementing the terms hereof may be made except by means of a written document signed by Your duly authorized representatives and those of iXsystems.
4.2 Waiver and Modification - No failure of either party to exercise or enforce any of its rights under this EULA will act as a waiver of those rights. This EULA may only be modified, or any rights under it waived, by a written document executed by the party against which it is asserted.
4.3. Severability - If any provision of this EULA is found illegal or unenforceable, it will be enforced to the maximum extent permissible, and the legality and enforceability of the other provisions of this EULA will not be affected.
4.4 United States Government End Users - For any TrueNAS SCALE Software licensed directly or indirectly on behalf of a unit or agency of the United States Government, this paragraph applies. Company’s proprietary software embodied in the Product: (a) was developed at private expense and is in all respects Company’s proprietary information; (b) was not developed with government funds; (c) is Company’s trade secret for all purposes of the Freedom of Information Act; (d) is a commercial item and thus, pursuant to Section 12.212 of the Federal Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202, Government’s use, duplication or disclosure of such software is subject to the restrictions set forth by the Company and Licensee shall receive only those rights with respect to the Product as are granted to all other end users.
4.5 Title - iXsystems retains all rights, titles, and interest in TrueNAS SCALE Software and all related copyrights, trade secrets, patents, trademarks, and any other intellectual and industrial property and proprietary rights, including registrations, applications, registration keys, renewals, and extensions of such rights. Contact Information - If You have any questions about this Agreement, or if You want to contact iXsystems for any reason, please email legal@ixsystems.com.
4.6 Maintenance and Support - You may be entitled to support services from iXsystems after purchasing a Product or a support contract. iXsystems will provide these support services based on the length of time of the purchased support contract. This maintenance and support is only valid for the length of time that You have purchased with Your Product. iXsystems may from time to time and at their sole discretion vary the terms and conditions of the maintenance and support agreement based on different business environmental and personnel factors. Any variations will be notified via email and the support portal. For more information on our Maintenance and Support contract, refer to https://www.ixsystems.com/support/.
4.7 Force Majeure - iXsystems will not be deemed to be in default of any of the provisions of this Agreement or be liable for any delay or failure in performance due to Force Majeure, which shall include without limitation acts of God, earthquake, weather conditions, labor disputes, changes in law, regulation or government policy, riots, war, fire, epidemics, acts or omissions of vendors or suppliers, equipment failures, transportation difficulties, malicious or criminal acts of third parties, or other occurrences which are beyond iXsystems’ reasonable control.
4.8 Termination - iXsystems may cease any and all support, services, or maintenance under this Agreement without prior notice, or liability, and for any reason whatsoever, without limitation, if any of the terms and conditions of this Agreement are breached. Other provisions of this Agreement will survive termination including, without limitation, ownership provisions, warranty disclaimers, indemnity, and limitations of liability.
4.9 Open Source Software Components - iXsystems uses Open Source Software components in the development of the TrueNAS SCALE Software. Open Source Software components that are used in the TrueNAS SCALE Software are composed of separate components each having their own trademarks, copyrights, and license conditions.
4.10 Assignment - Licensee shall not assign or otherwise transfer any of its rights, or delegate or otherwise transfer any of its obligations or performance, under this Agreement, in each case whether voluntarily, involuntarily, by operation of law, or otherwise, without iXsystems’ prior written consent. No delegation or other transfer will relieve Licensee of any of its obligations or performance under this Agreement. Any purported assignment, delegation, or transfer in violation of this Section is void. iXsystems may freely assign or otherwise transfer all or any of its rights, or delegate or otherwise transfer all or any of its obligations or performance, under this Agreement without Licensee’s consent. This Agreement is binding upon and inures to the benefit of the parties hereto and their respective permitted successors and assigns.
“The Product may be subject to export control laws. You shall not, directly or indirectly, export, re-export, or release the Product to, or make the Product accessible from, any jurisdiction or country to which export, re-export, or release is prohibited by law, rule, or regulation. You shall comply with all applicable laws, regulations, and rules, and complete all required undertakings (including obtaining any necessary export license or other governmental approval).”
TrueNAS SCALE Software may collect non-sensitive system information relating to Your use of the Product, including information that has been provided directly or indirectly through automated means. Usage of TrueNAS SCALE Software, device status and system configuration are allowed according to iXsystems’ privacy policy.
TrueNAS SCALE Software will not collect sensitive User information including email addresses, names of systems, pools, datasets, folders, files, credentials.
By accepting this Agreement and continuing to use the Product, you agree that iXsystems may use any information provided through direct or indirect means in accordance with our privacy policy and as permitted by applicable law, for purposes relating to management, compliance, marketing, support, security, update delivery, and product improvement.
THE PRODUCT IS PROVIDED “AS IS” AND WITH ALL FAULTS AND DEFECTS WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED UNDER APPLICABLE LAW, IXSYSTEMS, ON ITS OWN BEHALF AND ON BEHALF OF ITS AFFILIATES AND ITS AND THEIR RESPECTIVE LICENSORS AND SERVICE PROVIDERS, EXPRESSLY DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO THE PRODUCT, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, AND WARRANTIES THAT MAY ARISE OUT OF COURSE OF DEALING, COURSE OF PERFORMANCE, USAGE, OR TRADE PRACTICE. WITHOUT LIMITATION TO THE FOREGOING, IXSYSTEMS PROVIDES NO WARRANTY OR UNDERTAKING, AND MAKES NO REPRESENTATION OF ANY KIND THAT THE PRODUCT WILL MEET THE LICENSEE’S REQUIREMENTS, ACHIEVE ANY INTENDED RESULTS, BE COMPATIBLE, OR WORK WITH ANY OTHER SOFTWARE, APPLICATIONS, SYSTEMS, OR SERVICES, OPERATE WITHOUT INTERRUPTION, MEET ANY PERFORMANCE OR RELIABILITY STANDARDS OR BE ERROR FREE, OR THAT ANY ERRORS OR DEFECTS CAN OR WILL BE CORRECTED.
TO THE FULLEST EXTENT PERMITTED UNDER APPLICABLE LAW: (A) IN NO EVENT WILL IXSYSTEMS OR ITS AFFILIATES, OR ANY OF ITS OR THEIR RESPECTIVE LICENSORS OR SERVICE PROVIDERS, BE LIABLE TO LICENSEE, LICENSEE’S AFFILIATES, OR ANY THIRD PARTY FOR ANY USE, INTERRUPTION, DELAY, OR INABILITY TO USE THE PRODUCT; LOST REVENUES OR PROFITS; DELAYS, INTERRUPTION, OR LOSS OF SERVICES, BUSINESS, OR GOODWILL; LOSS OR CORRUPTION OF DATA; LOSS RESULTING FROM SYSTEM OR SYSTEM SERVICE FAILURE, MALFUNCTION, OR SHUTDOWN; FAILURE TO ACCURATELY TRANSFER, READ, OR TRANSMIT INFORMATION; FAILURE TO UPDATE OR PROVIDE CORRECT INFORMATION; SYSTEM INCOMPATIBILITY OR PROVISION OF INCORRECT COMPATIBILITY INFORMATION; OR BREACHES IN SYSTEM SECURITY; OR FOR ANY CONSEQUENTIAL, INCIDENTAL, INDIRECT, EXEMPLARY, SPECIAL, OR PUNITIVE DAMAGES, WHETHER ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, REGARDLESS OF WHETHER SUCH DAMAGES WERE FORESEEABLE AND WHETHER OR NOT IXSYSTEMS WAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES; (B) IN NO EVENT WILL IXSYSTEMS’ AND ITS AFFILIATES’, INCLUDING ANY OF ITS OR THEIR RESPECTIVE LICENSORS’ AND SERVICE PROVIDERS’, COLLECTIVE AGGREGATE LIABILITY UNDER OR IN CONNECTION WITH THIS AGREEMENT OR ITS SUBJECT MATTER, UNDER ANY LEGAL OR EQUITABLE THEORY, INCLUDING BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, AND OTHERWISE, EXCEED THE TOTAL AMOUNT PAID TO IXSYSTEMS PURSUANT TO THIS AGREEMENT FOR THE PRODUCT THAT IS THE SUBJECT OF THE CLAIM; (C) THE LIMITATIONS SET FORTH IN THIS SECTION SHALL APPLY EVEN IF THE LICENSEE’S REMEDIES UNDER THIS AGREEMENT FAIL OF THEIR ESSENTIAL PURPOSE.
You hereby acknowledge that you have read and understand this Agreement and voluntarily accept the duties and obligations set forth herein by clicking accept on this Agreement.
The TrueNAS Software Development Life Cycle (SDLC) is the process of planning, creating, testing, deploying, and maintaining TrueNAS releases.
The TrueNAS SDLC applies to the latest two release branches. As new releases are created for TrueNAS, the oldest TrueNAS release branch is dropped out of the SDLC and labeled as End of Life (EoL). For example, TrueNAS/FreeNAS 11.3 and TrueNAS 12.0 were in active development under the SDLC in August 2020. In early 2021, TrueNAS Core/Enterprise 12.0 and 13.0 branches were in active development under the SDLC. These versions of the software are in active development and maintenance. We encourage users to actively keep their software updated to an active development version to continue to receive security patches and other software improvements.
The Software Status page shows the latest recommendations for using the various TrueNAS software releases.
TrueNAS releases follow a general adoption guideline for their lifetime. Starting with the NIGHTLY builds, each stage of a major release incorporates more testing cycles and bug fixes that represent a maturation of the release. With each version release stage, users are encouraged to install, upgrade, or otherwise begin using the major version, depending on the specific TrueNAS deployment and use case:
Release Stage | Completed QA Cycles | Typical Use | Description |
---|---|---|---|
NIGHTLY | 0 | Developers | Incomplete |
ALPHA | 1 | Testers | Not much field testing |
BETA | 2 | Enthusiasts | Major Feature Complete, but expect some bugs |
RC | 4 | Home Users | Suitable for non-critical deployments |
RELEASE | 6 | General Use | Suitable for less complex deployments |
U1 | 7 | Business Use | Suitable for more complex deployments |
U2+ | 8 | Larger Systems | Suitable for higher uptime deployments |
TrueNAS collects non-sensitive system data and relays the data to a collector managed by iXsystems. This system data collection is enabled by default and can be disabled in the web interface under System Settings > General > GUI Settings > Usage collection.
When disabled, no information about system configuration and usage is collected. The system capacity and software version is still collected.
The protocol for system data collection uses the same TCP ports as HTTPS (443) and passes through most firewalls as an outgoing web connection. If a firewall blocks the data collection or the data collection is disabled, there is no adverse impact to the TrueNAS system.
Non-sensitive system data is used to identify the quality and operational trends in the fleet of TrueNAS systems used by the entire community. The collected data helps iXsystems identify issues, plan for new features, and determine where to invest resources for future software enhancements.
The non-sensitive system data collected is clearly differentiated from sensitive user data that is explicitly not collected by TrueNAS. This table describes the differences:
Sensitive User Data (NOT COLLECTED) | Non-Sensitive System Data (Optionally Collected) | |
---|---|---|
Description | Any data that includes user identity or business information | Data that only includes information about the TrueNAS system and its operation |
Frequency | NEVER | Daily |
Examples | Usernames, passwords, email addresses | Anonymous hardware inventory, faults, statistics, Pool configuration |
User-created System and dataset names | Software versions, firmware versions | |
Directory, files names, user data | Services and features enabled, Usage and Performance statistics |
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.
The SCALE top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI. Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens. It also shows the name of admin user currently logged into the system to the left of the Settings and Power icons.
You can also collapse or expand the main function menu on the left side of the screen.
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 system and allows you to add, edit, or delete keys.
To manage API keys in the TrueNAS SCALE CLI, use theauth api_key
namespace.
Click Add to display a dialog window that lets users add a new API key.
Type a descriptive name and click Add. The system displays a confirmation dialog and adds a new API key to the list.
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 that is built into the system.
TrueNAS EnterpriseThis procedure applies to SCALE Enterprise High Availability (HA) systems only.
If you need to power down your SCALE Enterprise system with HA enabled, 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.
This section contains tutorials involving the SCALE Dashboard.
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 SCALE Storage section has controls for pools, snapshots, and disk management. This section also provides access to datasets, zvols, quotas, and permissions.
Use the Import Pool button to reconnect pools exported/disconnected from the current system or created on another system. This also reconnects pools after users reinstall or upgrade the TrueNAS system.
Use the Disks button to manage, wipe, and import storage disks that TrueNAS uses for ZFS data storage.
Use the Create Pool to create ZFS data storage “pools” from physical disks. Pools efficiently store and protect data.
The Storage screen displays all the pools added to the system. Each pool shows statistics and status, along with buttons to manage the different elements of the pool.
The articles in this section offer specific guidance for the different storage management options.
ZFS pool importing works for pools exported or disconnected from the current system, those created on another system, and for pools you reconnect after reinstalling or upgrading the TrueNAS system.
The import procedure only applies to disks with a ZFS storage pool.
To import a pool, go to the Storage Dashboard and click Import Pool at the top of the screen.
TrueNAS detects the pools that are present but not connected and adds them to the Pools dropdown list.
Select a pool from the Pool dropdown list, then click Import.
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.
Hard drives and solid-state drives (SSDs) have a finite lifetime and can fail unexpectedly. When a disk fails in a Stripe (RAID0) pool, you must recreate the entire pool and restore all data backups. We always recommend creating non-stripe storage pools that have disk redundancy.
To prevent further redundancy loss or eventual data loss, always replace a failed disk as soon as possible! TrueNAS integrates new disks into a pool to restore it to full functionality.
TrueNAS requires you to replace a disk with another disk of the same or greater capacity as a failed disk. You must install the disk in the TrueNAS system. It should not be part of an existing storage pool. TrueNAS wipes the data on the replacement disk as part of the process.
Disk replacement automatically triggers a pool resilver.
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 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.
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/.
For more general information on SLOG disks, see SLOG Devices.
Some SATA devices are limited to one resize per power cycle. Some BIOS can block resize during boot and require a live power cycle.
For best stability and hardware compatibility, offline active SLOG SSDs before resizing for over-provisioning.
If the disk is assigned to an active pool, remove it from the pool. ZFS permits removing and re-adding SLOG disks to an active pool at any time.
SCALE uses the storage disk resize
command to change the size of a device. The SCALE UI does not have a UI function for this command yet.
The storage disk resize
command supports SAS, SATA, SAT (interposer) and NVMe drives. Power cycle SATA drives before a second resize.
Open a shell session using an SSH connection or from the local console.
Enter 6 from the TrueNAS console or enter cli
in the Linux shell and press Enter to access the TrueNAS CLI.
See the CLI Reference Guide for more information.
Enter
storage disk query
to return a table of all disks on the system and locate the row(s) for the disk you want to resize.
Record the identifier, name, and current size of the disk.
Unassigned disks are sometimes renamed when the system restarts. The identifier, in the format ofserial_lunid
, is a static value, which allows you to locate the correct disk to confirm changes after resizing.
Enter
storage disk resize disks={"name":"sda", "size":"16"}
where sda is the name of the disk and 16 is the new size for the disk (in gigabytes).
If no size is specified, it reverts the provision back the full size of the device.
The command returns the job progress completion percentage.
storage disk resize disks={"name":"sda", "size":"16"}
[0%] ...
[100%] ...
Reboot the system.
Wait for the system to come online and then use the TrueNAS CLI to verify that the disk is resized to the correct capacity.
Enter
storage disk get_instance id="{serial_lunid}A1BCDEFG234567H_1234567a1234bc12"
where A1BCDEFG234567H_1234567a1234bc12 is the disk identifier you recorded in step 3.
storage disk get_instance id="{serial_lunid}A1BCDEFG234567H_1234567a1234bc12"
+----------------+------------------------------------------------+
| identifier | {serial_lunid}A1BCDEFG234567H_1234567a1234bc12 |
| name | sds |
| subsystem | scsi |
| number | 16672 |
| serial | A1BCDEFG234567H |
| lunid | 1234567a1234bc12 |
| size | 16013942784 |
| description | |
| transfermode | Auto |
| hddstandby | ALWAYS ON |
| advpowermgmt | DISABLED |
| togglesmart | true |
| smartoptions | |
| expiretime | <null> |
| critical | <null> |
| difference | <null> |
| informational | <null> |
| model | SAMSUNG_MZ7KM240HAGR-0E005 |
| rotationrate | <null> |
| type | SSD |
| zfs_guid | 3102327624417314756 |
| bus | ATA |
| devname | sds |
| enclosure | <dict> |
| supports_smart | <null> |
| pool | <null> |
+----------------+------------------------------------------------+
Confirm the target disk reports the updated size. Check if the reported name has changed. If so, record the new name.
Create a new pool or locate an existing pool on the Storage Dashboard and (re)assign the SLOG device to bring it online.
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:~ #
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. Consider the following:
Security requirements can mean the pool must be created with ZFS encryption.
RAIDz pool layouts are well-suited for general use cases and especially smaller (<10) data VDEVS or storage scenarios that involve storing multitudes of small data blocks.
dRAID pool layouts are useful in specific situations where large disk count (>100) arrays need improved resilver times due to increased disk failure rates and the array is intended to store large data blocks.
TrueNAS recommends defaulting to a RAIDz layout generally and whenever a dRAID vdev would have fewer than 10 data storage devices.
Determining your specific storage requirements is a critical step before creating a pool. The ZFS and dRAID primers provide a starting point to learn about the strengths and costs of different storage pool layouts. You can also use the ZFS Capacity Calculator and ZFS Capacity Graph to compare configuration options.
Click Create Pool to open the Pool Creation Wizard.
Enter a name of up to 50 lowercase alpha-numeric characters. Use only the permitted special characters that conform to ZFS naming conventions. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
You cannot change the pool name after creation.
Create the required data VDEV.
Select the layout from the Layout dropdown list, then either use the Automated Disk Selection fields to select and add the disks, or click Manual Disk Selection to add specific disks to the chosen Layout.
dRAID layouts do not show the Manual Disk Selection button but do show additional Automated Disk Selection fields. When configuring a dRAID data VDEV, first choose a Disk Size then select a Data Devices number. The remaining fields update based on the Data Devices and dRAID layout selections.
Click Save And Go To Review if you do not want to add other VDEV types to the pool, or click Next to move to the next wizard screens.
Add any other optional VDEVs as determined by your specific storage redundancy and performance requirements.
Click Create Pool on the Review wizard screen to add the pool.
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 the Storage Dashboard and click Create Pool.
A pool must always have one normal (non-dedup/special) VDEV before you assign other devices to the special class.
Enter a name for the pool using up to 50 lowercase alpha-numeric and permitted special characters that conform to ZFS naming conventions. The pool name contributes to the maximum character length for datasets, so it is limited to 50 characters.
Click ADD VDEV and select Metadata to add the VDEV to the pool layout.
Add disks to the primary Data VDevs, then to the Metadata VDEV.
Add SSDs to the new Metadata VDev and select the same layout as the Data VDevs.
Metadata VDEVs are critical for pool operation and data integrity. Protect them with redundancy measures such as mirroring, and optionally hot spare(s) for additional fault tolerance. It is suggested to use an equal or greater level of failure tolerance in each of your metadata VDEVs; for example, if your data VDEVs are configured as RAIDZ2, consider the use of 3-way mirrors for your metadata VDEVs.
Using special VDEVs identical to the data VDEVs (so they can use the same hot spares) is recommended, but for performance reasons, you can make a different type of VDEV (like a mirror of SSDs). In that case, you must provide hot spare(s) for that drive type as well. Otherwise, if the special VDEV fails and there is no redundancy, the pool becomes corrupted and prevents access to stored data.
While the metadata VDEV can be adjusted after its addition by attaching or detaching drives, the entire metadata VDEV itself can only be removed from the pool when the pool data VDEVs are mirrors. If the pool uses RAIDZ data VDEVs, a metadata VDEV is a permanent addition to the pool and cannot be removed.
When more than one metadata VDEV is created, then allocations are load-balanced between all these devices. If the special class becomes full, then allocations spill back into the normal class. Deduplication table data is placed first onto a dedicated Dedup VDEV, then a Metadata VDEV, and finally the data VDEVs if neither exists.
Create a fusion pool and Status shows a Special section with the metadata SSDs.
The Storage Dashboard widgets provide access to pool management options to keep the pool and disks healthy, upgrade pools and VDEVs, open datasets, snapshots, data protection screens, and manage S.M.A.R.T. tests. This article provides instructions on pool management functions available in the SCALE UI.
Select Storage on the main navigation panel to open the Storage Dashboard. Locate the ZFS Health widget for the pool, then click the Edit Auto TRIM. The Pool Options for poolname dialog opens.
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.
Use the Export/Disconnect button to disconnect a pool and transfer drives to a new system where you can import the pool. It also lets you completely delete the pool and any data stored on it.
Click on Export/Disconnect on the Storage Dashboard.
A dialog displays showing any system services affected by exporting the pool, and options based on services configured on the system.
To delete the pool and erase all the data on the pool, select Destroy data on this pool. The pool name field displays at the bottom of the window. Type the pool name into this field. To export the pool, do not select this option.
Select Delete saved configurations from TrueNAS? to delete shares and saved configurations on this pool.
Select Confirm Export/Disconnect
Click Export/Disconnect. A confirmation dialog displays when the export/disconnect completes.
ZFS supports adding VDEVs to an existing ZFS pool to increase the capacity or performance 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 to open the Add Vdevs to Pool screen.
Adding a vdev to an existing pool follows the same process as documented in Create Pool. Click on the type of vdev you want to add, for example, to add a spare, click on Spare to show the vdev spare options.
To use the automated option, select the disk size from the Automated Disk Selection > Disk Size dropdown list, then select the number of vdevs to add from the Width dropdown. To add the vdev manually, click Manual Disk Selection to open the Manual Selection screen.
Click Add to show the vdev options available for the vdev type. The example image shows adding a stripe vdev for the spare. Vdev options are limited by the number of available disks in your system and the configuration of any existing vdevs of that type in the pool. Drag the disk icon to the stripe vdev, then click Save Selection.
The Manual Selection screen closes and returns to the Add Vdev to Pool wizard screen (in this case the Spare option.)
You have the option to accept the change or click Edit Manual Disk Selection to change the disk added to the strip vdev for the spare, or click Reset Step to clear the strip vdev from the spare completely. Click either Next or a numbered item to add another type of vdev to this pool.
Repeat the same process above for each type of vdev to add.
Click Save and Go to Review to go to the Review screen when ready to save your changes.
To make changes, click either Back or the vdev option (i.e., Log, Cache, etc.) to return to the settings for that vdev. To clear all changes, click Start Over. Select Confirm then click Start Over to clear all changes.
To save changes click Update Pool.
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 of the same type as existing VDEVs. For example, create another mirror, then stripe the new mirror VDEV to the existing mirror VDEV. While on the Devices screen, click on the data vdev, then click Extend.
You can always remove the L2ARC (cache) and SLOG (log) VDEVs from an existing pool, regardless of topology or VDEV type. Removing these devices does not impact data integrity, but can significantly impact performance for reads and writes.
In addition, you can remove a data VDEV from an existing pool under specific circumstances. This process preserves data integrity but has multiple requirements:
device_removal
feature flag.
The system shows the Upgrade button after upgrading SCALE when new ZFS feature flags are available.ashift
).When a RAIDZ data VDEV is present, it is generally not possible to remove a device.
To remove a VDEV from a pool:
The VDEV removal process status shows in the Task Manager (or alternately with the zpool status
command).
Avoid physically removing or attempting to wipe the disks until the removal operation completes.
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 recurring 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.
Manage Devices 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.
Storage pool upgrades are typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Do not do a pool-wide ZFS upgrade until you are ready to commit to this SCALE major version and lose the ability to roll back to an earlier major version!
The Upgrade button displays on the Storage Dashboard for existing pools after an upgrade to a new TrueNAS major version that includes new OpenZFS feature flags. Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS version.
The upgrade itself only takes a few seconds and is non-disruptive. It is not necessary to stop any sharing services to upgrade the pool. However, the best practice is to upgrade when the pool is not in heavy use. The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
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, and child datasets, and have individual permissions or flags.
Datasets can also be encrypted. TrueNAS automatically encrypts datasets created in encrypted pools, but you can change the encryption type from key to passphrase. You can create an encrypted dataset if the pool is not encrypted and set the type as either key or passphrase.
We recommend organizing your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.
To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select the Dataset Preset option you want to use. Options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but this dataset is not used for application data storage. If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting is found under Advanced Options and is not editable after saving the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.
Compression encodes information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of saved space.
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 while adding datasets using the quota management options in the Add Dataset screen under Advanced Options. You can also add or edit quotas for an existing dataset, by clicking Edit on the Dataset Space Management widget to open the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset. You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space. You can configure quotas for only the new dataset or both the new dataset and any child datasets of the new dataset.
Define the maximum allowed space for the dataset in either the Quota for this dataset or Quota for this dataset and all children field. Enter 0 to disable quotas.
Dataset quota alerts are based on the percentage of storage used. To set up a quota warning alert, enter a percentage value in Quota warning alert at, %. When consumed space reaches the defined percentage it sends the alert. To change the setting from the parent dataset warning level, clear the Inherit checkbox and then change the value.
To set up the quota critical level alerts, enter the percentage value in Quota critical alert at, %. Clear the Inherit checkbox to change this value to something other than using the parent alert setting.
When setting quotas or changing the alert percentages for both the parent dataset and all child datasets, use the fields under This Dataset and Child Datasets.
Enter a value in Reserved space for this dataset to set aside additional space for datasets that contain logs, which could eventually take all available free space. Enter 0 for unlimited.
For more information on quotas, see Managing User or Group Quotas.
By default, many dataset options inherit their values from the parent dataset. When settings on the Advanced Options screen are set toInherit the dataset uses the setting from the parent dataset. For example, the Encryption or ACL Type settings.
To change any setting that datasets inherit from the parent, select an available option other than Inherit.
For information on ACL settings see Setting Up Permissions.
First, add the pool with a Metadata VDEV.
Select the root dataset of the pool (with the metadata VDEV), then click Add Dataset to add the dataset. Click Advanced Options. Enter the dataset name, select the Dataset Preset, then scroll down to Metadata (Special) Small Block Size setting to set a threshold block size for including small file blocks into the special allocation class (fusion pools).
Blocks smaller than or equal to this value are assigned to the special allocation class while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. The default size 0 means no small file blocks are allocated in the special class. Enter a threshold block size for including small file blocks into the special allocation class (fusion pools).
After creating a dataset, users can manage additional options from the Datasets screen. Select the dataset, then click Edit on the dataset widget for the function you want to manage. The Datasets Screen article describes each option in detail.
Select the dataset on the tree table, then click Edit on the Dataset Details widget to open the Edit Dataset screen and change the dataset configuration settings. You can change all settings except Name, Case Sensitivity, or Device Preset.
To edit the dataset ACL permissions, click Edit on the Permissions widget. If the ACL type is NFSv4, the Permissions widget shows ACE entries for the dataset. Each entry opens a checklist of flag options you can select/deselect without opening the Edit ACL screen. To modify ownership, configure new or change existing ACL entries, click Edit to open the ACL Editor screen.
To edit a POSIX ACL type, click Edit on the Permissions widget to open the Unix Permissions Editor screen. To access the Edit ACL screen for POSIX ACLs, select Create a custom ACL on the Select a preset ACL window.
For more information, see the Setting Up Permissions article.
Select the dataset on the tree table, then click Delete on the Dataset Details widget. This opens a delete window where you enter the dataset path (root/parent/child) and select Confirm to delete the dataset, all stored data, and any snapshots from TrueNAS.
To delete a root dataset, use the Export/Disconnect option on the Storage Dashboard screen to delete the pool.
Deleting datasets can result in unrecoverable data loss! Move any critical data stored on the dataset off to a backup copy or obsolete the data before performing the delete operation.
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, go to Datasets. Select the root or non-root parent dataset where you want to add the zvol, and then click Add Zvol.
To create a basic zvol with default options, enter a name and a value in Size for the zvol, then click Save.
Options to manage a zvol are on the zvol widgets shown on the Dataset screen when you select the zvol on the dataset tree table.
Delete Zvol removes the zvol from TrueNAS. Deleting a zvol also deletes all snapshots of that zvol. Click Delete on the Zvol Details widget.
Deleting zvols can result in unrecoverable data loss! Remove critical data from the zvol or verify it is obsolete before deleting a zvol.
Edit on the Zvol Details widget opens the Edit Zvol screen where you can change settings. Name is read-only and you cannot change it.
To create a snapshot, click Create Snapshot on the Data Protection widget.
To clone a zvol from an existing snapshot, select the zvol on the Datasets tree table, then click Manage Snapshots on the Data Protection widget to open the Snapshots screen. You can also access the Snapshots screen from the Periodic Snapshot Tasks widget on the Data Protection screen. Click Snapshots to open the Snapshots screen.
Click on the snapshot you want to clone, then click Clone to New Dataset. Enter a name for the new dataset or accept the one provided, then click Clone.
The cloned zvol displays on the Datasets screen.
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 that is properly connected to TrueNAS. Begin typing a user name to filter all users on the system to find the desired user, then click on the user to add the name. Add additional users by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual user quotas, click anywhere on a user row to open the Edit User Quota screen where you can edit the User Data Quota and User Object Quota values.
User Data Quota is the amount of disk space that selected users can use. User Object Quota is the number of objects selected users can own.
Click Add to open the Add Group Quota screen.
Click in the Group field to view a list of system groups on the system. Begin typing a name to filter all groups on the system to find the desired group, then click on the group to add the name. Add additional groups by repeating the same process. A warning dialog displays if there are no matches found.
To edit individual group quotas, click anywhere on a group name to open the Edit Group Quota screen where you can edit the Group Data Quota and Group Object Quota values.
Group Data Quota is the amount of disk space that the selected group can use. Group Object Quota is the number of objects the selected group can own.
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 to snapshot, then click Create Snapshot on the Data Protection widget.
If you click Create Snapshot the Snapshots screen opens filtered for the selected dataset. Clear the dataset from the search field to see all snapshots.
You can also click the Manage Snapshots link on the Data Protection widget to open the Snapshots screen.
Click Add at the top right of the screen to open the Add Snapshot screen.
Select a dataset or zvol from the Dataset dropdown list.
Accept the name suggested by the TrueNAS software in the Name field or enter any custom string to override the suggested name.
(Optional) Select an option from the Naming Schema dropdown list that the TrueNAS software populated with existing periodic snapshot task schemas. If you select an option, TrueNAS generates a name for the snapshot using that naming schema from the selected periodic snapshot and replicates that snapshot.
You cannot enter a value in both Naming Schema and in Name as selecting or entering a value in Naming Schema populates the other field.
(Optional) Select Recursive to include child datasets with the snapshot.
Click Save to create the snapshot.
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 the top to narrow the selection. Clear the search bar to list all snapshots.
Click
to view snapshot options.Use the Clone to New Dataset button to create a clone of the snapshot. The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen. Click Clone to New Dataset to open a clone confirmation dialog.
Click Clone to confirm.
The Go to Datasets button opens the Datasets screen.
Click on the clone name in the dataset listing to populate the Dataset Details widget and display the Promote button.
After clicking the Promote button, the dataset clone is promoted and this button no longer appears.
Promote now displays on the Dataset Details widget when you select the demoted parent dataset.
See zfs-promote.8 for more information.
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 to the point in time saved by the snapshot.
Rollback is a dangerous operation that causes any configured replication tasks to fail. Replications use the existing snapshot when doing an incremental backup, and rolling back can put the snapshots out of order.
A less disruptive method to restore data from a point in time is to clone a specific snapshot as a new dataset:
- Clone the desired snapshot.
- Share the clone with the share type or service running on the TrueNAS system.
- Allow users to recover their needed data.
- Delete the clone from Datasets.
This approach does not destroy any on-disk data or disrupt automated replication tasks.
TrueNAS asks for confirmation before rolling back to the chosen snapshot state. Select the radio button for how you want the rollback to operate.
Click Confirm to activate the Rollback button.
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 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.
From the Datasets screen, select the dataset and click Edit on the Dataset Details widget. Click Advanced Options and set Snapshot Directory to Visible.
To access snapshots:
Using a share, configure the client system to view hidden files.
For example, in a Windows SMB share, enable Show hidden files, folders, and drives in Folder Options.
From to the dataset root folder, open the
Using the TrueNAS SCALE CLI, enter storage filesystem listdir path="/PATH/TO/DATASET/.zfs/PATH/TO/SNAPSHOT"
to view snapshot contents.
See also storage filesystem
.
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 through the Encryption option on the Pool Creation Wizard screen when you create the pool. Because encryption is inherited from the parent, all 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.
You cannot create an unencrypted dataset within an encrypted pool or dataset. This change does not affect existing datasets created in earlier releases of SCALE but does affect new datasets created in 22.12.3 and later releases.
Leave the Encryption option on the Pool Creation Wizard screen cleared to create an unencrypted pool. You can create both unencrypted and encrypted datasets within an unencrypted pool (root dataset). If you create an encrypted dataset within an unencrypted dataset, all datasets 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.
SCALE uses lock icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen. Each icon shows a text label with the state of the dataset when you hover the mouse over the icon.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon | State | Description |
---|---|---|
Locked | Displays for locked encrypted root, non-root parent and child datasets. | |
Unlocked | Displays for unlocked encrypted root, non-root parent and child datasets. | |
Locked by ancestor | Displays for locked datasets that inherit encryption properties from the parent. | |
Unlocked by ancestor | Displays for unlocked datasets that inherit encryption properties from the parent. |
A dataset that inherits encryption shows the mouse hover-over label Locked by ancestor or Unlocked by ancestor.
Select an encrypted dataset to see the ZFS Encryption widget on the Datasets screen.
The dataset encryption state is unlocked until you lock it using the Lock button on the ZFS Encryption widget. After locking the dataset, the icon on the tree table changes to locked, and the Unlock button appears on the ZFS Encryption widget.
Before creating a pool with encryption decide if you want to encrypt all datasets, zvols, 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. Instead, apply encryption at the dataset level to non-root parent or child datasets.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 to open the Pool Creation Wizard.
Enter a name for the pool, select Encryption next to Name, then select the layout for the data VDEV and add the disks. A warning dialog displays after selecting Encryption.
Read the warning, select Confirm, and then click I UNDERSTAND.
A second dialog opens where you click Download Encryption Key for the pool encryption key.
Click Done to close the window. Move the encryption key to safe location where you can back up the file.
Add any other VDEVS to the pool you want to include, then click Save to create the pool with encryption.
To add an encrypted dataset, go to Datasets.
Select dataset on the tree table where you want to add a new dataset. The default dataset selected when you open the Datasets screen is the root dataset of the first pool on the tree table list. If you have more than one pool and want to create a dataset in a pool other than the default, select the root dataset for that pool or any dataset under the root where you want to add the new dataset.
Click Add Dataset to open the Add Dataset screen, then click Advanced Options.
Enter a value in Name.
Select the Dataset Preset option you want to use. Options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
To add encryption to a dataset, scroll down to Encryption Options and select the inherit checkbox to clear the checkmark. If the parent dataset is unencrypted and you want to encrypt the dataset, clear the checkmark to show the Encryption option. If the parent dataset is encrypted and you want to change the type, clearing the checkmark shows the other encryption options. To keep the dataset encryption settings from the parent, leave inherited checkmarked.
Decide if you want to use the default key type encryption and if you want to let the system generate the encryption key. To use key encryption and your 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 to 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 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.
If the encryption type is set to passphrase, you can change the passphrase, or change Encryption Type to key. You cannot change a dataset created with a key as the encryption type to passphrase.
Key type options are Generate Key (pre-selected) or clear to display the Key field. Enter your new key in this field.
To change the passphrase for passphrase-encryption, enter a new passphrase in Passphrase and Confirm Passphrase.
Use a complex passphrase that is not easy to guess. Store in a secure location subject to regular backups.
Leave the other settings at default, then click Confirm to activate Save.
Click Save to close the window and update the ZFS Encryption widget 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 encrypted 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 locked dataset on the tree table. Click Unlock on the ZFS Encryption widget to open the Unlock Dataset screen.
Enter the key if key-encrypted, or the passphrase into Dataset Passphrase and click Save.
Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.
Select Force if the dataset mount path exists but is not empty. 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 encrypt 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, go to Datasets and click on the Zvol.
If you do not see the ZFS Encryption widget, you created the Zvol from an unencrypted dataset. Delete the Zvol and start over.
The Zvol is encrypted with settings inherited from the parent dataset.
To change inherited encryption properties from passphrase to key, or enter a new key or passphrase, select the zvol, then click Edit on the ZFS Encryption widget.
If Encryption Type is set to Key, type an encryption key into the Key field or select Generate Key. If using Passphrase, enter a passphrase of eight to 512 characters. Use a passphrase complex enough 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.
To manually back up a root dataset key file, click Export Key on the ZFS Encryption widget.Always back up the key file to a safe and secure location.
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. A passphrase is a user-defined string of eight to 512 characters that is required to decrypt the dataset. The pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Users must enter a number greater than 100000.
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 and shares.
An Access Control List (ACL) is a set of account permissions associated with a dataset that applies to directories or files within that dataset. TrueNAS uses ACLs to manage user interactions with shared datasets and creates them when users add a dataset to a pool.
TrueNAS SCALE offers two ACL types: POSIX and NFSv4. For a more in-depth explanation of ACLs and configurations in TrueNAS SCALE, see our ACL Primer.
The Dataset Preset setting on the Add Dataset screen determines the type of ACL for the dataset. To see the ACL type, click Edit on the Dataset Details widget to open the Edit Dataset. Click on the Advanced Options screen and scroll down to the ACL Type field. Preset options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
SCALE POSIX or NFSv4 ACL types, show different options on the ACL Editor screen. Both the POSIX and NFSv4 ACL Editors screens allow you to define the owner user and group, and add ACL entries (ACEs) for individual user accounts or groups to customize the permissions for the selected dataset.
The owner user and group should remain set to either root or the admin account with full privileges.
Add ACE items for other users, groups, directories, or other options to grant access permissions to the dataset. Click in the Who field and select the item (like User or Group) and to display the User or Group fields where you select the user or group accounts.
Basic ACL permissions are viewable and configurable from the Datasets screen. Select a dataset, then scroll down to the Permissions widget to view owner and individual ACL entry permissions.
To view the Edit ACL screen, either select the dataset and click Edit on the Permissions widget or go to Sharing and click on the share widget header to open the list of shares. Select the share, then click the options icon and select Edit Filesystem ACL.
You can view permissions for any dataset, but the edit option only displays on the Permissions widget for non-root datasets.
Configuring advanced permissions overrides basic permissions configured on the add and edit dataset screens.
Select a non-root dataset, scroll down to the Permissions widget, then click Edit to open the Unix Permissions Editor screen.
If the dataset has an NFSv4 ACL, the Edit ACL screen opens.
Enter or select the Owner user from the User dropdown list, then set the read/write/execute permissions, and select Apply User to confirm changes. User options include users created manually or imported from a directory service. Repeat for the Group field. Select the group name from the dropdown list, set the read/write/execute permissions, and then select Apply Group to confirm the changes.
To prevent errors, TrueNAS only submits changes after the apply option is selected.
A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets. A common misconfiguration is not adding or removing the Execute permission from a dataset that is a parent to other child datasets. Removing this permission results in lost access to the path.
To apply ACL settings to all child datasets, select Apply permissions recursively.
Change the default settings to your preferred primary account and group and select Apply permissions recursively before saving any changes.
Click Save now if you do not want to use an ACL preset.
See Edit ACL Screen for information on the ACL editor screens and setting options.
From the Unix Permissions Editor screen:
Click Set ACL. The Select a preset ACL dialog opens.
Select Select a present ACL to use a pre-configured set of permissions. Select the preset 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. Enter the ACL owner user and group, and add new ACE for users, groups, etc. that you want to grant access permissions to for this dataset
Select or enter the administrative user name in Owner, then click Apply Owner. The owner controls which TrueNAS user and group has full control of the dataset.
You can leave this set to root but we recommend changing this to the admin user with the Full Control role.
Repeat for the Owner Group, then click Apply Group.
Select the ACE entry on the Access Control List list on the left of the screen just below Owner and Owner Group. If adding a new entry, click Add Item.
Click in Who and select the value from the dropdown list.
If selecting User, the User field displays below the Who field. Same for Group.
Select a name from the dropdown list of options in the User (or Group) field or begin typing the name to see a narrowed list of options to select from.
Select the Read, Modify, and/or Execute permissions.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets.
(Optional) Click Use Preset to display the ACL presets window and select a predefined set of permission from the list of presets. See Using Preset ACL Entries (POSIX ACL) for the list of presets.
Click Save as Preset to add this to the list of ACL presets. Click Save Access Control List to save the changes made to the ACL.
An NFS4 ACL preset loads pre-configured permissions to match general permissions situations.
Changing the ACL type affects how TrueNAS writes and reads on-disk ZFS ACL.
When the ACL type changes from NFSv4 to POSIX, native ZFS ACLs do not convert to posix1e extended attributes, but ZFS usea the native ACL for access checks.
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.
To change NFSv4 ACL permissions:
Go to Datasets, select the dataset, scroll down to the Permissions widget, and click Edit. The Edit ACL screen opens.
Select or enter the administrative user name in Owner, then click Apply Owner. The owner controls which TrueNAS user and group has full control of the dataset. You can leave this set to root but we recommend changing the owner user and group to the admin user with the Full Control role.
Select or enter the group name in Owner Group, then click Apply Group.
Select the ACE entry on the Access Control List list on the left of the screen below Owner and Owner Group. If adding a new entry, click Add Item.
Click on Who and select the value from the dropdown list. If selecting User, the User field displays below the Who field. Same for Group. Select a name from the dropdown list of options or begin typing the name to see a narrowed list of options to select from. The selection in Who highlights the Access Control List entry on the left side of the screen.
Select permission type from the Permissions dropdown list. If Basic is selected, the list displays four options: Read, Modify, Traverse and Full Control. Basic flags enable or disable ACE inheritance.
Select Advanced to select more granular controls from the options displayed. Advanced flags allow further control of how the ACE applies to files and directories in the dataset.
(Optional) Select Apply permissions recursively, below the list of access control entries, to apply this preset to all child datasets. This is not generally recommended as recursive changes often cause permissions issues (see the warning at the top of this section).
(Optional) Click Use Preset to display the ACL presets window to select a predefined set of permissions from the list of presets. See Using Preset ACL Entries (NFS ACL).
(Optional) Click Save as Preset to add this to the list of ACL presets.
Click Save Access Control List to save the changes for the user or group selected.
To rewrite the current ACL with a standardized preset, follow the steps above in Configuring an ACL to step 6 where you click Use Preset, and then select an option:
Click Save Access Control List to add this ACE entry to the Access Control List.
If the file system uses a POSIX ACL, the first option presented is to select an existing preset or the option to create a custom preset.
To rewrite the current ACL with a standardized preset, click Use Preset and then select an option:
If creating a custom preset, a POSIX-based Edit ACL screen opens. Follow the steps in Adding a New Preset (POSIX ACL) to set the owner and owner group, then the ACL entries (user, group) and permissions from the options shown.
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares.
TrueNAS SCALE allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
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.
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS EnterpriseTrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores. This is all managed through the vCenter web interface.
TrueNAS CORE web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS SCALE web interface: TrueNAS SCALE offers a similar experience to TrueNAS CORE for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
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.
SCALE has implemented administrator roles to further comply with FIPS security hardening standards. The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and to start/restart the sharing service, but does not permit the user to modify users to grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
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.
When adding an iSCSI share the system prompts you to start, or restart, the service. You can also do this by clicking the
on the Block (iSCSI) Shares Targets widget and selecting 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.
Go to Shares and click Configure in the Block (iSCSI) Shares Targets screen, then select the Extents tab.
Click the more_vert next to the file-based LUN and select Edit.
Enter a new size in Filesize. Enter the new value as an integer that is one or more multiples of the logical block size (default 512) larger than the current file size. Click Save.
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.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
SCALE has implemented administrator roles to further comply with FIPS security hardening standards. The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and to start/restart the sharing service, but does not permit the user to modify users to grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
If creating a dataset and share from the Add Dataset screen, we recommend creating a new dataset with the Dataset Preset set to Generic for the new NFS share. Or you can set it to **Multiprotocol"" and select only the NFS share type.
To create the share and dataset from the Add NFS Share screen:
Go to Shares > Unix (NFS) Shares and click Add to open the Add NFS Share configuration screen.
Enter the path or use the
icon to the left of /mnt to locate the dataset and populate the path.Click Create Dataset, enter a name for the dataset and click Create. The system creates the dataset optimized for an NFS share, and populates the share Name and updates the Path with the dataset name. The dataset name is the share name.
Enter text to help identify the share in Description.
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 Networks. Enter an IP address in Network and select the mask CIDR notation. Click Add for each network address and CIDR you want to define as an authorized network. Defining an authorized network restricts access to all other networks. Leave empty to allow all networks.
If you want to enter allowed systems, click Add to the right of 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, but you cannot create a new dataset.
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.
You can configure the NFS service from either the System Settings > Services or the Shares > Unix Shares (NFS) widget.
To configure NFS service settings from the Services screen, click edit on the System Settings > Services screen to open the NFS service screen.
To configure NFS service settings from the Shares > Unix Shares (NFS) widget, click the Config Service from the
dropdown menu on the widget header to open the NFS service screen. Unless you need specific settings, we recommend using the default NFS settings.When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
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.
A multiprotocol or mixed-mode NFS and SMB share supports both NFS and SMB protocols for sharing data. Multiprotocol shares allow clients to use either protocol to access the same data. This can be useful in environments with a mix of Windows systems and Unix-like systems, especially if some clients lack an SMB client.
Carefully consider your environment and access requirements before configuring a multiprotocol share. For many applications, a single protocol SMB share provides better user experience and ease of administration. Linux clients can access SMB shares usingmount.cifs
.
It is important to properly configure permissions and access controls to ensure security and data integrity when using mixed-mode sharing. To maximize security on the NFS side of the multiprotocol share, we recommend using NFSv4 and Active Directory(AD) for Kerberos authentication. It is also important that NFS clients preserve extended attributes when copying files, or SMB metadata could be discarded in the copy.
Before adding a multiprotocol SMB and NFS share to your system:
Configure and start the SMB and NFS services. Configure the NFS service to require Kerberos authentication.
Join the TrueNAS server to an existing Active Directory domain. Configure a container, Kerberos admin, and user accounts in AD.
Create the dataset and share with Dataset Preset set to Multiprotocol.
Before joining AD and creating a dataset for the share to use, start both the SMB and NFS services and configure the NFS service for Kerberos authentication. Configure the NFS service before joining AD for simpler Kerberos credential creation.
You can either use theShares screen Configure Service option on both the Windows (SMB) Share and on the UNIX (NFS) Shares widgets, or go to System Settings > Services and select the Edit option on the SMB and NFS services.
Unless you need a specific setting or are configuring a unique network environment, we recommend using the default SMB service settings.
After configuring the share services, start the 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.After adding a share, use the toggle to enable or disable the service for that share.
To enable the service from the System Settings > Services screen, click the toggle for the service and set Start Automatically if you want the service to activate when TrueNAS boots.
Open the NFS service screen, then select only NFSv4 on the Enabled Protocols dropdown list. For security hardening, we recommend disabling the NFSv3 protocol.
Select Require Kerberos for NFSv4 to enable using a Kerberos ticket.
If Active Directory is already joined to the TrueNAS server, click Save and then reopen the NFS service screen. Click Add SPN to open the Add Kerberos SPN Entry dialog.
Click Yes when prompted to add a Service Principal Name (SPN) entry. Enter the AD domain administrator user name and password in Name and Password.
TrueNAS SCALE automatically applies SPN credentials if the NFS service is enabled with Require Kerberos for NFSv4 selected before joining Active Directory.
Click Save again, then start the NFS service.
From the Sharing screen, click on the Unix Shares (NFS)
to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.Each NFS share on the list also has a toggle to enable or disable the service for that share.
To enable the service from the System Settings > Services screen, click the toggle for the service and set Start Automatically if you want the service to activate when TrueNAS boots.
The NFS service does not automatically start on boot if all NFS shares are encrypted and locked.
Mixed-mode SMB and NFS shares greatly simplify data access for client running a range of operating systems. They also require careful attention to security complexities not present in standard SMB shares. NFS shares do not respect permissions set in the SMB Share ACL. Protect the NFS export with proper authentication and authorization controls to prevent unauthorized access by NFS clients.
We recommend using Active Directory to enable Kerberos security for the NFS share. Configure a container (group or organizational unit), Kerberos admin, and user accounts in AD.
You can create the dataset and add a multiprotocol (SMB and NFS) share using the Add Dataset screen.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
Select the dataset you want to be the parent of the multimode dataset, then click Add Dataset.
Enter a name for the dataset. The dataset name populates the SMB Name field and becomes the name of the SMB and NFS shares.
Select Multiprotocol from the Dataset Preset dropdown. The share configuration options display with Create NFS Share and Create SMB Share preselected.
(Optional) Click Advanced Options to customize other dataset settings such as quotas, compression level, encryption, and case sensitivity. See Creating Datasets for more information on adding and customizing datasets.
Click Save. TrueNAS creates the dataset and the SMB and NFS shares. Next edit both shares. After editing the shares, edit the dataset ACL.
After creating the multimode share on the Add Dataset screen, go to Shares and edit the SMB share.
Select the share on the Windows Shares (SMB) widget and then click Edit. The Edit SMB screen opens showing the Basic Options settings.
Select Multi-protocol (NFSv4/SMB) shares from the Purpose dropdown list to apply pre-determined Advanced Options settings for the share.
(Optional) Enter a Description to help explain the share purpose.
Click Save.
Restart the service when prompted.
After creating the multimode share on the Add Dataset screen, go to Shares and edit the NFS share.
Select the new share listed on Unix (NFS) Shares widget and then click Edit. The Edit NFS screen opens showing the Basic Options settings.
Enable Kereberos security. Click Advanced Options. Select KRB5 from the Security dropdown to enable the Kerberos ticket that generated when you joined Active Directory.
If needed, select Read-Only to prohibit writing to the share.
Click Save.
Restart the service when prompted.
After joining AD, creating a multimode dataset and the SMB and NFS shares, adjust the dataset/file system ACL to match the container and users configured in AD.
You can modify dataset permissions from the Shares screen using the Edit ACL screen for each share (SMB and NFS). Using this method you select the share on the Windows (SMB) Share widget, then click the icon to edit the dataset properties for the SMB share, but you must repeat this for the NFS share.
Edit Filesystem ACL icon to open theOr you can go to Datasets, select the name of the dataset created for the multiprotocol share to use and scroll down to the Permissions widget for the dataset. Click Edit to open the Edit ACL screen.
Check the Access Control List to see if the AD group you created is on the list and has the correct permissions. If not, add this Access Control Entry (ACE) item on the Edit ACL screen for the multimode dataset (or each share).
Enter Group in the Who field or use the dropdown list to select Group.
Type or select the appropriate group in the Group field.
Verify Full Control displays in Permissions. If not, select it from the dropdown list.
Click Save Access Control List to add the ACE item or save changes.
See Permissions for more information on editing dataset permissions.
After setting the dataset permission, connect to the share.
After creating and configuring the shares, connect to the mulit-protocol share using either SMB or NFS protocols from a variety of client operating systems including Windows, Apple, FreeBSD, and Linux/Unix systems.
For more information on accessing shares, see Mounting the SMB Share and Connecting to the NFS 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.
SCALE has implemented administrator roles to further comply with FIPS security hardening standards. The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and to start/restart the sharing service, but does not permit the user to modify users to grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Creating an SMB share to your system involves several steps to add the share and get it working.
Create the SMB share user account. You can also use directory services like Active Directory or LDAP to provide additional user accounts. If setting up an external SMB share, we recommend using Active Directory or LDAP, or at a minimum synchronizing the user accounts between systems.
Create the SMB share and dataset. 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.
You can create the dataset and share on the Add Dataset screen or create the share and dataset on the Add SMB Share screen. The procedure in this article provides the instructions to add the dataset while adding the share.
Modify the share permissions. After adding or modifying the user account for the share, edit the dataset permissions.
After adding the share, start the service and mount it to your other system.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled. You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To add users or edit users, go to Credentials > Local Users to add or edit the SMB share user(s). Click Add to create a new or as many new user accounts as you need.
Enter the values in each required field, verify Samba Authentication is selected, then click Save. For more information on the fields and adding users, see Creating User Accounts.
By default, all new local users are members of a built-in group called builtin_users. You can use a group to grant access to all local users on the server or add more groups to fine-tune permissions for large numbers of users.
You can create an SMB share while creating a dataset on the Add Dataset screen or create the dataset while creating the share on the Add SMB Share screen. This article covers adding the dataset on the Add SMB Share screen.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
To create a basic Windows SMB share and a dataset, go to Shares and click Add on the Windows Shares (SMB) widget to open the Add Share screen.
Enter or browse to select SMB share mount path (parent dataset where you want to add a dataset for this share) to populate the Path field. The Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Click Create Dataset. Enter the name for the share dataset in the Create Dataset dialog, then click Create. The system creates the new dataset.
Name becomes the dataset name entered and is the SMB share name. This 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 change the name, follow the naming conventions for:
If creating an external SMB share, enter the hostname or IP address of the system hosting the SMB share and the name of the share on that system. Enter as EXTERNAL:ip address\sharename in Path, then change Name to EXTERNAL with no special characters.
(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 or Default share parameters.
(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.
(Optional) Click Advanced Options to configure audit logging or other advanced configuration settings such as changing Case Sensitivity.
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 under Advanced Options on either the Add SMB or Edit SMB screens. See Managing SMB Shares for more on configuring permissions for the share and the file system.
There are two levels to set SMB share permissions, at the share or for the dataset associated for with the share. See Managing SMB Shares for more information on these options.
See Permissions for more information on dataset permissions.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses. The permissions apply at the SMB share level for the selected share. They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on
Edit Share ACL icon to open the Edit Share ACL screen if you want to modify permissions at the share level.Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option. This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level. To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, either click the «span class=“material-icons”>security> Edit Filesystem ACL icon on the share row to open the Edit ACL screen for the dataset the share uses. You can also go to Datasets, select the dataset the share uses (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS SCALE manually or through a directory service, and these users are automatically added to the builtin-users group. Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default. Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry. Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group. Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Home users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen. Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Enter or select Group in the Who field.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Local Groups, click Add and create the new group.
Go Local Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group. Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL. Add an ACE entry for the new group, and select Traverse. Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
To connect to an SMB share, you must start the related system service.
After adding a new share the system prompts you to either start, or restart the SMB service.
You can also start the service from the Windows (SMB) Share widget or on the System Settings > Services screen from the SMB service row.
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 Config Service from the
dropdown menu on the Windows (SMB) Shares widget header or by clicking edit on the Services screen. Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.The instructions in this section cover mounting the SMB share on a system with the following operating systems.
External SMB shares are essentially redirects to shares on other systems. Administrators might want to use this when managing multiple TrueNAS systems with SMB shares and if they don’t want to keep track of which shares live on which boxes for clients. This feature allows admins to connect to any of the TrueNAS systems with external shares set up and see them all.
Create the SMB share on another SCALE server (for example, system1), as described in Adding an SMB Share above.
We recommend using Active Directory or LDAP when creating user accounts, but at a minimum synchronize user accounts between the system with the share (system1) and on the TrueNAS SCALE system where you set up the external share (for example, system2).
On system2, enter the hostname or IP address of the system hosting the SMB share (system1) and the name given the share on that system as EXTERNAL:ip address\sharename in Path, then change Name to EXTERNAL with no special characters.
Leave Purpose set to Default share parameters, leave Enabled selected, then click Save to add the share redirect.
Repeat the system2 instructions above to add an external redirect (share) on system1 to see the SMB shares of each system.
Repeat for each SCALE system with SMB shares you want added as an external redirect. Change the auto-populated name to EXTERNAL2 or something to distinguish it from the SMB shares on the local system (system1 in this case) and any other external shares added.
These tutorials describe creating and managing various specific configurations of SMB shares.
To access SMB share management options, go to Shares screen with the Windows (SMB) Shares widget. The widget lists SMB shares configured on but is not the full list. Each share listed includes four icons that open other screens or dialogs that provide access to share settings. To see a full list of shares, click on Windows (SMB) Shares
to open the Sharing > SMB screen. Each share row on this screen provides access to the other screens or dialogs with share settings.SCALE has implemented administrator roles to further comply with FIPS security hardening standards. The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and to start/restart the sharing service, but does not permit the user to modify users to grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
To manage an SMB share click the icons on the widget or use the on the Sharing > SMB details screen to see the options for the share you want to manage. Options are:
Edit opens the Edit SMB screen where you can change settings for the share.
Edit Share ACL opens the Share ACL screen where you can add or edit ACL entries.
Edit Filesystem ACL opens the Edit ACL screen where you can edit the dataset permissions for the share. The Dataset Preset option determines the ACL type and therefore the ACL Editor screen that opens.
Delete opens a delete confirmation dialog. Use this to 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:
Edit Share ACL where you modify ACL permissions applying to the entire SMB share.
Edit Filesystem ACL where you modify ACL permissions at the shared dataset level.
See the ACL Primer for general information on Access Control Lists (ACLs) in general, the Permissions article for more details on configuring ACLs, and Edit ACL Screen for more information on the dataset ACL editor screens and setting options.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses. The permissions apply at the SMB share level for the selected share. They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on
Edit Share ACL icon to open the Edit Share ACL screen if you want to modify permissions at the share level.Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option. This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level. To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, either click the «span class=“material-icons”>security> Edit Filesystem ACL icon on the share row to open the Edit ACL screen for the dataset the share uses. You can also go to Datasets, select the dataset the share uses (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS SCALE manually or through a directory service, and these users are automatically added to the builtin-users group. Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default. Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry. Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group. Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Home users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen. Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Enter or select Group in the Who field.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Local Groups, click Add and create the new group.
Go Local Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group. Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL. Add an ACE entry for the new group, and select Traverse. Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
SCALE uses predefined setting options to establish an SMB share that fits a predefined purpose, such as a basic time machine share.
To set up a basic time machine share:
Create the user(s) for this SMB share. Go to Credentials > Local User and click Add.
Create the share and dataset with Purpose set to Basic time machine share.
After creating the share, enable the SMB service.
You can either create the dataset to use for the share on the Add Dataset screen and the share, or create the dataset when you add the share on the Add SMB screen. If you want to customize the dataset, use the Add Dataset screen.
To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select the Dataset Preset option you want to use. Options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but this dataset is not used for application data storage. If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting is found under Advanced Options and is not editable after saving the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.
To use the Add SMB screen, click Add on the Windows (SMB) Shares widget to open the screen.
Set the Path to the existing dataset created for the share, or to where you want to add the dataset, then click Create Dataset.
Enter a name for the dataset and click Create Dataset. The dataset name populates the share Name field and updates the Path automatically. The dataset name becomes the share name. Leave this as the default.
If you change the name follow the naming conventions for:
Set the Purpose to Basic time machine share.
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.
Finish customizing the share, then click Save.
Do not start the SMB service when prompted, start it after configuring the SMB service.
Click on the on the Windows (SMB) Share widget, then click Configure Service to open the SMB Service screen.
You can also go to System Settings > Services and scroll down to SMB. If using the Services screen, 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.
Restart the SMB service.
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 have not 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 locate the share.
If listed on the widget, select the Edit option for the share.
If not listed, click Windows (SMB) Shares
to open the Sharing > SMB list-view screen. Select the share, then click the for the share, then click Edit to open the Edit SMB screen.Click Advanced Options, scroll down to Other Options, and then select Enable Shadow Copies.
Click Save.
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 in the Other Options on the Advanced Options screen for the SMB share.
Disabling does not prevent access to the hidden
TrueNAS offers the Use as Home Share option, found in the Add SMB and Edit SMB screen Advanced Options settings in the Other Options section, for organizations or SMEs that want to use a single SMB share to provide a personal directory to every user account.
With home shares, each user is given a personal home directory when connecting to the share. These home directories are not accessible by other users. You can use only one share as the home share, but you can create as many non-home shares as you need or want.
Creating an SMB home share requires configuring the system storage and joining Active Directory.
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.
You can use Active Directory or LDAP to create share users.
If not already created, add a pool, then join Active Directory.
Go to Storage and create a pool.
Next, set up the Active Directory that you want to share resources with over your network.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled. You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
You can either add the share when you create the dataset for the share on the Add Dataset screen, or create the dataset when you add the share on the Add SMB screen. If you want to customize the dataset, use the Add Dataset screen.
To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
Enter a value in Name.
Select the Dataset Preset option you want to use. Options are:
Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.
SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.
Apps includes an additional entry granting modify control to group 568 (Apps).
If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but this dataset is not used for application data storage. If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.
If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.
Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting is found under Advanced Options and is not editable after saving the dataset.
Click Save.
Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.
To use the Add SMB screen, Click Add on the Windows (SMB) Shares widget to open the screen.
Set the Path to the existing dataset created for the share, or to where you want to add the dataset, then click Create Dataset.
Enter a name for the dataset and click Create Dataset. The dataset name populates the share Name field and updates the Path automatically. The dataset name becomes the share name. Leave this as the default. If you change the name follow the naming conventions for:
Set the Purpose to No presets, then click Advanced Options. Scroll down to Other Options and set Use as Home Share. Click Save.
Enable the SMB service when prompted to make the share is available on your network.
After saving the dataset, set the permissions.
After creating the share and dataset, you can edit permissions using either the Edit option on the Permissions widget for the dataset, or use the Edit Filesystem ACL option for the share on the Windows (SMB) Share widget to open the ACL edit screen for the share dataset. See SMB Shares for more information on editing the share dataset permissions.
Click on the new dataset. Scroll down to the Permissions widget and click Edit.
Click the Owner dropdown and select the owner, the repeat for Group. Change the owning group to your Active Directory domain admins. Select Apply Owner and Apply Group.
Click Use an ACL Preset and choose NFS4_HOME. Then, click Continue.
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.
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. This article provides instructions on adding a cloud sync task, configuring environment variables, running an unscheduled sync task, creating a copy of a task with a reversed transfer mode, and troubleshooting common issues with some cloud storage providers.
TrueNAS can send, receive, or synchronize data with a cloud storage provider. Cloud sync tasks allow for single-time transfers or recurring transfers on a schedule. They are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS 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 must have:
You can create cloud storage account credentials using Credentials > Backup Credentials > Cloud Credentials before adding the sync task or add it when configuring the cloud sync task using Add on the Data Protection > Cloud Sync Task widget to open the Cloudsync Task Wizard. See the Cloud Credentials article for instructions on adding a backup cloud credential.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloudsync Task Wizard opens.
Select an existing backup credential from the Credential dropdown list. If not already added as a cloud credential, click Add New to open the Cloud Credentials screen to add the credential. Click Save to close the screen and return to the wizard.
Click Next to open the Where and When wizard screen.
Select the option from Direction and in Transfer Mode. Select the location where to pull from or push data to in the Folder field.
Select the dataset location in Directory/Files. Browse to the dataset to use on SCALE for data storage. Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
Cloud provider settings change based on the credential you select. Select or enter the required settings that include where files are stored. If shown, select the bucket on the Bucket dropdown list.
Select the time to run the task from the Schedule options.
Click Save to add the task.
Use Dry Run to test the configuration before clicking Save or select the option on the Cloud Sync Task widget after you click Save. TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule.
The option to encrypt data transferred to or from a cloud storage provider is available in the Advanced Options settings.
Select Remote Encryption to use rclone crypt encryption during pull and push transfers. With Pull selected as the Transfer Direction, the Remote Encryption decrypts files stored on the remote system before the transfer. This requires entering the same password used to encrypt data in both Encryption Password and Encryption Salt.
With Push selected as the Transfer Direction, data is encrypted before it is transferred and stored on the remote system. This also requires entering the same password used to encrypt data in both Encryption Password and Encryption Salt.
Filename Encryption is selected by default. When selected, the pull and push transfers encrypt or decrypt file names with the rclone Standard file name encryption mode. The original directory structure of the files is preserved. When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, use sub-paths, and copy single files. When enabled, file names are encrypted, file names are limited to 143 characters, directory structure is visible, and files with identical names have identical uploaded names. File names can use sub-paths, single copy files, and shortcuts to shorten the directory recursion.
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 after deleting those files locally. Instead, files are tagged with a version number or moved to a hidden state. To automatically delete old or unwanted files from the bucket, adjust the Backblaze B2 Lifecycle Rules.
A directory, deleted in BackBlaze B2 and notated with an asterisk, do not display in the SCALE UI. These folders are essentially empty directories and Backblaze API restricts them 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.
Use either the Advanced Options screen accessed from the Cloudsync Task Wizard or Edit Cloud Sync Task screen, scroll down to the Advanced Options to locate and then enter environment variables in either the Pre-script or Post-script fields. The Post-script field only runs when the cloud sync task succeeds.
Saved tasks activate based on the schedule set for the task. Click Run Now on the Cloud Sync Task widget to run the sync task before the saved scheduled time. You can also expand the task on the Cloud Sync Tasks screen and click Run Now on the task details screen.
An in-progress cloud sync must finish before another can begin. Stopping an in-progress task cancels the file transfer and requires starting the file transfer over.
To view logs about a running task, or its most recent run, click on the State oval.
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 Linux 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. Click Log In To Provider. The Google Authentication window opens.
b. Click Proceed to open the Choose an Account window.
c. Select the email account to use. Google displays the Sign In window. Enter the password and click Next to enter the password. Click Next again. Google might display a Verify it’s you window. Enter a phone number where Google can text an verification code, or you can click Try another way.
d. Click Allow on the TrueNAS wants to access your Google Account window. TrueNAS populates Access Token with the token Google provides.
Click Verify Credentials and wait for TrueNAS to display the verification dialog with verified status. Close the dialog.
Click Save. The Cloud Credentials widget displays the new credentials. These are also available for cloud sync tasks to use.
You must add the cloud credential on the Backup Credentials screen before you create the cloud sync task.
To add a cloud sync task, go to Data Protection > Cloud Sync Tasks and click Add. The Cloudsync Task Wizard opens.
Select Google Drive on the Credential dropdown list, then enter your credentials.
Click Next.
Select the direction for the sync task. PULL brings files from the cloud storage provider to the location specified in Directory/Files (this is the location on TrueNAS 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. Click 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. Clearing the Enable checkbox makes the configuration available without allowing the specified schedule to run the task.
To manually activate a saved task, go to Data Protection > Cloud Sync Tasks, click for the cloud sync task you want to run. Click CONTINUE or CANCEL for the Run Now operation.
(Optional) Click Advanced Options to set any advanced option you want or need for your use case or to define environment variables. Scroll down to and enter the variables or scripts in either the Pre-script or Post-script fields. These fields are for advanced users.
Click Dry Run to test your settings before you click Save. TrueNAS connects to the cloud storage provider and simulates a file transfer but does not send or receive data.
The new task displays on the Cloud Sync Tasks widget with the status of PENDING until it runs. If the task completes without issue the status becomes SUCCESS.
See Using Scripting and Environment Variables for more information on environment variables.
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 you incur 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 create the Storj-TrueNAS account, creating a new bucket, and obtaining the S3 authentication credentials you need to complete the process in SCALE.
Create the Storj-TrueNAS account.
You must create a 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.
The instructions in this section covers adding the Storj-iX account and configuring the cloud service credentials in SCALE and Storj. The process includes going to Storj to create a new Storj-iX account and returning to SCALE to enter the S3 credentials provided by Storj.
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 to identify the credential in the Name field.
Click Signup for account to create your Stor-iX 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 the Storj S3 access for the new bucket.
Enter the authentication information provided by 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.
You can create your iX-Storj cloud service account using two methods:
The Storj Create your Storj account web page opens. Enter your information in the fields, select the I agree to the Terms of Service and Privacy Policy, then click the button at the bottom of the screen. The Storj main dashboard opens.
Now you can add the storage bucket you want to use in your Storj-TrueNAS account and 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 lowercase 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 allows you to download the encryption keys. You must keep encryption keys stored in a safe place 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 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. For example, select All for Permissions, then select the one bucket we created ixstorj1.
If you want to use the SCALE option to add new buckets in SCALE, set Storj Permissions 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 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 nor 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 Cloudsync Task Wizard.
Select the Storj credential on the Credential dropdown list, then click Next to show the What and When wizard screen.
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. Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
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!
If Direction is set to PUSH, click on the folder icon for the Folder field to select the desired folder in the Storj bucket from the dropdown list if not copying/moving/syncing the entire contents of the bucket with the dataset selected in the Directory/Files field.
Set the task schedule for when to run this task.
Click Save.
TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule. To test the task, click Dry Run or Run Now to start the task 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 Cloudsync Task Wizard opens.
Select an existing backup credential from the Credential dropdown list. If not already added as a cloud credential, click Add New to open the Cloud Credentials screen to add the credential. Click Save to close the screen and return to the wizard.
Click Next to open the Where and When wizard screen.
Select the option from Direction and in Transfer Mode. Select the location where to pull from or push data to in the Folder field.
Select the dataset location in Directory/Files. Browse to the dataset to use on SCALE for data storage. Click the arrow to the left of the name to expand it, then click on the name to select it.
If Direction is set to PUSH, click on the folder icon to add / to the Folder field.
Cloud provider settings change based on the credential you select. Select or enter the required settings that include where files are stored. If shown, select the bucket on the Bucket dropdown list.
Select the time to run the task from the Schedule options.
Click Save to add the task.
Use Dry Run to test the configuration before clicking Save or select the option on the Cloud Sync Task widget after you click Save. TrueNAS adds the task to the Cloud Sync Task widget with the Pending status until the task runs on schedule.
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.
Rsync provides the ability to either push or pull data. The Push function 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.
There are two ways to connect to a remote system and run an rsyc task: setting up an SSH connection or an rsync module. You need to have either an SSH connection for the remote server already configured or an rsync module configured in a remote rsync server. Each has different preparation requirements.
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 uses to run the rsync task.
Create an SSH connection and keypair. Go to Credentials > Backup Credentials to add an SSH connection and keypair. Download the keys. Enter the admin user that should set up and have permission to perform the remote sync operation with the remote system. If using two TrueNAS systems with the admin user, enter admin. If one system only uses the root user, enter root.
Update the admin user by adding the private key to user in the UI and then adding the private key to the home directory for the admin user. When the Rsync Mode is SSH,
Start the SSH service on both systems. Go to System Settings > Services and enable SSH.
Create a dataset on the remote TrueNAS (or other system). Write down the host and path to the data on the remote system you plan to sync with.
Create a module on the remote system. On TrueNAS, install an rsync app (for example, Rsyncd) and configure the module.
First, enable SSH and establish a connection to the remote server.
After establishing the SSH connection, add the rsync task.
Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Choose a Direction for the rsync task as either Push or Pull and then define the task Schedule.
Select a User account that matches the SSH connection Username entry in the SSH Connections set up for this remote sync.
Provide a Description for the rsync task.
Select SSH in Rsync Mode. The SSH settings fields show.
Choose a connection method from the Connect using dropdown list.
If selecting SSH private key stored in user’s home directory, enter the IP address or hostname of the remote system in Remote Host. Use the format username@remote_host if the username differs on the remote host. Enter the SSH port number for the remote system in Remote SSH Port. By default, 22 is reserved in TrueNAS.
If selecting SSH connection from the keychain, select an existing SSH connection to a remote system or choose Create New to add a new SSH connection.
Enter a full path to a location on the remote server where you either copy information from or to in Remote Path. Maximum path length is 255 characters.
If the remote path location does not exist, select Validate Remote Path to create and define it in Remote Path.
Select the schedule to use and configure the remaining options according to your specific needs.
Click Save.
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 per rsyncd.conf(5) on the rsync server. The Rsync Daemon application is available in situations where configuring TrueNAS as an rsync server with an rsync module is necessary. If the non-TruNAS remote server includes an rsync service, make sure it is turned on.
After configuring the rsync server, go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.
Enter or browse to the dataset or folder to sync with the remote server. Use the
to the left of the /mnt folder and each folder listed on the tree to expand and browse through, then click on the name to populate the path field.Click in the User field then select the user from the dropdown list. The user must have permissions to run an rsync on the remote server.
Set the Direction for the rsync task. Select Pull to copy from the remote server to TrueNAS or Push to copy from TrueNAS to the remote server.
Select Module as the connection mode from the Rsync Mode dropdown.
Enter the remote host name or IP in Remote Host. Use the format username@remote_host when the username differs from the host entered into the Remote Host field.
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.
Select the Enabled to enable the task. Leave cleared to disable the task but not delete the configuration. You can still run the rsync task by going to Data Protection and clicking then the Run Now play_arrow icon for the rsycn task.
Click Save.
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.
A snapshot lifetime value defines how long the snapshot schedule ignores that snapshot when it looks for obsolete snapshots to remove. For example, defining a lifetime of two weeks on a snapshot created after a weekly snapshot schedule runs can result in that snapshot actually being deleted three weeks later. This is because the snapshot has a timestamp and defined lifetime that preserves the snapshot until the next time the scheduled snapshot task runs.
TrueNAS also preserves snapshots when at least one periodic task requires it. For example, you have two schedules created where one schedule takes a snapshot every hour and keeps them for a week, and the other takes a snapshot every day and keeps them for 3 years. Each has an hourly snapshot taken. After a week, snapshots created at 01.00 through 23.00 get deleted, but you keep snapshots timed at 00.00 because they are necessary for the second periodic task. These snapshots get destroyed at the end of 3 years.
Use this procedure to create ZFS snapshots when using TrueNAS SCALE as a VMWare datastore.
You must have a paid edition of VMWare ESXi to use the TrueNAS SCALE VMWare Snapshots feature. ESXi free has a locked (read-only) API that prevents using TrueNAS SCALE VMWare Snapshots.
This tutorial uses ESXi version 8.
When creating a ZFS snapshot of the connected dataset, VMWare automatically takes a snapshot of any running virtual machines on the associated datastore. VMware snapshots can integrate VMware Tools, making it possible to quiesce VM snapshots, sync filesystems, take shadow copy snapshots, and more. Quiescing snapshots is the process of bringing VM data into a consistent state, suitable for creating automatic backups. Quiesced snapshots can be file-system consistent, where all pending data or file-system changes complete, or application consistent, where applications complete all tasks and flush buffers, prior to creating the snapshot.See Manage Snapshots from VMWare for more information.
VM snapshots are included as part of the connected Virtual Machine File System (VMFS) datastore and stored as a point-in-time within the scheduled or manual TrueNAS ZFS snapshot of the data or zvol backing that VMWare datastore. The temporary VMware snapshots are automatically deleted on the VMWare side, but still exist in the ZFS snapshot and are available as stable restore points.
TrueNAS EnterpriseTrueNAS Enterprise customers with TrueNAS CORE 12.0 and newer and TrueNAS SCALE 22.12.4 (Bluefin) and newer deployed can access the iXsystems TrueNAS vCenter plugin. This activates management options for TrueNAS hardware attached to vCenter Server and enables limited management of TrueNAS systems from a single interface.
Please contact iXsystems Support to learn more and schedule a time to deploy or upgrade the plugin.
Before using TrueNAS SCALE to create VMWare snapshots, configure TrueNAS to present a VMFS datastore or NFS export to your ESXi host(s) (this tutorial uses iSCSI) and then create and start your VM(s) in ESXi. Virtual machines must be running for TrueNAS to include them in VMWare snapshots, because powered-off virtual machines are already in a consistent state
Go to Datasets and click Add Zvol to create a dedicated zvol for VMWare.
This tutorial uses virtual/vmware/zvol-01.
Create an iSCSI share. Go to Shares and click Wizard on the Block (iSCSI) Shares Targets widget.
a. Enter a name for the share. For example, vmware.
Select Device for Extent Type and select the zvol from the Device dropdown.
Leave Sharing Platform set to VMware and Target set to Create New, then click Next.
b. Set Portal to Create New. You can leave Discovery Authentication Method set to NONE, or select CHAP or Mutual CHAP and enter a Discovery Authentication Group ID. Click Add next to IP Address and select either 0.0.0.0 for IPv4 or :: for IPv6 to listen on all ports.
c. Leave Initiators blank and click Save.
In the VMWare ESXi Host Client, go to Storage, select Adapters, and then click Software iSCSI to configure the iSCSI connection.
a. Configure CHAP authentication if needed or leave set to Do not use CHAP.
b. Click Add dynamic target, enter the IP address for the TrueNAS SCALE system, and click Save Configuration to return to the Adapters screen.
c. Click Rescan to discover the iSCSI initiator. ESXi automatically adds static targets for discovered initiators. Click Software iSCSI again to confirm.
d. Go to Devices and click Rescan to discover the shared storage. ESXi adds the TrueNAS iSCSI disk to the list of devices.
Go to Datastores and click New Datastore to create a new VMFS datastore using the TrueNAS device. Then go to Virtual Machines and create your new virtual machine(s), using the new datastore for storage.
To configure TrueNAS SCALE to create VMWare snapshots, go to Data Protection and click the VMware Snapshot Integration button in the Periodic Snapshot Tasks widget to open the VMWare Snapshots screen.
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 credentials on the VMware host with ‘Create Snapshot’ and ‘Remove Snapshot’ permissions in VMware. See Virtual Machine Snapshot Management Privileges from VMware for more information.
Click Fetch Datastores. This connects TrueNAS SCALE to the VMWare host and populates the ZFS Filesystem and Datastore dropdown fields. Make sure the correct TrueNAS ZFS dataset or zvol matching the VMware datastore is populated.
Select the TrueNAS SCALE dataset from the ZFS Filesystem dropdown list of options.
Select the VMFS datastore from the Datastore dropdown list of options.
Click Save. The saved snapshot configuration appears on the VMware Snapshots screen.
State indicates the current status of the VMware connection as PENDING, SUCCESS, or ERROR.
Create a new periodic snapshot task for the zvol or a parent dataset. If there is an existing snapshot task for the zvol or a parent dataset, VMWare snapshots are automatically integrated with any snapshots created after the VMWare snapshot is configured.
Expand the configured task on the Periodic Snapshot Tasks screen and ensure that VMware Sync is true.
To revert a VM using a ZFS snapshot, first clone the snapshot as a new dataset in TrueNAS SCALE, present the cloned dataset to ESXi as a new LUN, resignature the snapshot to create a new datastore, then stop the old VM and re-register the existing machine from the new datastore.
Clone the snapshot to a new dataset.
a. Go to Data Protection and click Snapshots on the Periodic Snapshot Tasks widget and locate the snapshot you want to recover and click on that row to expand details.
b. Click Clone to New Dataset. Enter a name for the new dataset or accept the one provided then click Clone.
The cloned zvol appears on the Datasets screen.
Share the cloned zvol to VMWare using NFS or iSCSI (this tutorial uses iSCSI).
a. Go to Shares and click Block (iSCSI) Shares Targets to access the iSCSI screen.
b. Click Extents and then click Add to open the Add Extent screen.
c. Enter a name for the new extent, select Device from the Extent Type dropdown, and select the cloned zvol from the Device dropdown. Edit other settings according to your use case and then click Save.
d. Click Associated Targets and then click Add to open the Add Associated Target screen.
e. Select the existing VMWare target from the Target dropdown. Enter a new LUN ID number or leave it blank to automatically assign the next available number. Select the new extent from the Extent dropdown and then click Save.
Go to Storage > Adapters and click Rescan to discover the new LUN. Then go to the Devices tab and click Rescan again to discover VMFS filesystems on the LUN. At this point, ESXi discovers the cloned device snapshot, but is unable to mount it because the original device is still online.
Resignature the snapshot so that it can be mounted.
a. Access the ESXi host shell using SSH or a local console connection to resignature the snapshot
b. Enter the command
esxcli storage vmfs snapshot list
to view the unmounted snapshot.
Note the VMFS UUID
value.
c. Enter the command
esxcli storage vmfs snapshot resignature -u VMFS-UUID
, where VMFS-UUID is the ID of the snapshot according to the previous command output.
ESXi resignatures the snapshot and automatically mounts the device.
d. Go back to Storage > Devices in the ESXi Host Client UI and click Refresh. The mounted snapshot appears in the list of devices.
e. Go to the Datastores tab. You might need to click Refresh again. A new datastore for the mounted snapshot appears in the list of datastores.
Stop the old virtual machine(s) you want to revert and use the snapshot datastore to register an existing VM from the snapshot.
a. Go to Virtual Machines in ESXi, select the existing VM(s) to revert, and click Power Off.
b. Click Create / Register VM to open the New virtual machine screen.
c. Select Register an existing virtual machine and then click next.
d. Click Select and use the Datastore Browser to select the snapshot datastore.
Select the VM(s) you want to revert and click Next.
e. Review selections on the Ready to complete screen/ If correct, click Finish.
Start the new VM(s) and verify functionality, then delete or archive the previous VM(s). Copy or migrate the VMware virtual machine to the original, non-snapshot datastore.
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.
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.
Before setting up a replication task, you must configure the admin user with the Home Directory set to something other than /var/empty and Auxiliary Groups set to include the builtin_administrators group.
Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
Verify the SSH service settings to ensure you have Root with Password, Log in as Admin with Password, and Allow Password Authentication selected to enable these capabilities. Incorrect SSH service settings can impact the admin user ability to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Replication tasks typically require a configured and active periodic snapshot task.
Set up the data storage for where you want to save replicated snapshots.
Make sure the admin user is correctly configured.
Create a Periodic Snapshot task of the storage locations to be backed up.
Create an SSH connection between the local SCALE system and the remote system for remote replication tasks. Local replication does not require an SSH connection. You can do this from either Credentials > Backup Credentials > SSH Connection and clicking Add or from the Replication Task Wizard using the Generate New option in the settings for the remote system.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard where you specify the settings for the replication task.
Setting options change based on the source selections. Replicating to or from a local source does not require an SSH connection.
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 the Local Administrator user and role-based permissions, 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.
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.
Before setting up a replication task, you must configure the admin user with the Home Directory set to something other than /var/empty and Auxiliary Groups set to include the builtin_administrators group.
Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
Verify the SSH service settings to ensure you have Root with Password, Log in as Admin with Password, and Allow Password Authentication selected to enable these capabilities. Incorrect SSH service settings can impact the admin user ability to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Replication tasks typically require a configured and active periodic snapshot task.
Set up the data storage for where you want to save replicated snapshots.
Make sure the admin user is correctly configured.
Create a Periodic Snapshot task of the storage locations to be backed up.
Create an SSH connection between the local SCALE system and the remote system for remote replication tasks. Local replication does not require an SSH connection. You can do this from either Credentials > Backup Credentials > SSH Connection and clicking Add or from the Replication Task Wizard using the Generate New option in the settings for the remote system.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard where you specify the settings for the replication task.
Setting options change based on the source selections. Replicating to or from a local source does not require an SSH connection.
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 to populate 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 the Local Administrator user and role-based permissions, 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.
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.
Before setting up a replication task, you must configure the admin user with the Home Directory set to something other than /var/empty and Auxiliary Groups set to include the builtin_administrators group.
Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
Verify the SSH service settings to ensure you have Root with Password, Log in as Admin with Password, and Allow Password Authentication selected to enable these capabilities. Incorrect SSH service settings can impact the admin user ability to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Replication tasks typically require a configured and active periodic snapshot task.
Set up the data storage for where you want to save replicated snapshots.
Make sure the admin user is correctly configured.
Create a Periodic Snapshot task of the storage locations to be backed up.
Create an SSH connection between the local SCALE system and the remote system for remote replication tasks. Local replication does not require an SSH connection. You can do this from either Credentials > Backup Credentials > SSH Connection and clicking Add or from the Replication Task Wizard using the Generate New option in the settings for the remote system.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard where you specify the settings for the replication task.
Setting options change based on the source selections. Replicating to or from a local source does not require an SSH connection.
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 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 regular snapshots of storage pools or datasets and saves them in the destination location on the same or another 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.
The Advanced Replication Creation option opens the Add Replication Task screen. This screen provides access to the same settings found in the replication wizard but has more options to specify:
You can also:
With the implementation of the local administrator user to replace the root login, there are a few differences between setting up replication tasks as an admin user than with setting up replication tasks when logged in as root. Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
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.
Before setting up a replication task, you must configure the admin user with the Home Directory set to something other than /var/empty and Auxiliary Groups set to include the builtin_administrators group.
Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.
Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.
Verify the SSH service settings to ensure you have Root with Password, Log in as Admin with Password, and Allow Password Authentication selected to enable these capabilities. Incorrect SSH service settings can impact the admin user ability to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.
Replication tasks typically require a configured and active periodic snapshot task.
Set up the data storage for where you want to save replicated snapshots.
Make sure the admin user is correctly configured.
Create a Periodic Snapshot task of the storage locations to be backed up.
Create an SSH connection between the local SCALE system and the remote system for remote replication tasks. Local replication does not require an SSH connection. You can do this from either Credentials > Backup Credentials > SSH Connection and clicking Add or from the Replication Task Wizard using the Generate New option in the settings for the remote system.
Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard where you specify the settings for the replication task.
Setting options change based on the source selections. Replicating to or from a local source does not require an SSH connection.
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 source of snapshots to replicate. Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories.
A remote destination requires you to specify an SSH connection before you can enter or select the path. If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and configure it to allow SSH connections. Define how long to keep snapshots in the destination.
Remote sources require defining a snapshot naming schema to identify the snapshots to replicate. Local sources are replicated by snapshots that were generated from a periodic snapshot task and/or from a defined naming schema that matches manually created snapshots.
DO NOT use zvols as remote destinations.
Select a previously configured periodic snapshot task for this replication task in Periodic Snapshot Tasks. The replication task selected must have the same values in Recursive and Exclude Child Datasets as the chosen periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
If a periodic snapshot task does not exist, exist the advanced replication task configuration, go configure a periodic snapshot task, then return to the Advanced Replication screen to configure the replication Task. Select Replicate Specific Snapshots to define specific snapshots from the periodic task to use for the replication. This displays the schedule options for the snapshot task. Enter the schedule. The only periodically generated snapshots included in the replication task are those that match your defined schedule.
Select the naming schema or regular expression option to use for this snapshot.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema custom-%Y-%m-%d_%H-%M
finds and replicates snapshots like custom-2020-03-25_09-15
.
Enter multiple schemas by pressing Enter to separate each schema.
Set the replication schedule to use and define when the replication task runs. Leave Run Automatically selected to use the snapshot task specified and start the replication immediately after the related periodic snapshot task completes. Select Schedule to display scheduling options for this replication task and To 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 additional setting options HEX key or PASSPHRASE. You can store the encryption key either in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination 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 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 the Local Administrator user and role-based permissions, when setting up remote replication tasks when logged in as an admin user requires selecting Use Sudo For ZFS Commands.
The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.
Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.
Remote replication with datasets also require an SSH connection in TrueNAS. You can use an existing SSH connection if it has the same user credentials you want to use for the new replication task.
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. Click the from the replication task options to download a key file that unlocks the destination dataset.
TrueNAS does not support preserving encrypted dataset properties when trying to re-encrypt an already encrypted source dataset.
To replicate an encrypted dataset to an unencrypted dataset on the remote destination system, follow the instructions above to configure the task, then to clear the dataset properties for the replication task:
Select the task on the Replication Task widget. The Edit Replication Task screen opens.
Scroll down to and select Include Dataset Properties to clear the checkbox.
This replicates the unlocked encrypted source dataset to an unencrypted destination dataset.
When you replicate an encrypted pool or dataset you have one level of encryption applied at the data storage level. Use the passphrase or key created or exported from the dataset or pool to unlock the dataset on the destination server.
To add a second layer of encryption at the replication task level, select Encryption on the Replication Task Wizard, 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.
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.
The Network screen allows you to add new or edit existing network interfaces, and configure static and alias IP addresses.
Prepare your system for interface changes by stopping and/or removing apps, VM NIC devices, and services that can cause conflicts:
If you encounter issues with testing network changes, you might need to stop any services, including Kubernetes and sharing services such as SMB, using the current IP address.
You can use DHCP to provide the IP address for only one network interface and this is most likely for your primary network interface configured during the installation process.
To add another network interface, click Add on the Interfaces widget to display the Add Interface panel. Leave the DHCP checkbox clear. Click Add to the right of Aliases, near the bottom of the Add Interface screen and enter a static IP address for the interface.
You must specify the type of interface you want to create. Select the type of interface from the Type dropdown 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 then click on the Edit icon to open the Edit Interface screen. The Edit Interface and Add Interface settings are identical except for Type and Name. You cannot edit these settings after you click Save. Name shows on the Edit Interface screen, but you cannot change the name. Type only shows on the Add Interface screen. If you make a mistake with either field you can only delete the 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 for the interface. A delete interface confirmation dialog opens.
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.
To configure alias IPs to provide access to internal portions of the network, go to the Network screen:
Click on the Edit icon for the interface to open the Edit Interface screen for the selected interface.
Clear the DHCP checkbox to show Aliases. Click Add for each alias you want to add to this interface.
Enter the IP address and CIDR values for the alias(es).
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 bridge in Linux. While the examples focus on the deprecated brctl(8) from the bridge-utilities package, we use ip(8) and bridge(8) from iproute2 instead. Refer to the FAQ section that covers bridging topics more generally.
Network bridging does not inherently aggregate bandwidth like link aggregation (LAGG). Bridging is often used for scenarios where you need to extend a network segment or combine different types of network traffic. Bridging can be used to integrate different types of networks (e.g., wireless and wired networks) or to segment traffic within the same network. A bridge can also be used to allow a VM configured on TrueNAS to communicate with the host system. See Accessing NAS From a VM for more information.
Prepare your system for interface changes by stopping and/or removing apps, VM NIC devices, and services that can cause conflicts:
If you encounter issues with testing network changes, you might need to stop any services, including Kubernetes and sharing services such as SMB, using the current IP address.
To set up a bridge interface, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
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. 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 Description.
Select the interfaces on the Bridge Members dropdown list.
Click Add to the right of Aliases to show the IP address fields, and enter the IP address for this bridge interface. Click Add again to show an additional IP address fields for each additional IP address you want to add.
Click Save when finished. The created bridge shows in Interfaces with its associated IP address information.
Click Test Changes to determine if network changes are successful.
After TrueNAS finishes testing the interface, click Save Changes to keep the changes. Click Revert Changes to discard the changes and return to the previous configuration.
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.
Prepare your system for interface changes by stopping and/or removing apps, VM NIC devices, and services that can cause conflicts:
If you encounter issues with testing network changes, you might need to stop any services, including Kubernetes and sharing services such as SMB, using the current IP address.
To set up a LAGG, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select Link Aggregation from the Type dropdown list. You cannot change the Type field value after you click Save.
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 clicking Apply.
(Optional, but recommended) Enter any notes or reminders about this particular LAGG interface in Description.
Select the protocol from the Link Aggregation Protocol dropdown. Options are LACP, FAILOVER, or LOADBALANCE. Each option displays additional settings.
Select the interfaces to use in the aggregation from the Link Aggregation Interface dropdown list.
(Optional) Click Add to the right of Aliases to show additional IP address fields for each additional IP address to add to this LAGG interface.
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, go to Network, click Add on the Interfaces widget to open the Add Interface screen, then:
Select VLAN from the Type dropdown list. You cannot change the Type field value after 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 clicking Save.
(Optional, but recommended) Enter any notes or reminders about this particular VLAN in Description.
Select the interface in the Parent Interface dropdown list. This is typically an Ethernet card connected to a switch port already configured for the VLAN.
Enter the numeric tag for the interface in the VLAN Tag field. This is typically preconfigured in the switched network.
Select the VLAN Class of Service from the Priority Code Point dropdown list.
(Optional) Click Add to the right of Aliases to show additional IP address fields for each additional IP address to add to this VLAN interface.
Click Save.
This article describes 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.
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 while making and testing network changes. 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. Save the system configuration file and a system debug.
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 might require reconfiguring 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 Edit icon for the interface on the Interfaces widget to open the Edit Interface screen, then clear the DHCP checkbox.
Click Add to the right of Aliases to add IP address fields, then 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. A dialog opens 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 widget. If the current settings are not on the same network, click Settings and modify each setting as needed to allow the static IP to communicate over the network.
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 dialog 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 an existing network interface set to use DHCP you can convert an interface from static IP to DHCP.
To switch/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 Edit icon for 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 screen, then enter the 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 and 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.
Go to Network and click Settings on the Global Configuration widget to open the Edit Global Configuration screen, then:
Enter the host name for your TrueNAS in Hostname. For example, host.
Enter the system domain name in Domain. For example, example.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 Default 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 for which you want to permit external communications. Unchecked services cannot communicate externally.
Click Save. The Global Configuration widget on the Network screen updates to show the new settings.
Use the Global Configuration Settings screen to manage existing general network settings like the default gateway and 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 for external communication capability.
These services use external communication:
Select Allow All to permit all the above services to communicate externally. This is the default setting.
Select Deny All to prevent all the above services from communicating externally.
Select Allow Specific to permit external communication for the services you select. Allow Specific displays a dropdown list of the services you can select. Click on all that apply. A checkmark displays next to a selected service, and these services display in the field separated by a comma (,).
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 to open the Global Configuration screen.
Select Enable Netwait Feature. The Netwait IP List field displays.
Enter your list of IP addresses to ping. Press Enter after entering each IP address.
Click Save when finished.
TrueNAS EnterpriseThe instructions in the article only apply to SCALE Enterprise (HA) systems.
Both controllers must be powered on and ready before you configure network settings.
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready to sync to peer, SCALE applies settings to controller 2 at that time.
SCALE Enterprise (HA) systems use three static IP addresses for access to the UI:
Have the list of network addresses, name sever and default gateway IP addresses, and host and domain names ready so you can complete the network configuration without disruption or system timeouts.
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.
To configure network settings on controller 1:
Disable the failover service. Go to System Settings > Services locate the Failover service and click edit. Select Disable Failover and click Save.
Edit the global network settings to add any missing network settings or make any changes.
Edit the primary network interface to add failover settings. Go to Network and click on the primary interface eno1 to open the Edit Interface screen for this interface.
a. Turn DHCP off if it is on. 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.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
Click Save
Click Test Changes after editing the interface settings. 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 and 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 to open the Add Static Route screen.
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.
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 the TrueNAS SCALE administrator login permitted users to continue using the root user but encouraged users to create a 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.
TrueNAS SCALE plans to permanently disable root account access in a future release.
SCALE has implemented administrator roles and privileges that allow greater control over access to functions in SCALE and to further comply with FIPS security hardening standards. SCALE includes three predefined admin user account levels:
Full Admin - This is the local administrator account created by the system when doing a clean install using an
Sharing Admin - This is assigned to users responsible for only managing shares (SMB, NFS, iSCSI). This user can create shares and the datasets for shares, start/restart the share service, and modify the ACL for the share dataset.
Read-only Admin - This is assigned to users that can monitor the system but not make changes to settings.
At present, SCALE has both the root and local administrator user logins and passwords.
Root is the default system administration account for CORE, SCALE Angelfish, and early Bluefin releases.
Users migrating from CORE to SCALE or from pre 22.12.3 releases must manually create an admin user account. Only fresh installations using an
iso file provide the option to create the admin user during the installation process.SCALE systems with only the root user account can log in to the TrueNAS web interface as the root user. After logging in as root, TrueNAS alerts you to create the local administrator account.
System administrators should create and begin using the admin login, and then disable the root user password.
SCALE 24.04 (Dragonfish) introduces administrators privileges and role-based administrator accounts. The root or local administrator user can create new administrators with limited privileges based on their needs. Predefined administrator roles are read only, share admin, and the default full access 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.
All systems should create the local administrator account and use this account for web interface access. When properly set up, the local administrator (full admin) account performs the same functions and has the same access as the root user.
Some UI screens and settings still refer to the root account, but these references are updating to the administrator account in future releases of SCALE.
To improve system security after the local administrator account is created, disable the root account password to restrict root access to the system.
For more information on the different administrator scenarios users can encounter, read Logging Into SCALE the First Time.
As a security measure, the root user is no longer the default account and the 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 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 the admin user (or for root):
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 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 SSH password login enabled to allow authenticating and logging into an SSH session. Disable this after completing the SSH session to return to a security hardened system.
Select Allow all sudo commands with no password. You to see a prompt in the ssh session to enter a password the first time you enter a sudo command but to 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, administrator logins work with TrueCommand but you need to set up the TrueNAS connection using an 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.
Root is the default system administration account for CORE, SCALE Angelfish, and early Bluefin releases.
Users migrating from CORE to SCALE or from pre 22.12.3 releases must manually create an admin user account. Only fresh installations using an
iso file provide the option to create the admin user during the installation process.SCALE systems with only the root user account can log in to the TrueNAS web interface as the root user. After logging in as root, TrueNAS alerts you to create the local administrator account.
System administrators should create and begin using the admin login, and then disable the root user password.
SCALE 24.04 (Dragonfish) introduces administrators privileges and role-based administrator accounts. The root or local administrator user can create new administrators with limited privileges based on their needs. Predefined administrator roles are read only, share admin, and the default full access 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.
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.
All CORE systems migrating to SCALE, and all Angelfish and early Bluefin releases of SCALE upgrading to 22.12.3+ or to later SCALE major versions should create and begin using an admin user instead of the root user. After migrating or upgrading from CORE or a pre-SCALE 22.12.3 release to a later SCALE release, use this procedure to create the Local Administrator user.
Go to Credentials > Local Users and click Add.
Enter the name to use for the administrator account. For example, admin. You can create multiple admin users with any name and assign each different administration privileges.
Enter and confirm the admin user password.
Select builtin_administrators on the Auxiliary Group dropdown list.
Add the home directory for the new admin user. Enter or browse to select the location where SCALE creates the home directory. For example, /mnt/tank. If you created a dataset to use for home directories, select that dataset. Select the Read, Write, and Execute permissions for User, Group and Other this user should have, then select Create Home Directory.
Select the shell for this admin user from the Shell dropdown list. To have System Settings > Shell open in the Console Setup Menu, select TrueNAS Console. This gives the administrator access to the TrueNAS and Linux CLI prompts.
Select the sudo authorization permissions for this admin user. Some applications, such as Nextcloud, require sudo permissions for the administrator account. For administrator accounts generated during the initial installation process, TrueNAS SCALE sets authorization to Allow all sudo commands.
Click Save. The system adds the user to the builtin-users group after clicking Save.
Log out of the TrueNAS system and then log back in using the admin user credentials to verify that the admin user credentials work properly with your network configuration.
After adding the admin user account, disable the root user password:
Go to Credentials > Local Users, click on the root user and select Edit. Click the Disable Password toggle to disable the password, then click Save.
When creating a user, you must:
All other settings are optional. Click Save after configuring the user settings to add the user.
To create a new user, click Add.
Enter a personal name or description in Full Name, for example, John Doe or Share Anonymous User, then allow TrueNAS to suggest a simplified name derived from the Full Name or enter a name in Username.
Enter and confirm a password for the user.
Make sure the login password is enabled. Click the Disable Password toggle to enable/disable the login password.
Setting the Disable Password toggle to active (blue toggle) disables these functions:
Enter a user account email address in the Email field if you want this user to receive notifications
Accept the default user ID or enter a new UID. TrueNAS suggests a user ID starting at 3000, but you can change it if you wish. We recommend using an ID of 3000 or greater for non-built-in users.
Leave the Create New Primary Group toggle enabled to allow TrueNAS to create a new primary group with the same name as the user. To add the user to a different existing primary group, disable the Create New Primary Group toggle and search for a group in the Primary Group field. To add the user to more groups use the Auxiliary Groups dropdown list.
Configure a home directory and permissions for the user. Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
When creating a user, the home directory path is set to
SCALE 24.04 changes the user home directory location from /nonexistent, a directory that should never exist, to /var/empty. This new directory is an immutable directory shared by service accounts and accounts that should not have a full home directory. Services impacted:
- SMB if a home share is enabled
- SSH
- Shell access (edited)
Select Read, Write, and Execute for each role (User, Group, and Other) to set access control for the user home directory. Built-in users are read-only and can not modify these settings.
Assign a public SSH key to a user for key-based authentication by entering or pasting the public key into the Authorized Keys field. You can click Choose File under Upload SSH Key and browse to the location of an SSH key file.
Do not paste the private key.
Always keep a backup of an SSH public key if you are using one.
As of SCALE 24.04, users assigned to the trueNAS_readonly_administrators group cannot access the Shell screen.
Select the shell option for the admin user from the Shell dropdown list. Options are nologin, bash, rbash, dash, sh, tmux, and zsh. For members of the builtin_administrators and builtin_users groups, select TrueNAS Console to open in the Console Setup menu for SCALE that provides access to the Linux and SCALE CLI prompts, or select TrueNAS CLI to open the Shell screen in the TrueNAS CLI.
To disable all password-based functionality for the account, select Lock User. Clear to unlock the user.
Set the sudo permissions you want to assign this user. Exercise caution when allowing sudo commands, especially without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password and Allow all sudo commands with no password grant the account limited root-like permissions using the sudo command.
If selecting Allowed sudo commands or Allowed sudo commands with no password, enter the specific sudo commands allowed for this user.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano.
Leave Samba Authentication selected to allow using the account credentials to access data shared with SMB.
Click Save.
To edit an existing user account, go to Credentials > Local Users. Click anywhere on the user row to expand the user entry, then click 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 3000 for a group with user accounts or enter the default port number as the GID for a system service.
Enter a name for the group. The group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?) greater or less than (<) (>), equal (=). You can only use the dollar sign ($) as the last character in a group name.
Allowed sudo commands, Allow all sudo commands, Allowed sudo commands with no password and Allow all sudo commands with no password grant members of the group limited root-like permissions using the sudo command.
Use Allowed sudo commands or Allowed sudo commands with no password to list specific sudo commands allowed for group members.
Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano.
Exercise caution when allowing sudo commands, especially without password prompts. We recommend limiting this privilege to trusted users and specific commands to minimize security risks.
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. Use only if absolutely necessary, as duplicate GIDs can lead to unexpected behavior.
Click anywhere on a row to expand that group and show the group management buttons.
Use Members to manage membership and Edit or Delete to manage the group.
To manage group membership, go to Credentials > Local Groups, expand the group entry, and click Members to open the Update Members screen.
To add a user account to the group, select the user and then click the right arrow .
To remove a user account from the group, select the user and then click the left arrow .
To select multiple users, press Ctrl and click on each entry.
Click Save.
To edit an existing group, go to Credentials > Local Groups, expand the group entry, and click edit Edit to open the Edit Group configuration screen. See Local Group Screens for details on all settings.
The SCALE Directory Services tutorials contain 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 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 widget 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.
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.
You must also configure and activate the SSH Service to allow SSH access.
To begin setting up an SSH connection, go to Credentials > Backup Credentials.
Click Add on the SSH Connections widget.
This procedure uses the semi-automatic setup method for creating an SSH connection with other TrueNAS or FreeNAS systems.
Follow these instructions to set 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 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.
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. Options are cloudflare, Amazon route53, OVH, and shell. Authenticator selection changes the configuration fields.
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.
If you select OVH as the authenticator, you must enter your OVH application key, application secret, consumer key, and endpoint.
Click Save to add the authenticator.
The shell authenticator option is meant for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.
If you select shell as the authenticator, you must enter the path to an authenticator script, the running user, a certificate timeout, and a domain propagation delay.
Advanced users can select this option to pass an authenticator script, such as acme.sh, to shell and add an external DNS authenticator. Requires an ACME authenticator script saved to the system.
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.
For OVH, enter your OVH Application Key, OVH Application Secret, OVH Consumer Key, and OVH Endpoint.
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.
TrueNAS EnterpriseKMIP 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.
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, obtain 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, 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 Enable Display to enable a SPICE Virtual Network Computing (VNC) remote connection for the VM. The Bind and Password fields display. If Enable Display is selected:
Enter a display Password
Use the dropdown menu to change the default IP address in Bind if you want to use a specific address as the display network interface, otherwise leave it set to 0.0.0.0. The Bind menu populates any existing logical interfaces, such as static routes, configured on the system. Bind cannot be edited after VM creation.
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.
Use Memory Size and Minimum Memory Size to specify how much RAM to dedicate to this VM. To dedicate a fixed amount of RAM, enter a value (minimum 256 MiB) in the Memory Size field and leave Minimum Memory Size empty.
To allow for memory usage flexibility (sometimes called ballooning), define a specific value in the Minimum Memory Size field and a larger value in Memory Size. The VM uses the Minimum Memory Size for normal operations but can dynamically allocate up to the defined Memory Size value in situations where the VM requires additional memory. Reviewing available memory from within the VM typically shows the Minimum Memory Size.
Click Next.
Configure 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 for 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.
Configure 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.
Click on the VM row on the Virtual Machines screen to expand it and show the options, then click device_hub Devices.
Device notes:
See Adding and Managing VM Devices for more information.
After creating the VM and configuring devices for it, click on the VM to expand it and show the options to manage the VM.
An active VM displays options for settings_ethernet Display and keyboard_arrow_right Serial Shell connections.
When a Display device is configured, remote clients can connect to VM display sessions using a SPICE client, or by installing a 3rd party remote desktop server inside your VM. SPICE clients are available from the SPICE Protocol site.
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 does not have a guest OS installed, the VM State toggle and stop Stop button might not function as expected. The State toggle and stop Stop buttons send an ACPI power down command to the VM operating system, but since an OS is not installed, these commands time out. Use the Power Off button instead.
After configuring the VM in TrueNAS and 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.
Configure VM network settings during or after installation of the guest OS. To communicate with a VM from other parts of your local network, use the IP address configured or assigned by DHCP within the VM.
To confirm network connectivity, send a ping to and from the VM and other nodes on your local network.
By default, VMs are unable to communicate directly with the host NAS. If you want to access your TrueNAS SCALE directories from a VM, to connect to a TrueNAS data share, for example, 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.
To create a bridge interface for the VM to use if you have only one physical interface, stop all existing apps, VMs, and services using the current interface, edit the interface and VMs, create the bridge, and add the bridge to the VM device. See Accessing NAS from VM for more information.
After creating a VM, the next step is to add virtual devices for that VM. Using the Create Virtual Machine wizard configures at least one disk, NIC, and the display as part of the process. To add devices, from the Virtual Machines screen, click anywhere on a VM entry to expand it and show the options for the VM.
Click device_hub Devices to open the Devices screen for 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, or use the Stop and Restart buttons.
Select Edit to open the Edit Device screen. You can change the type of virtual hard disk, the storage volume to use, or change the device boot order.
To edit a VM device:
Deleting a device removes it from the list of available devices for the selected VM.
To delete a VM device:
Stop the VM if it is running, then click Devices to open the list of devices for the selected VM.
Click on the
icon at the right of the listed device you want to edit, then select Delete. The Delete Virtual Machine dialog opens.Select Delete zvol device to confirm you want to delete the zvol device. Select Force Delete if you want the system to force the deletion of the zvol device, even if other devices or services are using or affiliated with the zvol device.
Click Delete Device.
Select CD-ROM as the Device Type on the Add Device screen and set a boot order.
Stop the VM if it is running, then click Devices.
Click Add and select CD-ROM from the Device Type dropdown list.
Specify the mount path. Click on the to the left of /mnt and at the pool and dataset levels to expand the directory tree. Select the path to the CD-ROM device.
Specify the boot sequence in Device Order.
Click Save.
Restart the VM.
Select NIC in the Device Type on the Add Device screen to add a network interface card for the VM to use.
Stop the VM if it is running, then click Devices.
Click Add and select NIC from the Device Type dropdown list.
Select the adapter type. Choose Intel e82585(e1000) for maximum compatibility with most operating systems. If the guest OS supports VirtIO paravirtualized network drivers, choose VirtIO for better performance.
Click Generate to assign a new random MAC address to replace the random default address, or enter your own custom address.
Select the physical interface you want to use from the NIC To Attach dropdown list.
(Optional) Select Trust Guest Filters to allow the virtual server to change its MAC address and join multicast groups. This is required for the IPv6 Neighbor Discovery Protocol (NDP).
Setting this attribute has security risks. It allows the virtual server to change its MAC address and receive all frames delivered to this address. Determine your network setup needs before setting this attribute.
Click Save.
Restart the VM
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.
Stop the VM if it is running, then click Devices.
Click Add and select Disk from the Device Type dropdown list.
Select the path to the zvol you created when setting up the VM using the Zvol dropdown list.
Select the hard disk emulation type from the Mode dropdown list. Select AHCI for better software compatibility, or VirtIO for better performance if the guest OS installed in the VM supports VirtIO disk devices.
Specify the sector size in bytes in Disk Sector Size. Leave set to Default or select either 512 or 4096 from the dropdown list to change it. If the sector size remains unset it uses the ZFS volume values.
Specify the boot sequence order for the disk device.
Click Save.
Restart the VM.
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 might see a warning: PCI device does not have a reset mechanism defined. You may experience inconsistent or degraded behavior when starting or stopping the VM. Determine if you want to proceed with this action in such an instance.
Stop the VM if it is running, then click Devices.
Click Add and select PCI Passthrough Device from the Device Type dropdown list.
Enter a value in PCI Passthrough Device using the format of bus#/slot#/fcn#.
Specify the boot sequence order for the PCI passthrough device.
Click Save.
Restart the VM.
Select USB Passthrough Device as the Device Type on the Add Device screen to configure the USB passthrough device, and set a boot order.
Stop the VM if it is running, then click Devices.
Click Add and select USB Passthrough Device from the Device Type dropdown list.
Select the Controller Type from the dropdown list.
Select the hub controller type from the Device dropdown list. If the type is not listed, select Specify custom, then enter the Vendor ID and Product ID.
Specify the boot sequence order.
Click Save.
Restart the VM.
Select Display as Device Type on the Add Device screen to configure a new display device.
Stop the VM if it is running, then click Devices.
Click Add and select Display from the Device Type dropdown list.
Enter a fixed port number in Port. To allow TrueNAS to assign the port after restarting the VM, set the value to zero (leave the field empty).
Specify the display session settings: a. Select the screen resolution to use for the display from the Resolution dropdown. b. Select an IP address for the display device to use in Bind. The default is 0.0.0.0. c. Enter a unique password for the display device to securely access the VM.
Select Web Interface to allow access to the VNC web interface.
Click Save.
Restart the VM.
Display devices have a 60-second inactivity timeout. If the VM display session appears unresponsive, try refreshing the browser tab.
If you want to access your TrueNAS SCALE directories from a VM, you have multiple options:
Prepare your system for interface changes by stopping and/or removing apps, VM NIC devices, and services that can cause conflicts:
If you encounter issues with testing network changes, you might need to stop any services, including Kubernetes and sharing services such as SMB, using the current IP address.
If your system only has a single physical interface, complete these steps to create a network bridge.
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 to open the Edit Interface screen.
If enabled, 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 without IP information.
Add a bridge interface.
Edit VM device configuration.
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.
If you have more than one NIC on your system, you can assign VM traffic to a secondary NIC. Configure the secondary interface as described in Managing Interfaces before attaching it to a VM.
If you are creating a new VM, use the Attach NIC dropdown menu under Network Interface to select the secondary NIC.
To edit the NIC attached to an existing VM:
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 secondary interface from the NIC to Attach dropdown list, then click Save.
The first time you go to Apps, the Installed applications screen displays an Apps Service Not Configured status on the screen header.
After setting the pool apps uses, this changes to Apps Service Running.
The Installed applications screen displays Check Available Apps before you install the first application.
Click Check Available Apps or Discover Apps to open the Discover screen to see application widgets available in the TRUENAS catalog.
After installing an application, the Installed screen populates the Applications area with a table listing installed applications. Select an application to view the information widgets for applications, with options to edit the application settings, open container pod shell or logs, and access the Web Portal for the application, if applicable.
Application widgets vary by app, but all include the Application Info and Workloads widgets. Some include the History and Notes widgets.
You must choose the pool apps use before you can add applications. The first time you go to the Applications screen, click Settings > Choose Pool to choose a storage pool for Apps.
We recommend keeping the application use case in mind when choosing a pool. Select a pool with enough space for all the applications you intend to use. For stability, we also recommend using SSD storage for the applications pool.
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 > General > GUI > Settings and locate the Web Interface HTTP -> HTTPS Redirect checkbox. To disable HTTPS redirects, clear this option and click Save, then clear the browser cache before attempting to connect to the app again.
After an apps storage pool is configured, the status changes to Apps Service Running.
To select a different pool for apps to use, click Settings > Unset Pool. This turns off the Apps service until you choose another pool for apps to use.
Official applications use the default system-level Kubernetes node IP settings.
You can change the Kubernetes node IP to assign an external interface to your apps, separate from the web UI interface, in Apps > Settings > Advanced Settings.
We recommend using the default Kubernetes node IP (0.0.0.0) to ensure apps function correctly.
The Settings dropdown includes an option Click Settings > Manage Container Images to open the Manage Container Images screen.
Update or delete images from this screen, or click Pull Image to download a specific custom image to TrueNAS.
To download a specific image, click the button and enter a valid path and tag to the image. Enter the path using the format registry/repository/image to identify the specific image. The default latest tag downloads the most recent image version.
When downloading a private image, enter user account credentials that allow access to the private registry.
Apps display a yellow circle with an exclamation point that indicates an upgrade is available, and the Installed application screen banner displays an Update or Update All button when upgrades are available. To upgrade an app to the latest version, click Update on the Application Info widget or to upgrade multiple apps, click the Update All button on the Installed applications banner. Both buttons only display if TrueNAS SCALE detects an available update for installed applications.
Update opens an upgrade window that includes two selectable options, Images (to be updated) and Changelog. Click on the down arrow to see the options available for each.
Click Upgrade to begin the process. A counter dialog opens showing the upgrade progress. When complete, the update badge and buttons disappear and the application Update state on the Installed screen changes from Update Available to Up to date.
To delete an application, click Stop on the application row. After the app status changes to stopped, click Delete on the Application Info widget for the selected application to open the Delete dialog.
Click Confirm then Continue to delete the application.
The Settings dropdown list at the top of the Installed applications screen provides these options:
The Discover screen displays New & Updated Apps application widgets for the official TRUENAS catalog Chart, Community, and Enterprise trains. Non-Enterprise systems show the Chart catalog of apps by default. The Chart catalog train has official applications that are pre-configured and only require a name during deployment.
Enterprise applications display automatically for Enterprise=licensed systems, but community users can add these apps using the Manage Catalogs screen. App trains display based on the Trains settings on the Edit Catalog screen.
See Using SCALE Catalogs for more information on managing catalogs.
The Discover screen includes three links:
The Custom App button opens a wizard where you can install unofficial apps or an app not included in a catalog.
Browse the widgets or use the search field to find an available application. Click on an application widget to go to the application information screen.
You can refresh the charts catalog by clicking Refresh Charts on the Discover screen. You can also refresh all catalogs from the Catalogs screen. Click Manage Catalogs, then click Refresh All. Refresh the catalog after adding or editing the catalogs on your system.
To filter the app widgets shown, click the down arrow to the right of Filters.
You can filter by catalog, app category, name, catalog name, and date last updated. Click on the option then begin typing the name of the app into the search field to narrow the widgets to fit the filter criteria. Click in Categories to select apps based on the selection you make. Click in the field again to add another category from the dropdown list to select multiple categories.
From the application information screen, click Install to open the installation wizard for the application.
After installing an application, the Installed applications screen shows the application in the Deploying state. It changes to Running when the application is ready to use.
The installation wizard configuration sections vary by application, with some including more configuration areas than others. Click Install to review settings ahead of time to check for required settings. Click Discover on the breadcrumb at the top of the installation wizard to exiting the screen without saving and until you are ready return and configure the app settings.
All applications include these basic setting sections:
Application Name shows the default name for the application.
If deploying more than one instance of the application, you must change the default name. Also includes the version number for the application. Do not change the version number for official apps or those included in a SCALE catalog. When a new version becomes available, the Installed application screen banner and application row displays an update alert, and the Application Info widget displays an update button> Updating the app changes the version shown on the edit wizard for the application.
Application Configuration shows settings that app requires to deploy. This section can be named anything. For example, the MinIO app uses MinIO Configuration.
Typical settings include user credentials, environment variables, additional argument settings, name of the node, or even sizing parameters.
If not using the default user and group provided, add the new user (and group) to manage the application before using the installation wizard.
Network Configuration shows network settings the app needs to communicate with SCALE and the Internet. Settings include the default port assignment, host name, IP addresses, and other network settings.
If changing the port number to something other than the default setting, refer to Default Ports for a list of used and available port numbers.
Some network configuration settings include the option to add a certificate. Create the certificate authority and certificate before using the installation wizard if using a certificate is required for the application.
Storage Configuration shows options to configure storage for the application. Storage options include using the default ixVolume setting that adds a storage volume under the ix-applications dataset, host path where you select existing dataset(s) to use, or in some cases the SMB share option where you configure a share for the application to use. The Add button allows you to configure additional storage volumes for the application to use in addition to the main storage volume (dataset).
If the application requires specific datasets, configure these before using the installation wizard.
Resources Configuration shows CPU and memory settings for the container pod. This section can also be named Resource Limits. In most cases, you can accept the default settings, or you can change these settings to limit the system resources available to the application.
After installing an app, you can modify most settings by selecting the app on the Installed applications screen and then clicking the Edit button on the Application Info widget for that app.
Refer to individual tutorials in the Community or Enterprise sections of the Documentation Hub for more details on application settings. Installation and editing wizards include tooltips to help users configure application settings.
Users with compatible hardware can allocate one or more GPU devices to an application for use in hardware acceleration. This is an advanced process that could require significant troubleshooting depending on installed GPU device(s) and application-specific criteria.
GPU devices can be available for the host operating system (OS) and applications or can be isolated for use in a Virtual Machine (VM). A single GPU cannot be shared between the OS/applications and a VM.
Allocate GPU from the Resources Configuration section of the application installation wizard screen or the Edit screen for a deployed application.
Click the GPU Resource allocation row for the type of GPU (AMD, Intel, or Nvidia) and select the number of GPU devices the application is allowed access to. It is not possible at this time to specify which available GPU device is allocated to the application and assigned devices can change on reboot.
To deploy a custom application, go to Discover and click Custom App to open the Install Custom App screen. See Using Install Custom App for more information.
Custom applications use the system-level Kubernetes Node IP settings by default.
You can assign an external interface to custom apps using one of the Networking section settings found on the Install Custom App screen.
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.
TrueNAS SCALE comes with a pre-built official catalog of over 50 available iXsystems-approved applications.
Users can configure custom apps catalogs if they choose, but iXsystems does not directly support non-official apps in a custom catalog.
TrueNAS uses outbound ports 80/443 to retrieve the TRUENAS catalog.
Users can manage the catalog from the Catalogs screen. Click Manage Catalogs at the top right side of the Discover screen to open the Catalogs screen.
Users can edit, refresh, delete, and view the catalog summary by clicking on a catalog to expand and show the options.
Edit opens the Edit Catalog screen where users can change the name SCALE uses to look up a catalog, add other trains to the catalog, or change the trains from which the UI retrieves available applications for the catalog.
Refresh pulls the catalog from its repository and refreshes it by applying any updates.
Delete allows users to remove a catalog from the system. Users cannot delete the default TRUENAS catalog.
Summary lists all apps in the catalog and sorts them by 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 Add Catalog at the top right of the Catalogs screen.
A warning dialog opens.
Click Continue to open the Add Catalog screen.
Fill out the Add Catalog form.
Enter a name in Catalog Name, for example, type mycatalog.
We do not recommend enabling Force Create, since it overrides safety mechanisms that prevent adding a catalog to the system even if some trains are unhealthy.
Select a valid GitHub repository in Repository. For example, https://github.com/mycatalog/catalog.
Type the name of the train TrueNAS should use to retrieve available application information from the catalog.
Finally, enter the GitHub repository branch TrueNAS should use for the catalog in Branch. Leave this set to main unless you need to change it.
Click Save.
Go to Apps and click on Discover Apps.
Click on Manage Catalogs at the top of the Discover screen to open the Catalog screen.
Click on the TRUENAS catalog to expand it, then click Edit to open the Edit Catalog screen.
Click in the Preferred Trains field, click on enterprise to add it to the list of trains, and then click Save.
SCALE includes the ability to run third-party apps in containers (pods) using Kubernetes settings.
Generally, any container that follows the Open Container Initiative specifications can be deployed.
Always read through the documentation page for the application container you are considering installing so that you know all of the settings that you need to configure. To set up a new container image, first, determine if you want the container to use additional TrueNAS datasets. If yes, create a dataset for host volume paths before you click Custom App on the Discover application screen.
Custom Docker applications typically follow Open Container specifications and deploy in TrueNAS following the Custom Application deployment process described below.
If your application requires directory paths, specific datasets, or other storage arrangements, configure these before you start the Install Custom App 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 Install Custom App Screen UI reference article before creating a new container image.
To create directories in a dataset on SCALE, before you begin installing the container, open the TrueNAS SCALE CLI and enter
storage filesystem mkdir path="/PATH/TO/DIRECTORY"
.
When you are ready to create a container, go to Apps, click Discover Apps, then click Custom App.
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 Entrypoint commands and arguments the application requires.
Enter the Container Environment Variables. Not all applications use environment variables. Check the application container documentation for details on what to install and to verify the 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 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 Install 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 up 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.
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 Kubernetes 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
Enhancing app security is a multifaceted challenge and there are various effective approaches. We invite community members to share insights on their methods by contributing to the documentation.
TrueNAS SCALE offers various applications, either directly provided or via the community. While applications can greatly expand TrueNAS functionality, making them accessible from outside the local network can create security risks that need to be solved.
Regardless of the VPN or reverse proxy you use, follow best practices to secure your applications.
- Update the applications regularly to fix security issues.
- Use strong passwords and 2FA, preferably TOTP, or passkeys for your accounts.
- Don’t reuse passwords, especially not for admin accounts.
- Don’t use your admin account for daily tasks.
- Create a separate admin account and password for every application you install.
The tutorials in this section aim to provide a general overview of different options to secure apps by installing an additional application client like Cloudflared or WireGuard to proxy traffic between the user and the application.
See the available guides below.
This Guide shows how to create a Cloudflare tunnel and configure the Nextcloud and Cloudflared applications in TrueNAS SCALE. The goal is to allow secure access from anywhere.
Exposing applications to the internet can create security risks. Always follow best practices to secure your applications.
See additional security considerations below.
Review the Nextcloud documentation to get a better understanding of the security implications before proceeding.
Cloudflare Tunnel is a system that proxies traffic between the user and the application over the Cloudflare network. It uses a Cloudflared client that is installed on the TrueNAS SCALE system.
This allows a secure and encrypted connection without the need of exposing ports or the private IP of the TrueNAS system to the internet.
Register or log in to a Cloudflare account. A free account is sufficient.
Follow Cloudflare documentation to register a domain and set up DNS.
This video from Lawrence Systems provides a detailed overview of setting up Cloudflare tunnels for applications. It assumes that the applications run as a docker container, but the same approach can be used to secure apps running on TrueNAS SCALE in Kubernetes.
In the Cloudflare One dashboard:
Go to Networks and select Tunnels.
Click Create Tunnel, choose type Cloudflared and click Next.
Choose a Tunnel Name and click Save tunnel.
Copy the tunnel token from the Install and run a connector screen. This is needed to configure the Cloudflared app in TrueNAS SCALE.
The operating system selection does not matter as the same token is used for all options. For example, the command for a docker container is:
docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token
eyJhIjoiNjVlZGZlM2IxMmY0ZjEwNjYzMDg4ZTVmNjc4ZDk2ZTAiLCJ0IjoiNWYxMjMyMWEtZjE
2YS00MWQwLWFhN2ItNjJiZmYxNmI4OGIwIiwicyI6IlpqQmpaRE13WXpBdFkyRmpPUzAwWVRCbU
xUZ3hZVGd0TlRWbE9UQmpaakEyTlRFMCJ9
Copy the string after --token
, then click Next.
Add a public hostname for accessing Nextcloud, for example: nextcloud.example.com.
Set service Type to HTTPS. Enter the local TrueNAS IP with the Nextcloud container port, for example 192.168.1.1:9001.
Go to Additional application Settings, select TLS from the dropdown menu, and enable No TLS Verify.
Click Save tunnel.
The new tunnel displays on the Tunnels screen.
After creating the Cloudflare tunnel, go to Apps in the TrueNAS SCALE UI and click Discover Apps. Search or browse to select the Cloudflared app from the community train and click Install.
Accept the default Application Name and Version.
Copy the Cloudflare tunnel token from the Cloudflare dashboard
Paste the token from Cloudflare, that you copied earlier, in the Tunnel Token field.
All other settings can be left as default.
Click Save and deploy the application.
Install the Nextcloud community application.
The first application deployment may take a while and starts and stops multiple times. This is normal behavior.
The Nextcloud documentation provides information on running Nextcloud behind a reverse proxy. Depending on the reverse proxy and its configuration, these settings may vary. For example, if you don’t use a subdomain, but a path like example.com/nextcloud.
If you want to access your application via subdomain (shown in this guide) two environment variables must be set in the Nextcloud application: overwrite.cli.url and overwritehost.
Enter the two environment variables in Name as OVERWRITECLIURL and OVERWRITEHOST.
Enter the address for the Cloudflare Tunnel, configured above in Value, for example nextcloud.example.com.
With the Cloudflare connector and Nextcloud installed and configured, in your Cloudflare dashboard, go to Networks and select Tunnels.
The status of the tunnel should be HEALTHY.
Nextcloud should now be reachable via the Cloudflare Tunnel address, nextcloud.example.com in this example, using a HTTPS connection.
Use strong user passwords and configure two-factor authentication for additional security.
Cloudflare offers access policies to restrict access to the application to specific users, emails or authentication methods.
Go to Access, click Add an Application, and select Self-Hosted.
Add your Nextcloud application and the domain you configured in the Cloudflare tunnel.
Click Next.
Create a new policy by entering a Policy Name. Groups can be assigned to this policy or additional rules can be added.
Click Next and Save.
Note: there are additional options for policy configuration, but these are beyond the scope of this tutorial.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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 Discover apps screen. To view the catalog settings, select the Manage Catalogs at the top of the Discover apps screen.
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 does not 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.
This article provides information on installing and using the TrueNAS Syncthing app.
SCALE has two versions of the Syncthing application, the community version in the charts train and a smaller version tested and polished for a safe and supportable experience for enterprise customers in the enterprise train. Community members can install either the enterprise or community version.
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 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 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 Syncthing web UI provides users with easy management and configuration of the application software.
You can allow the app to create a storage volume(s) or use existing datasets created in SCALE. The TrueNAS Syncthing app requires a main configuration storage volume for application information. You can also mount existing datasets for storage volume inside the container pod.
If you want to use existing datasets for the main storage volume, [create any datasets]/scale/scaletutorials/datasets/datasetsscale/ before beginning the app installation process (for example, syncthing for the configuration storage volume). If also mounting storage volume inside the container, create a second dataset named data1. If mounting multiple storage volumes, create a dataset for each volume (for example, data2, data3, etc.).
You can have multiple Syncthing app deployments (two or more Charts, two or more Enterprise, or Charts and Enterprise trains, etc.). Each Syncthing app deployment requires a unique name that can include numbers and dashes or underscores (for example, syncthing2, syncthing-test, syncthing_1, etc.).
Use 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 app are case sensitive. For example, a file named MyData.txt is not the same as mydata.txt file in Syncthing.
If not already assigned, set a pool for applications to use.
Either use the default user and group IDs or create the new user with Create New Primary Group selected. Make note of the UID/GID for the new user.
Go to Apps > Discover Apps and locate the Syncthing charts app widget.
Click on the widget to open the Syncthing details screen.
Click Install to open the Install Syncthing screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields, click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
Accept the default owner user and group ID settings. You can customize your Syncthing charts deployment by adding environment variables but these are not required.
Add the storage volume(s). Either allow the Syncthing app to create the configuration storage volume or use an existing dataset created for this app. To use an existing dataset, select Enable Custom Host Path for Syncthing Configuration Volume, then browse to and select the dataset to populate the field. See Storage Settings for more details on adding existing datasets.
Accept the default port numbers in Networking. See Network Settings below for more information on network settings. Before changing the default port number, see Default Ports for a list of assigned port numbers. When selected, Host Network binds to the default host settings programmed for Syncthing. We recommend leaving this disabled.
Syncthing does not require advanced DNS options. If you want to add DNS options, see Advanced DNS Settings below.
Accept the default resource limit values for CPU and memory or select Enable Pod resource limits to show the CPU and memory limit fields, then enter the new values you want to use for Syncthing. See Resource Configuration Settings below for more information.
Click Install. The system opens the Installed Applications screen with the Syncthing app in the Deploying state. After installation completes the status changes to Running.
Click Web Portal on the Application Info widget to open the Syncthing web portal to begin configuring folders, devices, and other settings.
Secure Syncthing by setting up a username and password.
The following sections provide more detail explanations of the settings found in each section of the Install Syncthing screen.
Accept the default value or enter a name in Application Name field. In most cases use the default name but adding a second application deployment requires a different name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
Accept the defaults in the Configuration settings or enter new user and group IDs. The default value for Owner User ID and Owner Group ID is 568.
Click Add to the right of Syncthing environment to show the Name and Value fields.
For a list of Syncthing environment variables, go to the Syncthing documentation website and search for environment variables. You can add environment variables to the Syncthing app configuration after deploying the app. Click Edit on the Syncthing Application Info widget found on the Installed Application screen to open the Edit Syncthing screen.
You can allow the Syncthing app to create the configuration storage volume or you can create datasets to use for the configuration storage volume and to use for storage within the container pod.
To use existing datasets, select Enable Custom Host Path for Syncthing Configuration Volume to show the Host Path for Syncthing Configuration Volume and Extra Host Path Volumes fields. Enter the host path in Host Path for Syncthing Configuration Volume or browse to and select the dataset an existing dataset created for the configuration storage volume.
Add to the right of Extra Host Path Volumes shows the Mount Path in Pod and Host Path fields.
Enter the data1 dataset in Mount Path in Pod, then enter or browse to the dataset location in Host Path. If you added extra datasets to mount inside the container pod, click Add for each extra host path you want to mount inside the container pod. Enter or browse to the dataset created for the extra storage volumes to add inside the pod.
Accept the default port numbers in Web Port for Syncthing, TCP Port for Syncthing and UDP Port for Syncthing. The SCALE Syncthing chart app listens on port 20910. The default TCP port is 20978 and the default UDP port is 20979. Before changing default ports and assigning new port numbers, 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.
We recommend not selecting Host Network. This binds to the host network.
Syncthing does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.
Accept the default values in Resources Configuration or select Enable Pod resource limits to enter new CPU and memory values. By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container (pod) Syncthing uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.
Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi
After installing and starting the Syncthing application, launch the Syncthing web portal. Go to Actions > Settings and set a user password for the web UI.
The Syncthing web portal 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 listeners, total uptime, sync state, and the device ID and version.
Actions displays a dropdown list of options. Click Advanced to access GUI, LDAP, folder, device, and other settings.
You can manage directional settings for sync configurations, security, encryption, and UI server settings through the Actions options.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
The SCALE Chia app installs the Chia Blockchain architecture in a Kubernetes container. Chia Blockchain is a cryptocurrency ecosystem that uses Proof of Space and Time, and allows users to work with digital money and interact with their assets and resources. Instead of using expensive hardware that consumes exorbitant amounts of electricity to mine crypto, it leverages existing empty hard disk space on your computer(s) to farm crypto with minimal resources.
Before you install the application, you have the option to create the config and plots datasets for the Chia app storage volumes, or you can allow the SCALE to automatically create these storage volumes.
You also have the option to mount datasets inside the container for other Chia storage needs. You can allow SCALE to create these storage volumes, or you can create and name datasets according to your intended use or as sequentially-named datasets (i.e., volume1, volume2, etc.) for each extra volume to mount inside the container.
Create all datasets before you begin the app installation process if using existing datasets and the host path option. See Creating a Dataset for information on correctly configuring the datasets.
To install the SCALE Chia app you:
Log into SCALE, go to Apps, click on Discover Apps, then either begin typing Chia into the search field or scroll down to locate the Chai application widget.
Click on the widget to open the Chia app information screen.
Click Install to open the Install Chia configuration screen.
Application configuration settings are presented in several sections, each explained in Understanding SCALE Chia App Settings below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default value or enter a name in Application Name. Accept the default value in Version.
Select the timezone for your TrueNAS system location from the Timezone dropdown list of options.
Select the service from the Chia Service Mode dropdown list. The default option is Full Node, but you can select Farmer or Harvester. Harvester displays additional settings, each described in Chia Configuration below. Refer to Chia-provided documentation for more information on these services.
You can enter the network address (IP address or host name) for a trusted peer in Full Node Peer now or after completing the app installation. This is the trusted/known or untrusted/unknown server address you want to use in sync operations to speed up the sync time of your Chia light wallet. If not already configured in Chia, you can add this address as a trusted peer in Chia after completing the app installation.
Accept the default values in Chia Port and Farmer Port. You can enter port numbers below 9000, but check the Default Ports list to verify the ports are available. Setting ports below 9000 automatically enabled host networking.
By default, SCALE can create the storage volumes (datasets) for the app.
If you created datasets to use, select Host Path (Path that already exists on the system). Enter or browse to select the mount path for the config and plot datasets created in First Steps and populate the Host Path field for both Data and Plots storage volumes.
Accept the defaults in Resource Configuration or change the CPU and memory limits to suit your use case.
Click Install. The system opens the Installed Applications screen with the SCALE Chia app in the Deploying state. When the installation completes, it changes to Running.
The first time the SCALE Chia app launches, it automatically creates and sets a new private key for your Chia plotting and wallet, but you must preserve this key across container restarts.
To make sure your plots and wallet private key persists (is not lost) across container restarts, save the mnemonic seed created during the app installation and deployment.
On the Installed apps screen, click on the Chia app row, then scroll down to the Workloads widget and the Shell and Logs icons.
Click on the shell icon to open the Choose pod window.
Click Choose to open the Pod shell screen.
To show Chia key file details and the 24 word recovery key, enter /chia-blockchain/venv/bin/chia keys show --show-mnemonic-seed
.
The command should return the following information:
If you loose the keyfile at any time, use this information to recover your account. To copy from the SCALE Pod Shell, highlight the part of the screen you want to copy, then press Ctrl+Insert. Open a text editor like Notepad, paste the information into the file and save it. Back up this file and keep it secured where only authorized people can access it.
Now save this mnemonic-seed phrase to one of the host volumes on TrueNAS. Enter this command at the prompt:
echo type all 24 unique secret words in this command string > /plots/keyfile
Where type all 24 unique secret words in this command string is all 24 words in the mnemonic-seed.
Next, edit the SCALE Chia app to add the key file.
Click Installed on the breadcrumb at the top of the Pod Shell screen to return to the Apps > Installed screen. Click on the Chia app row, then click Edit in the Application Info widget to open the Edit Chia screen.
Click on Chia Configuration on the menu on the right of the screen or scroll down to this section. Click Add to the right of Additional Environments to add the Name and Value fields.
Enter keys in Name and /plots/keyfile in Value.
Scroll down to the bottom of the screen and click Save. The container should restart automatically.
After the app returns to the Running state, you can confirm the keys by returning to the Pod shell screen and entering the /chia-blockchain/venv/bin/chia keys show --show-mnemonic-seed
command again.
If the keys are not identical, edit the Chia app again and check for any errors in the name of values entered.
If identical, the keys file persists for this container.
You can now complete your Chia configuration using either the Chia command line (CLI) or web interface (GUI).
To complete the Chia software and client setup, go to the Chia Crash Course and Chai Getting Started guides and follow the instructions provided. The following shows the simplest option to install the Chia GUI.
Click on the link to the Chia downloads and select the option that fits your operating system environment. This example shows the Windows setup option.
After downloading the setup file and opening the Chia Setup wizard, agree to the license to show the Chia setup options.
Click Next. Choose the installation location.
Click Install to begin the installation. When complete, click Next to show the Chia Setup Installation Complete wizard window. Launch Chia is selected by default. Select the Add the Chia Command Line executable to PATH advanced option if you want to include this. Click Finish.
After the setup completes the Chia web portal opens in a new window where you configure your Chia wallet and farming modes, and other settings to customize Chia for your use case.
Use the Chia Documentation to complete configuration of your Chia software and client.
At this point, you are ready to begin farming Chia.
The CLI process is 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 following sections provide more details on the settings found in each section of the SCALE Install Chia and Edit Chia screens.
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
The Chia Configuration section includes four settings: Timezone, Chia Service Node, Full Node Peer, and Additional Environments.
Select the time zone for the location of the TrueNAS server from the dropdown list.
The Chia Service Node has three options: Full Node, Farmer, and Harvestere. The default Full Node, and Farmer do not have extra settings.
Selecting Harvester shows the required Farmer Address and Farmer Port settings, and CA for the certificate authority for the farmer system. Refer to Chia documentation on each of these services and what to enter as the farmer address and CA.
After configuring Chia in the Chia GUI or CLI, you can edit these configuration settings. You can also create a second SCALE Chia app deployment by repeating the instructions above if you want to create a second app deployment as a Harvester service node.
You can enter the network address (IP address or host name) for a trusted peer in Full Node Peer now or after completing the app installation and setting up the Chia GUI or CLI and configuring the Chia blockchain. Enter the trusted/known or untrusted/unknown server address you want to use in sync operations to speed up the sync time of your Chia light wallet. You can also edit this after the initial app installation in SCALE.
Click Add to the right of Additional Environments to add a Name and Value field. You can add environment variables here to customize Chia, and to make the initial key file persist, survive after a container restart. Click Add for each environment variable you want to add. Refer to Chia documentation for information on environment variables you might want to implement.
Accept the default port numbers in Chia Port and Farmer Port. The SCALE Chai app listens on port 38444 and 38447.
Refer to the TrueNAS default port list for a list of assigned port numbers. To change the port numbers, enter an available number within the range 9000-65535.
You can allow SCALE to create the datasets for Chia plots and configuration storage, or you can create the datasets you want to use as storage volumes for the app or to mount in the container. If manually creating and using datasets, follow the instructions in Creating a Dataset to correctly configure the datasets. Add one dataset named config and the another named plots. If also mounting datasets in the container, add and name these additional storage volumes according to your intended use or use volume1, volume2, etc. for each additional volume.
In the SCALE Chia app Storage Configuration section, select Host Path (Path that already exists on the system) as the Type for the Data storage volume. Enter or browse to and select the location of the existing dataset to populate the Host Path field. Repeat this for the Plots storage volume.
If adding storage volumes inside the container pod, click Add to the right of Additional Volumes for each dataset or ixVolume you want to mount inside the pod.
You can edit the SCALE Chia app after installing it to add additional storage volumes.
The Resources Configuration section allows you to limit the amount of CPU and memory the application can use. By default, this application is limited to use no more than 4 CPU cores and 8 Gibibytes available memory. The application might use considerably less system resources.
Tune these limits as needed to prevent the application from over-consuming system resources and introducing performance issues.
This Community App article provides installation instructions using the legacy TrueNAS SCALE Applications screen. SCALE 23.10 (Cobia) introduces new Installed and Discover screens for applications. See Apps and Applications Screens to learn how to install applications using these screens.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
The DDNS-Updater application is a lightweight universal dynamic 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 container runs as a non-root user.
Make sure to have account credentials ready with the chosen DNS provider before installing the application in TrueNAS.
To grant access to specific user (and group) accounts other than using the default apps user (UID: 568), add a non-root TrueNAS administrative user from Credentials > Local Users and record the UID and GID for this user. Using a non-default user/group account forces permissions changes on any defined data storage for this application.
Have the TRUENAS catalog loaded and community train enabled. To view and adjust the current application catalogs, go to Apps and click Discover Apps > Manage Catalogs.
Go to Apps, click Discover Apps, and locate the DDNS-Updater application widget by typing the first few characters of the application name in the search bar.
Click the application card to see additional details about the application and options to install it.
Click Install to open the DDNS-Updater configuration screen. Application configuration options are presented in several sections. Find specific fields or skip to a particular section with the navigation box in the upper-right corner.
Leave these fields at their default settings. Changing the application version is only recommended when a specific version is required.
Select the timezone that applies to the TrueNAS 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 specific provider.
Enter the domain and host name split between the Domain and Host fields.
For example, populate domain myhostname.ddns.net with ddns.net in Domain and myhostname afer the @ in Host or @myhostname.
Define how often to check IP addresses with Update Period and Update Cooldown Period.
The application also creates
To configure notifications with the Shoutrrr service, click Add and enter the service Address under Shoutrrr Addresses.
Use the Public IP options to define which providers to use for the various DNS, IPv4, and IPv6 public addresses. The default All providers allows for quick app usability but these options can be tuned as needed.
By default, the TrueNAS apps (UID/GID 568) user and group account manages this application.
Entering an alternate UID or GID reconfigures the application to run as that account. When using a custom account for this application, make sure the account is a member of the Builtin_administrators group and that the storage location defined in Storage Configuration has permissions tuned for this account after the application is installed.
By default, this application uses TrueNAS port 30007 to access the application web interface.
Adjust the Web Port integer when a different network port is required. 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 a predefined host path.
By default, this application is limited to use no more than 4 CPU cores and 8 Gibibytes available memory. The application might use considerably less system resources.
Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
Review the configuration settings then click Install for TrueNAS to download and initialize the application.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
Immich is a self-hosted photo and video backup tool.
Immich integrates photo and video storage with a web portal and mobile app. It includes features such as libraries, automatic backup, bulk upload, partner sharing, Typesense search, facial recognition, and reverse geocoding.
TrueNAS SCALE makes installing Immich easy, but you must use the Immich web portal and mobile app to configure accounts and access libraries.
The Immich app in TrueNAS SCALE installs, completes the initial configuration, then starts the Immich web portal. When updates become available, SCALE alerts and provides easy updates.
Before installing the Immich app in SCALE, review their Environment Variables documentation and to see if you want to configure any during installation. You can configure environment variables at any time after deploying the application.
SCALE does not need advance preparation.
You can allow SCALE to create the datasets Immich requires automatically during app installation.
Or before beginning app installation, create the datasets to use in the Storage Configuration section during installation.
Immich requires seven datasets: library, pgBackup, pgData, profile, thumbs, uploads, and video.
You can organize these as one parent with seven child datasets, for example
To install the Immich application, go to Apps, click Discover Apps, either begin typing Immich into the search field or scroll down to locate the Immich application widget.
Click on the widget to open the Immich application details screen.
Click Install to open the Immich application configuration screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
Accept the default value in Timezone or change to match your local timezone.
Timezone is only used by the Immich exiftool
microservice if it cannot be determined from the image metadata.
Accept the default port in Web Port.
Immich requires seven storage datasets. You can allow SCALE to create them for you, or use the dataset(s) created in First Steps. Select the storage options you want to use for Immich Uploads Storage, Immich Library Storage, Immich Thumbs Storage, Immich Profile Storage, Immich Video Storage, Immich Postgres Data Storage, Immich Postgres Backup Storage. Select ixVolume (dataset created automatically by the system) in Type to let SCALE create the dataset or select Host Path to use the existing datasets created on the system.
Accept the defaults in Resources or change the CPU and memory limits to suit your use case.
Click Install. The system opens the Installed Applications screen with the Immich app in the Deploying state. When the installation completes it changes to Running.
Click Web Portal on the Application Info widget to open the Immich web interface to set up your account and begin uploading photos. See Immich Post Install Steps for more information.
Go to the Installed Applications screen and select Immich from the list of installed applications. Click Edit on the Application Info widget to open the Edit Immich screen. The settings on the edit screen are the same as on the install screen. You cannot edit Storage Configuration paths after the initial app install.
Click Update to save changes. TrueNAS automatically updates, recreates, and redeploys the Immich container with the updated environment variables.
The following sections provide more detailed explanations of the settings found in each section of the Install Immich screen.
Accept the default value or enter a name in the Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
You can accept the defaults in the Immich Configuration settings, or enter the settings you want to use.
Accept the default setting in Timezone or change to match your local timezone.
Timezone is only used by the Immich exiftool
microservice if it cannot be determined from the image metadata.
You can enter a Public Login Message to display on the login page, or leave it blank.
Accept the default port numbers in Web Port. The SCALE Immich app listens on port 30041.
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.
You can install Immich using the default setting ixVolume (dataset created automatically by the system) or use the host path option with datasets created before installing the app.
Select Host Path (Path that already exists on the system) to browse to and select the datasets.
Accept the default values in Resources Configuration or enter new CPU and memory values By default, this application is limited to use no more than 4 CPU cores and 8 gibibytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container Immich uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m, which means Immich is able to use 4 cores.
Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 4G or 123Mi.
Systems with compatible GPU(s) display devices in GPU Configuration. Use the GPU Resource dropdown menu(s) to configure device allocation.
See Allocating GPU for more information about allocating GPU devices in TrueNAS SCALE.
TrueNAS works differently from Immich’s original documentation for database backup and recovery. You can read how to backup and restore the Immich database here
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
Jellyfin is a volunteer-built media solution that puts you in control of managing and streaming your media.
Jellyfin enables you to collect, manage, and stream media files. Official and third-party Jellyfin streaming clients are available on most popular platforms.
TrueNAS SCALE makes installing Jellyfin easy, but you must use the Jellyfin web portal to configure accounts and manage libraries.
The Jellyfin app in TrueNAS SCALE installs, completes the initial configuration, then starts the Jellyfin web portal. When updates become available, SCALE alerts and provides easy updates.
You can configure environment variables at any time after deploying the application.
SCALE does not need advance preparation.
You can allow SCALE to create the datasets Jellyfin requires automatically during app installation.
Or before beginning app installation, create the datasets to use in the Storage Configuration section during installation.
Jellyfin requires two datasets: config and cache.
You can organize these as one parent with two child datasets, for example
If you want to run the application with a user or group other than the default apps (568) user and group, create them now.
To install the Jellyfin application, go to Apps, click Discover Apps, either begin typing Jellyfin into the search field or scroll down to locate the Jellyfin application widget.
Click on the widget to open the Jellyfin application details screen.
Click Install to open the Jellyfin application configuration screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
Accept the defaults in Jellyfin Configuration, User and Group Configuration, and Network Configuration or change to suit your use case. You must select Host Network under Network Configuration if using DLNA.
Jellyfin requires three app storage datasets. You can allow SCALE to create them for you, or use the dataset(s) created in First Steps. Select the storage options you want to use for Jellyfin Config Storage and Jellyfin Cache Storage. Select ixVolume (dataset created automatically by the system) in Type to let SCALE create the dataset or select Host Path to use the existing datasets created on the system.
Jellyfin also requires a dataset or emptyDir for Jellyfin Transcodes Storage. Select ixVolume (dataset created automatically by the system) in Type to let SCALE create the dataset, select Host Path to use an existing dataset created on the system, or select emptyDir to use a temporary storage volume on the disk or in memory.
Solid state storage is recommended for config and cache storage. Do not use the same spinning disk device for both cache and config and media storage libraries.
Mount one or more media libraries using Additional Storage. Click Add to enter the path(s) on your system. Select Host Path (Path that already exists on the system) or SMB Share (Mounts a persistent volume claim to a SMB share) in Type. Enter a Mount Path to be used within the Jellyfin container. For example, the local Host Path /mnt/tank/video/movies could be assigned the Mount Path /media/movies. Define the Host Path or complete the SMB Share Configuration fields. See Mounting Additional Storage below for more information.
Accept the defaults in Resource Configuration or change the CPU and memory limits to suit your use case.
Click Install.
A container launches with root privileges to apply the correct permissions to the Jellyfin directories. Afterward, the Jellyfin container runs as a non-root user (default: 568). Configured storage directory ownership is changed if the parent directory does not match the configured user.
The system opens the Installed Applications screen with the Jellyfin app in the Deploying state. When the installation completes it changes to Running.
Click Web Portal on the Application Info widget to open the Jellyfin web interface initial setup wizard to set up your admin account and begin administering libraries.
Go to the Installed Applications screen and select Jellyfin from the list of installed applications. Click Edit on the Application Info widget to open the Edit Jellyfin screen. The settings on the edit screen are the same as on the install screen. You cannot edit Storage Configuration paths after the initial app install.
Click Update to save changes. TrueNAS automatically updates, recreates, and redeploys the Jellyfin container with the updated environment variables.
The following sections provide more detailed explanations of the settings found in each section of the Install Jellyfin screen.
Accept the default value or enter a name in the Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
You can accept the defaults in the Jellyfin Configuration settings, or enter the settings you want to use.
You can enter a Published Server URL for use in UDP autodiscovery, or leave it blank.
If needed, click Add to define Additional Environment Variables, see the Jellyfin Configuration documentation for options.
You can accept the default value of 568 (apps) in User ID and Group ID or define your own.
This user and group are used for running the Jellyfin container only and cannot be used to log in to the Jellyfin web interface. Create an admin user in the Jellyfin initial setup wizard to access the UI.
Select Host Network under Network Configuration if using DLNA, to bind network configuration to the host network settings. Otherwise, leave Host Network unselected.
Accept the default port numbers in Web Port. The SCALE Jellyfin app listens on port 30013.
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.
You can install Jellyfin using the default setting ixVolume (dataset created automatically by the system) or use the host path option with datasets created before installing the app.
Select Host Path (Path that already exists on the system) to browse to and select the datasets.
For Jellyfin Transcodes Storage, choose ixVolume, Host Path, or emptyDir (Temporary directory created on the disk or in memory). An emptyDir uses ephemeral storage either on the disk or by mounting a tmpfs (RAM-backed filesystem) directory for storing transcode files.
Click Add next to Additional Storage to add the media storage path(s) on your system.
Select Host Path (Path that already exists on the system) or SMB Share (Mounts a persistent volume claim to a SMB share) in Type. You can select iXvolume (dataset created automatically by the system) to create a new library dataset, but this is not recommended.
Mounting an SMB share allows data synchronization between the share and the app. The SMB share mount does not include ACL protections at this time. Permissions are currently limited to the permissions of the user that mounted the share. Alternate data streams (metadata), finder colors tags, previews, resource forks, and MacOS metadata is stripped from the share along with filesystem permissions, but this functionality is undergoing active development and implementation planned for a future TrueNAS SCALE release.
For all types, enter a Mount Path to be used within the Jellyfin container.
For example, the local Host Path
Accept the default values in Resources Configuration or enter new CPU and memory values By default, this application is limited to use no more than 4 CPU cores and 8 gibibytes available memory.
To customize the CPU and memory allocated to the container Jellyfin uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m, which means Jellyfin is allowed to use 4 CPU cores.
Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 4G.
Systems with compatible GPU(s) display devices in GPU Configuration. Use the GPU Resource dropdown menu(s) to configure device allocation.
See Allocating GPU for more information about allocating GPU devices in TrueNAS SCALE.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
This section has tutorials for using the MinIO apps available for TrueNAS SCALE.
SCALE has two version of the MinIO application. The community version of the S3 application available in the charts train of TRUENAS catalog application. The MinIO Enterprise version of the application is a smaller version of MinIO that is tested and polished for a safe and supportable experience for TrueNAS Enterprise customers. Community members can install either the Enterprise or community version.
MinIO High Performance Object Storage, released under the Apache Licenses v2.0 is an Open Source, Kubernetes Native, and Amazon S3 cloud storage compatible object storage solution. For more on MinIO, see MinIO Object Storage for Kubernetes.
The Minio applications, chart and enterprise train versions, allow users to build high performance infrastructure for machine learning, analytics, and application data workloads.
MinIO supports distributed mode. Distributed mode, allows pooling multiple drives, even on different systems, into a single object storage server. For information on configuring a distributed mode cluster in SCALE using MinIO, see Setting Up MinIO Clustering.
For information on installing and configuring MinIO Enterprise, see Installing MinIO Enterprise.
The instructions in this section cover the basic requirements and instruction on how to install and configure the community MinIO application, charts train version. For instructions on installing the Enterprise version of the MinIO application see Configuring Enterprise MinIO.
Before configuring MinIO, 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:
In the TrueNAS SCALE CLI, use storage filesystem mkdir path="/PATH/TO/minio/data"
to create the /data directory in the MinIO dataset.
In the web UI, create a share (i.e. an SMB share), then log into that share and create the directory.
MinIO uses /data but allows users to replace this with the directory of their choice.
To install the S3 MinIO (community app), go to Apps, click on Discover Apps, then either begin typing MinIO into the search field or scroll down to locate the charts version of the MinIO widget.
Click on the widget to open the MinIO application information screen.
Click Install to open the Install MinIO screen.
Accept the default values for Application Name and Version. The best practice is to keep the default Create new pods and then kill old ones in the MinIO update strategy. This implements a rolling upgrade strategy.
Next, enter the MinIO Configuration settings.
The MinIO application defaults include all the arguments you need to deploy a container for the application.
Enter a name in Root User to use as the MinIO access key. Enter a name of five to 20 characters in length, for example admin or admin1. Next enter the Root Password to use as the MinIO secret key. Enter eight to 40 random characters, for example MySecr3tPa$$w0d4Min10.
Refer to MinIO User Management for more information.
Keep all passwords and credentials secured and backed up.
MinIO containers use server port 9000. The MinIO Console communicates using port 9001.
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 and enter the amount of storage you want to allocate to logging. The default is 5 disks.
Configure the storage volumes. Accept the default /export value in Mount Path. Click Add to the right of Extra Host Path Volumes to add a data volume for the dataset and directory you created above. Enter the /data directory in Mount Path in Pod and the dataset you created in the First Steps section in Host Path.
If you want to create volumes for postgres data and postgres backup, select Postgres Data Volume and/or Postgres Backup Volume to add the mount and host path fields for each. If not set, TrueNAS uses the defaults for each postgres-data and postgres-backup.
Accept the defaults in Advanced DNS Settings.
If you want to limit the CPU and memory resources available to the container, select Enable Pod resource limits then enter the new values for CPU and/or memory.
Click Install when finished entering the configuration settings.
The Installed applications screen displays showing the MinIO application in the Deploying state. It changes to Running when the application is ready to use.
Click Web Portal to open the MinIO sign-in screen.
The following section provide more detailed explanations of the settings found in each section of the Install MinIO configuration screen.
Accept the default value or enter a name in Application Name field. Accept the default version number in Version.
The MinIO Workload Configuration section includes the MinIO update strategy setting that sets how application updates occur.
Select Create new pods then kill old ones to implement a rolling update strategy where the existing container (pod) remains until the update completes, then it is removed. Select Kill existing pods before creating new ones to implement a recreate update strategy where you remove the existing container (pod) and then create a new one. The recommended option is to keep the default and use the the rolling update strategy.
The MinIO Configuration section provides options to set up a cluster, add arguments, credentials, and environment variables to the deployment.
Select Enable Distributed Mode when setting up a cluster of SCALE systems in a distributed cluster.
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.
To create a distributed cluster, click Add to show the Distributed MinIO Instance URI(s) fields for each TrueNAS system (node) IP addresses/host names to include in the cluster. Use the same order across all the nodes.
The app is preconfigured with arguments it needs to deploy a container. Do not enter the server and URL argument earlier versions of the app required.
Enter the name for the root user (MinIO access key) in Root User. Enter a name of five to 20 characters in length. For example admin or admin1. Next enter the root user password (MinIO secret key) in Root Password. Enter eight to 40 random characters. For example MySecr3tPa$$w0d4Min10.
You do not need to enter extra arguments or environment variables to configure the MinIO app.
Accept the default port settings in MinIO Service Configuration. Before changing ports, refer to Default Ports.
Select the optional Enable Log Search API to enable LogSearch API and configure MinIO to use this function. This deploys a postgres database to store the logs. Enabling this option displays the Disk Capacity in GB field. Use this to specify the storage in gigabytes the logs are allowed to occupy.
MinIO storage settings include the option to add mount paths and storage volumes to use inside the container (pod). There are three storage volumes, data, postgres data, and postgres backup. The data volume is the only required storage volume.
Accept the default /export value in Mount Path. Click Add to the right of Extra Host Path Volumes to add a data volume for the dataset and directory you created above. Enter the /data directory in Mount Path in Pod and the dataset you created in the First Steps section above in Host Path.
Of the three volume options, adding the data volume and directory are required. Adding postgres data volumes is optional.
To add host paths for postgress storage volumes, select Enable Host Path for Postgres Data Volume and/or Enable Host Path for Postgres Backup Volumes. SCALE default values for each of these postgres volumes are postgres-data and postgres-backup.
MinIO does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to show the Name and Value fields for a DNS option.
By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container (pod) the MinIO app uses, select Enable Pod resource limits. This adds the CPU Resource Limit and Memory Limit fields. Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
This article applies to the public release of the S3 MinIO community application in the charts train of the TRUENAS catalog.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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, found on the Application Info widget on the Installed applications screen, 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.
When adding a new MinIO deployment, verify your storage settings are correct in the MinIO application configuration. If not set, click Install 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 S3 MinIO charts application in the TRUENAS catalog.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
On TrueNAS SCALE 23.10 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, 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:
In the TrueNAS SCALE CLI, use storage filesystem mkdir path="/PATH/TO/minio/data"
to create the /data directory in the MinIO dataset.
In the web UI, create a share (i.e. an SMB share), then log into that share and create the directory.
MinIO uses /data but allows users to replace this with the directory of their choice.
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.
Configure the MinIO application using the full version Minio charts widget. Go to Apps, click Discover Apps then
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.
Begin on the first node (system) in your cluster.
To install the S3 MinIO (community app), go to Apps, click on Discover Apps, then either begin typing MinIO into the search field or scroll down to locate the charts version of the MinIO widget.
Click on the widget to open the MinIO application information screen.
Click Install to open the Install MinIO screen.
Accept the default values for Application Name and Version. The best practice is to keep the default Create new pods and then kill old ones in the MinIO update strategy. This implements a rolling upgrade strategy.
Next, enter the MinIO Configuration settings.
Select Enable Distributed Mode when setting up a cluster of SCALE systems in a distributed cluster.
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.
To create a distributed cluster, click Add to show the Distributed MinIO Instance URI(s) fields for each TrueNAS system (node) IP addresses/host names to include in the cluster. Use the same order across all the nodes.
The MinIO application defaults include all the arguments you need to deploy a container for the application.
Enter a name in Root User to use as the MinIO access key. Enter a name of five to 20 characters in length, for example admin or admin1. Next enter the Root Password to use as the MinIO secret key. Enter eight to 40 random characters, for example MySecr3tPa$$w0d4Min10.
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 server nodes and have the same credentials.
MinIO containers use server port 9000. The MinIO Console communicates using port 9001.
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 and enter the amount of storage you want to allocate to logging. The default is 5 disks.
You can also configure a MinIO certificate.
Configure the storage volumes. Accept the default /export value in Mount Path. Click Add to the right of Extra Host Path Volumes to add a data volume for the dataset and directory you created above. Enter the /data directory in Mount Path in Pod and the dataset you created in the First Steps section in Host Path.
Accept the defaults in Advanced DNS Settings.
If you want to limit the CPU and memory resources available to the container, select Enable Pod resource limits then enter the new values for CPU and/or memory.
Click Install when finished entering the configuration settings.
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, start the MinIO applications.
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 MINIO_ROOT_USER and MINIO_ROOT_PASSWORD keys you created as environment variables.
Click Web Portal to open the MinIO sign-in screen.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
The TrueNAS SCALE Netdata app provides an easy way to install and access the Netdata infrastructure monitoring solution. SCALE deploys the Netdata app in a Kubernetes container using the Helm package manager. After successfully deploying the app, you can access the Netdata web portal from SCALE. The Netdata web portal opens on the local dashboard, and where you can create new dashboards, add plugins, metric databases, physical and virtual systems, containers, and other cloud deployments you want to monitor. The portal also provides access to the Netdata Cloud sign-in screen.
The SCALE Netdata app does not require advance preparation.
You can allow SCALE to automatically create storage volumes for the Netdata app or you can create specific datasets to use for configuration, cache, and library storage and extra storage volumes in the container pod. If using specific datasets, create these before beginning the app installation.
The administrator account must have sudo permissions enabled. To verify, go to Credentials > Local User. Click on the administrator user (e.g., admin), then click Edit. Scroll down to the sudo permissions. Select either Allow all sudo commands to permit changes after entering a password (not recommended in this instance) or Allow all sudo commands with not password to permit changes without requiring a password. If you upgraded from Angelfish or early releases of Bluefin that do not have an admin user account, see Creating an Admin User Account for instructions on correctly creating an administrator account with the required permissions.
You can create a Netdata account before or after installing and deploying the Netdata app.
To install the Netdata application, go to Apps, click on Discover Apps, then either scroll down to the Netdata app widget or begin typing Netdata in the search field to filter the list to find the Netdata app widget.
Click on the widget to open the Netdata application details screen.
Click Install to open the Install Netdata screen.
Application configuration settings presented in several sections, are explained in Understanding Netdata Settings below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
Accept the default settings in Netdata Configuration and the default port in Node Port to use for Netdata UI. The SCALE Netdata app uses the default port 20489 to communicate with Netdata and show the Netdata local dashboard.
Make no changes in the Storage section to allow SCALE to create the storage volumes for the app, or to use datasets created for Netdata configuration storage, select Enable Host Path for Netdata to show the Host Path for Netdata Configuration settings.
Enter or browse to select the dataset created for Netdata configuration storage to populate the mount path. If using datasets created for cache and library storage, enable these options, then enter or browse to the datasets for each.
Accept the default settings in Advanced DNS Settings.
Accept the default values in Resources Limits or select Enable Pod Resource limits to show resource configuration options for CPU and memory and enter new values to suit your use case.
Click Install. The system opens the Installed Applications screen with the Netdata app in the Deploying state. When the installation completes it changes to Running.
Click Web Portal on the Application Info widget to open the Netdata web interface showing the local dashboard.
The following sections provide more detailed explanations of the settings found in each section of the Install Netdata screen.
Accept the default value or enter a name in Application Name. In most cases use the default name, but if adding a second deployment of the application you must change the name.
Accept the default version number in Version. When a new version becomes available, the application shows an update badge on the Installed Applications screen and adds Update buttons to the Application Info widget and the Installed applications screen.
You can accept the defaults in the Netdata Configuration settings or enter the settings you want to use.
Click Add to the right of Netdata image environment to display the environment variable Name and Value fields. Netdata does not require using environment variables to deploy the application but you can enter any you want to use to customize your container.
The SCALE Netdata app uses port 20489 to communicate with Netdata and open the web portal. Netdata documentation states it uses 19999 as the default port, but it recommends restricting access to this for security reasons. 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.
SCALE defaults to automatically creating storage volumes for Netdata without enabling the host path options.
To create and use datasets for the Netdata configuration, cache, and library storage or extra storage volumes inside the container pod, first create these datasets. Go to Datasets and create the datasets before you begin the app installation process. See Add Datasets for more information. Select Enable Host Path for Netdata to show the volume mount path field to add the configuration storage dataset.
Enter or browse to select the dataset and populate the mount path field. To use datasets created for cache and library storage volumes, first enable each option and then enter or browse to select the datasets tp populate the mount path fields for each.
If you want to add storage volumes inside the container pod for other storage, click Add to the right of Extra Host Path Volumes for each storage volume (dataset) you want to add.
You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings.
The default DNS Configuration is sufficient for a basic installation. To specify additional DNS options, click Add to the right of DNS Options to add the DNS Option Name and Option Value fields.
Accept the default values in Resources Limits or select Enable Pod Resource limits to show CPU and memory resource configuration options.
By default, the application is limited to use no more than four CPU cores and eight gigabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container (pod) Netdata uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.
Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi.
After deploying the SCALE Netdata app click on Web Portal to open the Netdata agent local dashboard. This Netdata dashboard provides a system overview of CPU usage and other vital statistics for the TrueNAS server connecting to Netdata.
The Netdata System Overview dashboard displays a limited portion of the reporting capabilities. Scroll down to see more information or click on a listed metric on the right side of the screen to show the graph and reporting on that metric. Click the other tabs at the top left of the dashboard to view other dashboards for nodes, alerts, anomalies, functions, and events. You can add your own Netdata dashboards using Netdata configuration documentation to guide you. Click on the Nodes tab to better understand the differences between the Netdata agent and Netdata Cloud service reporting. The Netdata Cloud monitors your cloud storage providers added to Netdata.
Click Sign In to open the Netdata Cloud sign-in screen.
Use the Netdata-provided documentation to customize Netdata dashboards to suit your use case and monitoring needs.
This Community App article provides installation instructions using the legacy TrueNAS SCALE Applications screen. SCALE 23.10 (Cobia) introduces new Installed and Discover screens for applications. See Apps and Applications Screens to learn how to install applications using these screens.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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.
If you are creating a user account to manage this application, create the user with sudo permissions enabled, or make sure the local administrator account has sudo permissions enabled. If creating a new user, add this user to the dataset permissions.
If you want to use a certificate for this application, create a new self-signed CA and certificate, or import the CA and create the certificate if using one already configured for Nextcloud. A certificate is not required to deploy the application.
Set up an account with Nextcloud if you don’t already have one. Enter this user account in the application configuration.
In this procedure you:
Add the storage Nextcloud uses
Install the Nextcloud app in SCALE
Nextcloud needs five datasets. A primary dataset for the application (nextcloud) with four child datasets. The four child datasets are named and used as follows:
SCALE 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 app 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, select Apps as the Dataset Preset. Click Advanced Options to make any other setting changes you want to make, and click Save. When prompted, select Return to Pool List.
Next, select the nextcloud dataset, click Add Dataset to add the first child dataset. Enter data in Name and select Apps as the Dataset Preset. Click Advanced Options to 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 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.
Set the pool SCALE applications use. If you have not installed an application yet, click Settings, select Choose Pool to open the Choose a pool for Apps dialog. Enter or select the name of the pool where you created the Nextcloud datasets from the Pools dropdown list and then click Choose to set the pool for all applications.
When set, the Installed Applications screen displays Apps Service Running on the top screen banner.
Click Discover Apps and then locate the Nextcloud app. Change the Sort to App Name, then type Nextcloud in the search field to display the app widget.
Click on the widget to open the Nextcloud details screen, then click Install. If this is the first application installed, SCALE displays a dialog about configuring apps.
Click Confirm then Agree to close the dialog and open the Nextcloud details screen opens.
Click Install to open the Install Nextcloud wizard.
Enter a name for the app in Application Name if you want to change what displays or have multiple Nextcloud app deployments on your system. This example uses the default nextcloud.
Scroll down to or click on Nextcloud Configuration to show the app configuration settings. For a basic installation you can leave the default values in all settings except Username and Password.
a. (Optional) Click in the Certificate Configuration field and select the certificate for Nextcloud if already created and using a certificate.
b. Enter the Nextcloud username and password created in the Before You Begin section or existing Nextcould user account credentials. This example uses admin as the user.
TrueNAS populates Nextcloud host with the IP address for your TrueNAS server and Nextcloud data directory populates with the correct path.
Select Install ffmpeg to automatically install the utility FFmpeg 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. Select Enable Host Path for Nextcloud Data Volume, then browse to and select the nextcloud/data dataset to populate the Host Path for Nextcloud Data Volume field.
b. Click Add to display the Mount Path in Pod and Host Path fields. Enter or browse to select the host path for the nextcloud/opt dataset to populate the Host Path field, then enter the path in the Mount Path in Pod field. 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 Postgres 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. The Installed screen displays with the nextcloud app in the Deploying state. It changes to Running when ready to use. Click Web Portal on the Application Info widget to open the Nextcloud web portal sign-in screen.
If the app does not deploy, add the www-data user and group to the /nextcloud dataset but do not set recursive. Stop the app before editing the ACL permissions for the datasets.
Next, add the www-data user and group to the /nextcloud/data dataset. You can set this to recursive, but it is not necessary. To do this:
This Community App article provides installation instructions using the legacy TrueNAS SCALE Applications screen. SCALE 23.10 (Cobia) introduces new Installed and Discover screens for applications. See Apps and Applications Screens to learn how to install applications using these screens.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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 before you begin installing this container. To create a directory, open the TrueNAS SCALE CLI and enterstorage filesystem mkdir path="/PATH/TO/DIRECTORY"
.
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/.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
Prometheus is a monitoring platform that collects metrics from targets it monitors. Targets are system HTTP endpoints configured in the Prometheus web UI. Prometheus is itself an HTTP endpoint so it can monitor itself.
Prometheus collects and stores metrics such as time series data. Information stored is time-stamped at the point when it is recorded. Prometheus uses key-value pairs called labels to differentiate characteristics of what is measured.
Use the Prometheus application to record numeric time series. Also use it to diagnose problems with the monitored endpoints when there is a system outage.
TrueNAS SCALE makes installing Prometheus easy, but you must use the Prometheus web portal to configure targets, labels, alerts, and queries.
The Prometheus app in SCALE installs, completes the initial configuration, then starts the Prometheus Rule Manager. When updates become available, SCALE alerts and provides easy updates.
Before installing the Prometheus app in SCALE, review their Configuration documentation and list of feature flags and environment variables to see if you want to include any during installation. You can configure environment variables at any time after deploying the application.
SCALE does not need advance preparation.
If not using the default user and group to manage the application, create a new user (and group) and take note of the IDs.
You can allow SCALE to create the two datasets Prometheus requires automatically during app installation. Or before beginning app installation, create the datasets named data and config to use in the Storage Configuration section during installation.
To install the Prometheus application, go to Apps, click Discover Apps, either begin typing Prometheus into the search field or scroll down to locate the Prometheus application widget.
Click on the widget to open the Prometheus application details screen.
Click Install to open the Prometheus application configuration screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
Accept the default value in Retention Time or change to suit your needs. Enter values in days (d), weeks (w), months (m), or years (y). For example, 15d, 2w, 3m, 1y.
Enter the amount of storage space to allocate for the application in Retention Size. Valid entries include integer and suffix, for example: 100MB, 10GB, etc.
You can add arguments or environment variables to customize your installation but these are not required. To show the Argument entry field or the environment variable Name and Value fields, click Add for whichever type you want to add. Click again to add another argument or environment variable.
Accept the default port in API Port. Select Host Network to bind to the host network, but we recommend leaving this disabled.
Prometheus requires two storage datasets. You can allow SCALE to create these for you, or use the datasets named data and config created before in First Steps. Select the storage option you want to use for both Prometheus Data Storage and Prometheus Config Storage. Select ixVolume in Type to let SCALE create the dataset or select Host Path to use the existing datasets created on the system.
Accept the defaults in Resources or change the CPU and memory limits to suit your use case.
Click Install. The system opens the Installed Applications screen with the Prometheus app in the Deploying state. When the installation completes it changes to Running.
Click Web Portal on the Application Info widget to open the Prometheus web interface to begin configuring targets, alerts, rules and other parameters.
The following sections provide more detailed explanations of the settings found in each section of the Install Prometheus screen.
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
You can accept the defaults in the Prometheus Configuration settings, or enter the settings you want to use.
Accept the default in Retention Time or change to any value that suits your needs. Enter values in days (d), weeks (w), months (m), or years (y). For example, 15d, 2w, 3m, 1y.
Retention Size is not required to install the application. To limit the space allocated to retain data, add a value such as 100MB, 10GB, etc.
Select WAL Compression to enable compressing the write-ahead log.
Add Prometheus environment variables in SCALE using the Additional Environment Variables option. Click Add for each variable you want to add. Enter the Prometheus flag in Name and desired value in Value. For a complete list see Prometheus documentation on Feature Flags.
Accept the default port numbers in API Port. The SCALE Prometheus app listens on port 30002.
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.
We recommend not selecting Host Network. This binds to the host network.
You can install Prometheus using the default setting ixVolume (dataset created automatically by the system) or use the host path option with the two datasets created before installing the app.
Select Host Path (Path that already exists on the system) to browse to and select the data and config datasets. Set Prometheus Data Storage to the data dataset path, and Prometheus Config Storage to the config dataset path.
Accept the default values in Resources Configuration or enter new CPU and memory values By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container (pod) Prometheus uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.
Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi.
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.
You do not need this application to schedule or run rsync tasks from the Data Protections screen using the Rsync Task widget.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
This application is an open source server that provides fast incremental file transfers. When installed, the Rsync Daemon application provides the server function to rsync clients given the server information and ability to connect.
The before installing the Rsync Daemon application (rsyncd) add a dataset the application can use for storage.
To install this application, go to Apps, click on Discover Apps, then either begin typing rsync into the search field or scroll down to locate the Rsync Daemon application widget.
Click on the widget to open the application Rsync Daemon information screen.
Click Install to open the Install Rsync Daemon configuration screen.
Accept the default value or enter a name in Application Name.
Accept the Network Configuration default port number the Rsync app listens on.
Add and configure at least one module. A module creates an alias for a connection (path) to use rsync with. Click Add to display the Module Configuration fields. Enter a name and specify the path to the dataset this module uses for the rsync server storage. Leave Enable Module selected. Select the type of access from the Access Mode dropdown list. Accept the rest of the module setting defaults. To limit clients that connect, enter IP addresses in Hosts Allow and Hosts Deny.
Accept the default for the rest of the settings.
Accept the default values in Resources Configuration or enter the CPU and memory values for the destination system.
Click Save.
The Installed applications displays with the app in the Deploying state until the installation completes, then it changes to Running.
The following sections provide more detailed explanations of the settings found in each section of the Install Rsync Daemon configuration screen.
The Application Name section includes only the Application Name setting. Accept the default rsyncd or enter a new name to show on the Installed applications screen in the list and on the Application Info widget.
The Rysnc Configuration section Auxiliary Parameters allow you to customize the rsync server deployment. Enter rsync global or module parameters using the Auxiliary Parameters fields.
Click Add to the right of Auxiliary Parameters for each parameter you want to add. Enter the name of the parameter in Parameter and the value for that parameter in Value.
The Network Configuration section includes the Host Network and Rsync Port settings.
Accept the default port number 30026 which is the port the Rsync app listens on. Before changing the port number refer to Default Ports to verify the port is not already assigned. Enter a new port number in Rsync Port.
We recommend that you leave Host Network unselected.
The Module Configuration section includes settings to add and customize a module for the rsync server and to configure the clients allowed or denied access to it. Click Add for each module to add.
There are seven required settings to add a module and four optional settings.
Module Name is whatever name you want to give the module and is an alias for access to the server storage path. A name can include upper and lowercase letters, numbers, and the special characters underscore (_), hyphen (-) and dot (.). Do not begin or end the name with a special character.
Enable Module, selected by default, allows the list client IP addresses added to connect to the server after the app is installed and started.
Use optional Comment to enter a description that displays next to the module name when clients obtain a list of available modules. Default is to leave this field blank.
Enter or browse to the location of the dataset to use for storage for this module on the rsync server in Host Path.
Select the access permission for this storage path from the Access Mode dropdown list. Options are Read Only, Read Write, and Write Only.
Enter a number in Max Connections for the number of client connections to allow. The default, 0, allows unlimited connections to the rsync server.
Accept the UID (user ID) and GID (group ID) default 568. If you create an administration user and group to use for this module in this application, enter that UID/GID number in these fields.
Use Hosts Allow and Hosts Deny to specify IP addresses for client systems that can to connect to the rsync server through this module. Enter multiple IP addresses separated by a comma and space between entries in the field. Leave blank to allow all or deny hosts.
Use the Auxiliary Parameters to enter parameters and their values to further custiize the module. Do not enter parameters already available as the settings included in this section. You can specify rsync global or module parameters using the module Auxiliary Parameters fields.
By default, the rsync daemon will allow access to everything within the dataset that has been specified for each module, without authentication. In order to set up password authentication you needs to add two auxilary parameters for the module:
Parameter: “auth users” Value: comma separated list of usernames
Parameter: “secrets file” Value: path to the rsyncd.secrets file
You will have to place the file inside your module dataset and use the value:
“/data/
The file will have to be chmod 600 and owned by root:root in order for the rsync daemon to accept it for authentication.
The file should contain list of username:password in plaintext, one user per line: admin:password1234 user:password5678
The Resources Configuration section allows you to limit the amount of CPU and memory the application can use. By default, this application is limited to use no more than 4 CPU cores and 8 Gibibytes available memory. The application might use considerably less system resources.
Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
This Community App article provides installation instructions using the legacy TrueNAS SCALE Applications screen. SCALE 23.10 (Cobia) introduces new Installed and Discover screens for applications. See Apps and Applications Screens to learn how to install applications using these screens.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
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.
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.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
The new TFTP Server application provides Trivial File Transfer Protocol (TFTP) server functions. The TFTP Server application is a lightweight TFTP-server container in TrueNAS SCALE. It is not intended for use as a standalone container.
The app runs as root and drops privileges to the tftp (9069) user for the TFTP service. Every application start launches a container with root privileges. This checks the parent directory permissions and ownership. If it finds a mismatch, the container applies the correct permissions to the TFTP directories. If Allow Create is selected, the container also checks and chmods TFTP directories to 757 or to 555 if not checked. Afterwards, the TFTP container runs as root user, dropping privileges to the tftp (9069) user for the TFTP service.
Configure your DHCP server for network boot to work.
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.
You can install the application using all default settings, or you can customize setting to suit your use case.
To install the TFTP Server app, go to Apps, click Discover Apps. Either begin typing TFTP into the search field or scroll down to locate the TFTP Server application widget.
Click on the widget to open the *TFTP Server information screen.
Click Install to open the TFTP Server configuration screen.
Application configuration settings are presented in several sections. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
After accepting or changing the default settings explained in the sections below, click Install to start the installation process. The TFTP Server application displays on the Installed applications screen when the installation completes.
Accept the default values or enter a name in Application Name. Accept the default Version.
Select the location of the TrueNAS server in Timezone.
Select Allow Create to allow creating new files. This sets CREATE to 1 and MAPFILE to "". This changes the permissions of the tftpboot directory to 757, otherwise the tftpboot directory permissiong is 555.
Click Add to the right of Additional Environmental Variables to display the Name and Value fields. Enter the name as shown in the environment variables table below. Do not enter variables that have setting fields or the system displays an error.
When selected, Host Network sets the app to use the default port 69, otherwise the default port is 30031.
To change the default port number, clear the Host Network checkmark to display the TFTP Port field. Enter a new port number in TFTP Port within the range 9000-65535. Refer to the TrueNAS default port list for a list of assigned port numbers.
Storage sets the path to store TFTP boot files. The default storage type is ixVolume (Dataset created automatically by the system) where the system automatically creates a dataset named tftpboot. Select Host Path (Path that already exists on the system) to show the Host Path field. Enter or browse to select a dataset you created on the system for the application to use.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
The WebDAV application is a set of extensions to the HTTP protocol that allows users to collaboratively edit and manage files on remote web servers. It 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.
To grant access to a specific user (and group) other than the default for the webdav user and group (666), add a new non-root administrative user and take note of the UID and GID for this user.
If you want to create a dataset to use for the WebDAV application share(s), create it before you install the application.
To install the application, you can accept the default values or customize the deployment to suit your use case. You create the WebDAV share as part of the application installation.
To install the WebDAV application, go to Apps, click Discover Apps, then either begin typing WebDAV into the search field or scroll down to locate the WebDAV application widget.
Click on the widget to open the WebDAV information screen.
Click Install to open the Install WebDAV configuration screen.
Application configuration settings are presented in several sections. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the defaults in Application Name and Version.
Accept the defaults or customize the settings in WebDAV Configuration. Accept the default authentication setting No Authentication or to require entering authentication credentials, select Basic Authentication as the type. The application includes all the setting fields you need to install and deploy the container, but you can add additional environment variables to further configure the container.
The default network protocol is HTTP and uses the port 30035. To use HTTPS and add encryption to the web traffic, clear the checkmark in Enable HTTP and select Enable HTTPS. HTTPS uses port 30035 and adds the Certificate field. The default certificate is 0.
We recommend not selecting Host Network as this binds to the host network.
Create at least one share in Storage Configuration. Click Add to display the share settings. Enable the share is selected by default. It enables the share at start (when the app starts). Enter a name using lower or uppercase letters and or numbers. Names can include the underscore (_) or dash (-).
Accept the default Resource Configuration, or enter the CPU and memory settings you want to apply to the WebDAV application container.
After configuring the container settings, click Install to save the application configuration, deploy the app, and make the share(s) accessible.
After the installation completes, the application displays on the Installed applications screen.
The WebDAV widget on the Discover and WebDAV information screens includes the Installed badge.
Accept the default values in Application Name and Version. If you want to change the application name, enter a new name.
WebDAV configuration settings include the type of share authentication to use, none or basic. No Authentication means any system can discover TrueNAS and access the data shared by the WebDAV application share, so this is not recommended. Basic Authentication adds the Username and Password fields and provides some basic security.
The WebDAV application configuration includes all the settings you need to install the Docker container for the app. You can use the Docker container environment variables listed in the table below to further customize the WebDAV Docker container.
The default user and group for WebDAV is 666. To specify a different user, create the user and group before installing the application, then enter the user ID (UID) and group ID (GID) in the fields for these settings.
The container for the WebDAV app has Enable HTTP selected by default. The port for HTTP is 30034.
To add encryption to the web traffic between clients and the server, clear the checkmark in Enable HTTP and select Enable HTTPS. This changes the default port in HTTPS Port to 30035, and adds a system Certificate.
The default certificate is 0. You can use the default as the Certificate if no other specific certificate is available.
Create one or more shares in the Storage Configuration section. For the application to work, create at least one share. Click Add for each share you want to create. Each share must have a unique name.
To add a WebDAV share to the application, click Add to the right of Shares in the Storage Configuration section.
Enter a name in Share Name. The name can have upper and lowercase letters and numbers. It can include an underscore (_) and/or a dash (-).
Enter share purpose or other descriptive information about the share in Description. This is not required.
Enter or browse to the Host Path location for the where the app adds the WebDAV share. If you created a dataset before installing the app, you can browse to it here.
Select Read Only to disable write access to the share. When selected, data accessed by clients cannot be modified.
Select Fix Permissions to change the Host Path file system permissions. When enabled, 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. Fix Permissions 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 deployed with Fix Permissions enabled, it 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.
By default, this application is limited to use no more than 4 CPU cores and 8 Gibibytes available memory. The application might use considerably less system resources.
Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
At the end of the installation 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.
Community applications are created and maintained by members of the TrueNAS community. Similarly, community members actively maintain application articles in this section. Click Edit Page in the top right corner to propose changes to this article.
WG Easy is the easiest way to install and manage WireGuard on any Linux host. The application is included in the Community catalog of applications.
WG EASY is a Docker image designed to simplify setting up and managing WireGuard connections. This app provides a pre-configured environment with all the necessary components and a web-based user interface to manage VPN connections.
WG Easy does not require advanced preparation before installing the application.
To install the WG Easy application, go to Apps, click Discover Apps, then either begin typing WG Easy into the search field or scroll down to locate the WG Easy application widget.
Click on the widget to open the WG Easy application information screen.
Click Install to open the WG Easy application configuration screen. Application configuration settings are presented in several sections. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
After installing WG Easy the app displays on the Installed screen.
Click Web PortaL on the Application Info widget to open the WG Easy web interface where you can add a new client.
Accept the default value or enter a name in Application Name field. Accept the default version number in Version.
You can accept the defaults in the Configuration settings, or enter the configuration settings you want to use.
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 or change the value to the number of seconds you want to keep the session alive. When set to zero, connections are not kept alive. Alternate value to use 25.
Accept the default setting for WireGuard (1420) in Clients MTU or enter a new value.
Accept the default IPs in Clients IP Address Range and Clients DNS Server or enter the IP addresses the client uses. If not provided, the default value 1.1.1.1 is used.
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.
You can install WG Easy using the default settings or enter your own values to customize the 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 a preconfigured 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.
WG Easy does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to show the fields for option name and value.
Accept the default values in Resources Configuration or select Enable Pod resource limits to show the fields to enter new CPU and memory values for the destination system.
Enter CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.
Accept the default value 8Gi, or enter the memory limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi
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 EnterpriseTrueNAS applications expand the capabilities of your system by adding third-party software but can add significant risk to system stability and security. We do not recommend deploying 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. Only install applications with the assistance of 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 SMB is using) might fail to deploy. The 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 are found in Apps > Settings > Advanced Settings.
The Custom App button starts the configuration wizard where users can install applications not included in the approved application catalog. 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 storage, user, or other configuration requirements ready before starting the wizard. You should have access 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 might 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 a node port to be greater than 9000. Refer to the Default Ports for a list of used and available ports before changing default port assignments.
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 EnterpriseThe instructions in this article apply to the Official TrueNAS Enterprise MinIO application. This smaller version of MinIO is 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 available in the Community Apps catalog.
The Enterprise MinIO application is tested and verified as an immutable target for Veeam Backup and Replication.
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 members can add and use the MinIO Enterprise app or the default community version.
If your system has active sharing configurations (SMB, NFS, iSCSI), disable them in System Settings > Services before adding and configuring the MinIO application. Start any sharing services after MinIO completes the installation and starts.
This basic procedure covers the required MinIO Enterprise app settings. It does not provide instructions for optional settings.
To install the Minio Enterprise app, go to Apps, click on Discover Apps, then scroll down to locate the enterprise version of the Minio widget.
Click on the MinIO Official Enterprise widget to open the MinIO information screen.
Click Install to open the Install MinIO configuration screen.
Accept the defaults in Application Name or enter a name for your MinIO application deployment.
Accept the default in Version, which populates with the current MinIO version. SCALE displays update information on the Installed application screen when an update becomes available.
Enter credentials to use as the MinIO administration user. If you have existing MinIO credentials, enter these or create new login credentials for the first time you log into MinIO. The Root User is the equivalent of the MinIO access key. The Root Password is the login password for that user or the MinIO secret key.
Accept the User and Group Configuration settings default values for MinIO Enterprise. If you configured SCALE with a new administration user for MinIO, enter the UID and GID.
Scroll down to or click Network Configuration on the list of sections at the right of the screen.
Do not select Host Network.
Select the certificate you created for MinIO from the Certificates dropdown list.
Enter the TrueNAS server IP address and the API port number 30000 as a URL in MinIO Server URL (API). For example, https://ipaddress:30000. Enter the TrueNAS server IP address and the web UI browser redirect port number 30001 as a URL in MinIO Browser Redirect URL. For example, https://ipaddress:30001.
MNMD MinIO installations require HTTPS for both MinIO Server URL and MinIO Browser Redirect URL to verify the integrity of each node. Standard or SNMD MinIO installations do not require HTTPS.
The Certificates setting is not required for a basic configuration but is required when setting up multi-mode configurations and when using MinIO as an immutable target for Veeam Backup and Replication. The Certificates dropdown list includes valid unrevoked certificates, added using Credentials > Certificates.
Enter the TrueNAS server IP address and the API port number 30000 as a URL in MinIO Server URL (API). For example, http://ipaddress:30000. Enter the TrueNAS server IP address and the web UI browser redirect port number 30001 as a URL in MinIO Browser Redirect URL. For example, http://ipaddres:30001.
Scroll down to the Storage Configuration section.
Select the storage type you want to use. ixVolume (Dataset created automatically by the system) is the default storage type. 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 the default /data1. Browse to the dataset location and click on it to populate the Host Path.
If you are setting up a cluster configuration, select Enable Multi Mode (SNMD or MNMD), then click Add in MultiMode Configuration. MinIO recommends using MNMD for enterprise-grade performance and scalability. See the related MinIO articles listed below for SNMD and MNMD configuration tutorials.
The following section provides more detailed explanations of the settings in each section of the Install MinIO configuration screen.
Accept the default value or enter a name in Application Name field. Accept the default version number in Version.
MinIO credentials establish the login credentials for the MinIO web portal and as the MinIO administration user.
If you have existing MinIO credentials, enter them or create new login credentials for the first time you log into MinIO. The Root User is the equivalent of the MinIO access key. The Root Password is the login password for that user or the MinIO secret key.
Enter the name of five to 20 characters in length for the root user (MinIO access key) in Root User. For example admin or admin1.
Enter eight to 40 random characters for the root user password (MinIO secret key) in Root Password. For example, MySecr3tPa$$w0d4Min10.
Accept the default values in User and Group Configuration. If you configured SCALE with a new administration user for MinIO, enter the UID and GID in these fields.
Accept the default port numbers in API Port and Web Port, which are the port numbers MinIO uses to communicate with the app and web portal.
Do not select Host Network.
MinIO does not require a certificate for a basic configuration and installation of MinIO Enterprise, but if installing and configuring multi-mode SNMD or MNMD, you must use a certificate. A SNMD configuration can use the same self-signed certificate created for MNMD, but a MNMD configuration cannot use the certificate created for a SNMD configuration because that certificate would only include the IP address for one system.
Enter the system IP address in URL format followed by the port number for the API separated by a colon in MinIO Server URL (API). For example, https://10.123.12.123:30000. Enter the system IP address in URL format followed by the port number for the web portal separated by a colon in MinIO Browser Redirect URL. For example, https://10.123.12.123:30001.
MNMD MinIO installations require HTTPS for both MinIO Server URL and MinIO Browser Redirect URL to verify the integrity of each node. Standard or SNMD MinIO installations do not require HTTPS.
MinIO storage settings include the option to add storage volumes to use inside the container (pod). The default storage Type is ixVolume *(Dataset created automatically by the system), which adds a storage volume for the application.
To select an existing dataset, select Host Path (Path that already exists on the system) from the Type dropdown list. The Host Path and Mount Path fields display. Enter or browse to select and populate the Host Path field.
Accept the default Mount Path /data1 for the first storage volume for a basic installation.
Click Add to add a block of storage volume settings.
When configuring multi-mode, click Add three times to add three additional datasets created to serve as the drives in these configurations. Multi mode uses four dataset named data1, data2, data3, and data4. Change the Mount Path for the added volumes to /data2, /data3, or /data4, then either enter or browse to select the dataset of the same name to populate the Host Path.
When configuring MNMD, repeat the storage settings on each system in the node.
Multi-mode installs the app in either a MinIO Single-Node Multi-Drive (SNMD) or Multi-Node Multi-Drive (MNMD) cluster. MinIO recommends using MNMD for enterprise-grade performance and scalability.
Click Enable Multi Mode (SNMD or MNMD) to enable multi-mode and display the Multi Mode (SNMD or MNMD) and Add options. Click Add to display the field where you enter the storage or system port and storage URL string.
Enter /data{1…4} in the field if configuring SNMD. Where /data represents the dataset name and the curly brackets enclosing 1 and 4 separated by three dots represent the numeric value of the dataset names.
Enter https://10.123.123.10{0…3}:30000/data{1…4} in the field if configuring MNMD. The last number in the final octet of the IP address number is the first number in the {0…3} string. Separate the numbers in the curly brackets with three dots. If your sequential IP addresses are not using 100 - 103, for example 10.123.123.125 through 128, then enter them as https://10.123.123.12{5…8}:30000/data{1…4}.
If you do not have sequentially numbered IP addresses assigned to the four systems, assign sequentially numbered host names. For example, minio1.mycompany.com through minio4.mycompany.com. Enter https://minio{1…4}.mycompany.com:30000/data{1…4} in the Multi Mode (SNMD or MNMD) field.
Logging is an optional setting. If setting up logging, select Anonymous to hide sensitive information from logging or Quiet to omit (disable) startup information.
Select Enable Log Search API to enable LogSearch API and configure MinIO to use this function and add the configuration settings for LogSearch. This deploys a Postgres database to store the logs.
Enter the disk capacity LogSearch can use in Disk Capacity (GB).
Accept the default ixVolume in Postgres Data Storage to allow the app to create a storage volume. To select an existing dataset instead of the default, select Host Path from the dropdown list. Enter or browse to the dataset to populate the Host Path field.
Accept the default ixVolume in Postgres Backup Storage to allow the app to create the storage volume. To select an existing dataset instead of the default, select Host Path from the dropdown list. Enter or browse to the dataset to populate the Host Path field.
By default, TrueNAS limits this application to using no more than 4 CPU cores and 8 Gigabytes of available memory. The application might use considerably less system resources.
Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
TrueNAS EnterpriseThe instructions in this article apply to the TrueNAS MinIO Enterprise application installed in a Multi-Node Multi-Disk (MNMD) multi mode configuration.
SCALE Enterprise single controller systems with the applications and virtual machines license have access to the MinIO Official Enterprise widget.
For more information on MinIO multi mode configurations see MinIO Single-Node Multi-Drive (SNMD) or Multi-Node Multi-Drive (MNMD). MinIO recommends using MNMD (distributed) for enterprise-grade performance and scalability.
Community members can add and use the MinIO Enterprise app or the default community version.
To add the Enterprise MinIO application to the list of available applications, go to Apps and click on Discover Apps.
Click on Manage Catalogs at the top of the Discover screen to open the Catalog screen.
Click on the TRUENAS catalog to expand it, then click Edit to open the Edit Catalog screen.
Click in the Preferred Trains field, click on enterprise to add it to the list of trains, and then click Save.
Both the charts and enterprise train versions of the MinIO app widget display on the Discover application screen.
Complete these steps for every system (node) in the cluster.
Assign four sequential IP addresses or host names such as minio1.mycompany.com through minio4.mycompany.com to the TrueNAS SCALE system. If you assign IP address numbers such as *#.#.#.*100 - 103 or *#.#.#.134 - .137, you can uses these in the command string in the Multi Mode field. If not using sequential IP addresses, use sequentially numbered host names. Add network settings using either the Network screen. Enter host names on the Global Configuration screen.
When creating the certificate, enter the system IP addresses for each system in Subject Alternate Names. If configuring MinIO in a MNMD cluster, enter the system IP addresses for each system in the cluster.
If the 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.
Multi mode configurations require a self-signed certificate. If creating a cluster each system requires a self-signed certificate.
Add a self-signed certificate for the MinIO application to use.Create four datasets named, data1, data2, data3, and data4. Do not nest these datasets under each other. Select the parent dataset, for example apps, before you click Create Dataset. Set the Share Type to apps for each dataset. MinIO assigns the correct properties during the installation process so you do not need to configure the ACL or permissions.
This procedure covers the required Enterprise MinIO App settings.
Repeat this procedure for every system (node) in the MNND cluster.
To install the Minio Enterprise app, go to Apps, click on Discover Apps, then scroll down to locate the enterprise version of the Minio widget.
Click on the MinIO Official Enterprise widget to open the MinIO information screen.
Click Install to open the Install MinIO configuration screen.
Accept the defaults in Application Name or enter a name for your MinIO application deployment.
Accept the default in Version, which populates with the current MinIO version. SCALE displays update information on the Installed application screen when an update becomes available.
Enter credentials to use as the MinIO administration user. If you have existing MinIO credentials, enter these or create new login credentials for the first time you log into MinIO. The Root User is the equivalent of the MinIO access key. The Root Password is the login password for that user or the MinIO secret key.
Accept the User and Group Configuration settings default values for MinIO Enterprise. If you configured SCALE with a new administration user for MinIO, enter the UID and GID.
Scroll down to or click Network Configuration on the list of sections at the right of the screen.
Do not select Host Network.
Select the certificate you created for MinIO from the Certificates dropdown list.
Enter the TrueNAS server IP address and the API port number 30000 as a URL in MinIO Server URL (API). For example, https://ipaddress:30000. Enter the TrueNAS server IP address and the web UI browser redirect port number 30001 as a URL in MinIO Browser Redirect URL. For example, https://ipaddress:30001.
MNMD MinIO installations require HTTPS for both MinIO Server URL and MinIO Browser Redirect URL to verify the integrity of each node. Standard or SNMD MinIO installations do not require HTTPS.
Scroll down to or click on Storage Configuration on the list of sections at the right of the screen. Click Add three times in the Storage Configuration section to add three more sets of storage volume settings. In the first set of storage volume settings, select Host Path (Path that already exists on the system) and accept the default /data1 in Mount Path. Enter or browse to the data1 dataset to populate Host Path with the mount path. For example, /mnt/tank/apps/data1.
Scroll down to the next set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data2, and enter or browse to the location of the data2 dataset to populate the Host Path.
Scroll down to the next set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data3, and enter or browse to the location of the data3 dataset to populate the Host Path.
Scroll down to the last set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data4, and enter or browse to the location of the data4 dataset to populate the Host Path.
Select Enable Multi Mode (SNMD or MNMD), then click Add. If the systems in the cluster have sequentially assigned IP addresses, use the IP addresses in the command string you enter in the Multi Mode (SNMD or MNMD) field. For example, https://10.123.12.10{0…3}:30000/data{1…4} where the last number in the last octet of IP address number is the first number in the {0…3} string. Separate the numbers in the curly brackets with three dots. If your sequential IP addresses are not using 100 - 103, for example 10.123.12.125 through 128, then enter them as https://10.123.12.12{5…8}:30000/data{1…4}. Enter the same string in the Multi Mode (SNMD or MNMD) field in all four systems in the cluster.
If you do not have sequentially numbered IP addresses assigned to the four systems, assign sequentially numbered host names. For example, minio1.mycompany.com through minio4.mycompany.com. Enter https://minio{1…4}.mycompany.com:30000/data{1…4} in the Multi Mode (SNMD or MNMD) field.
If you want to set up logging, select Anonymous to hide sensitive information from logging, or Quiet to disable startup information.
Select the optional Enable Log Search API to enable LogSearch API and configure MinIO to use this function and deploy a postgres database to store the logs.
Specify the storage in gigabytes that the logs are allowed to occupy in Disk Capacity in GB. Accept the default ixVolume in Postgres Data Storage and Postgres Backup Storage to let the system create the datasets, or select Host Path to select an existing dataset on the system to use for these storage volumes.
Accept the default values in Resources Configuration or to customize the CPU and memory allocated to the container (pod) the Minio app uses, enter new values in the CPU Resource Limit and Memory Limit fields. Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
Click Install to complete the installation.
The Installed applications screen opens showing the MinIO application in the Deploying state. It changes to Running when the application is ready to use.
Click Web Portal to open the MinIO sign-in screen.
After installing and getting the MinIO Enterprise application running in SCALE, log into the MinIO web portal and complete the MinIO setup.
Go to Monitoring > Metrics to verify the servers match the total number of systems (nodes) you configured. Verify the number of drives match the number you configured on each system, four systems each with four drives (4 systems x 4 drives each = 16 drives).
Refer to MinIO documentation for more information.
TrueNAS EnterpriseThe instructions in this article apply to the TrueNAS MinIO Enterprise application installed in a Single-Node Multi-Disk (SNMD) multi mode configuration.
SCALE Enterprise single controller systems with the applications and virtual machines license have access to the MinIO Official Enterprise widget.
For more information on MinIO multi mode configurations see MinIO Single-Node Multi-Drive (SNMD) or Multi-Node Multi-Drive (MNMD). MinIO recommends using MNMD (distributed) for enterprise-grade performance and scalability.
Community members can add and use the MinIO Enterprise app or the default community version.
To add the Enterprise MinIO application to the list of available applications, go to Apps and click on Discover Apps.
Click on Manage Catalogs at the top of the Discover screen to open the Catalog screen.
Click on the TRUENAS catalog to expand it, then click Edit to open the Edit Catalog screen.
Click in the Preferred Trains field, click on enterprise to add it to the list of trains, and then click Save.
Both the charts and enterprise train versions of the MinIO app widget display on the Discover application screen.
This procedure covers the required Enterprise MinIO App settings.
To install the Minio Enterprise app, go to Apps, click on Discover Apps, then scroll down to locate the enterprise version of the Minio widget.
Click on the MinIO Official Enterprise widget to open the MinIO information screen.
Click Install to open the Install MinIO configuration screen.
Accept the defaults in Application Name or enter a name for your MinIO application deployment.
Accept the default in Version, which populates with the current MinIO version. SCALE displays update information on the Installed application screen when an update becomes available.
Enter credentials to use as the MinIO administration user. If you have existing MinIO credentials, enter these or create new login credentials for the first time you log into MinIO. The Root User is the equivalent of the MinIO access key. The Root Password is the login password for that user or the MinIO secret key.
Accept the User and Group Configuration settings default values for MinIO Enterprise. If you configured SCALE with a new administration user for MinIO, enter the UID and GID.
Scroll down to or click Network Configuration on the list of sections at the right of the screen.
Do not select Host Network.
Select the certificate you created for MinIO from the Certificates dropdown list.
Enter the TrueNAS server IP address and the API port number 30000 as a URL in MinIO Server URL (API). For example, https://ipaddress:30000. Enter the TrueNAS server IP address and the web UI browser redirect port number 30001 as a URL in MinIO Browser Redirect URL. For example, https://ipaddress:30001.
MNMD MinIO installations require HTTPS for both MinIO Server URL and MinIO Browser Redirect URL to verify the integrity of each node. Standard or SNMD MinIO installations do not require HTTPS.
Scroll down to or click on Storage Configuration on the list of sections at the right of the screen. Click Add three times in the Storage Configuration section to add three more sets of storage volume settings. In the first set of storage volume settings, select Host Path (Path that already exists on the system) and accept the default /data1 in Mount Path. Enter or browse to the data1 dataset to populate Host Path with the mount path. For example, /mnt/tank/apps/data1.
Scroll down to the next set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data2, and enter or browse to the location of the data2 dataset to populate the Host Path.
Scroll down to the next set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data3, and enter or browse to the location of the data3 dataset to populate the Host Path.
Scroll down to the last set of storage volume settings and select Host Path (Path that already exists on the system). Change the Mount Path to /data4, and enter or browse to the location of the data4 dataset to populate the Host Path.
Select Enable Multi Mode (SNMD or MNMD), then click Add. Enter **/data{1…4} in the Multi Mode (SNMD or MNMD) field.
If you want to set up logging, select Anonymous to hide sensitive information from logging, or Quiet to disable startup information.
Select the optional Enable Log Search API to enable LogSearch API and configure MinIO to use this function and deploy a postgres database to store the logs.
Specify the storage in gigabytes that the logs are allowed to occupy in Disk Capacity in GB. Accept the default ixVolume in Postgres Data Storage and Postgres Backup Storage to let the system create the datasets, or select Host Path to select an existing dataset on the system to use for these storage volumes.
Accept the default values in Resources Configuration or to customize the CPU and memory allocated to the container (pod) the Minio app uses, enter new values in the CPU Resource Limit and Memory Limit fields. Tune these limits as needed to prevent the application from overconsuming system resources and introducing performance issues.
By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
Click Install to complete the installation.
The Installed applications screen opens showing the MinIO application in the Deploying state. It changes to Running when the application is ready to use.
Click Web Portal to open the MinIO sign-in screen.
This article provides information on installing and using the TrueNAS Syncthing app.
SCALE has two versions of the Syncthing application, the community version in the charts train and a smaller version tested and polished for a safe and supportable experience for enterprise customers in the enterprise train. Community members can install either the enterprise or community version.
TrueNAS EnterpriseSyncthing is available to Enterprise systems with the appropriate VM and applications license.
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 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 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 Syncthing web UI provides users with easy management and configuration of the application software.
Create a self-signed certificate for the Syncthing enterprise app.
You can allow the app to create a storage volume(s) or use existing datasets created in SCALE. The TrueNAS Syncthing app requires a main configuration storage volume for application information. You can also mount existing datasets for storage volume inside the container pod.
If you want to use existing datasets for the main storage volume, [create any datasets]/scale/scaletutorials/datasets/datasetsscale/ before beginning the app installation process (for example, syncthing for the configuration storage volume). If also mounting storage volume inside the container, create a second dataset named data1. If mounting multiple storage volumes, create a dataset for each volume (for example, data2, data3, etc.).
You can have multiple Syncthing app deployments (two or more Charts, two or more Enterprise, or Charts and Enterprise trains, etc.). Each Syncthing app deployment requires a unique name that can include numbers and dashes or underscores (for example, syncthing2, syncthing-test, syncthing_1, etc.).
Use 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 app are case sensitive. For example, a file named MyData.txt is not the same as mydata.txt file in Syncthing.
If not already assigned, set a pool for applications to use.
Either use the default user and group IDs or create the new user with Create New Primary Group selected. Make note of the UID/GID for the new user.
Go to Apps > Discover Apps, locate the Syncthing enterprise app widget.
Click on the widget to open the Syncthing details screen.
Click Install to open the Install Syncthing screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Accept the default values in Application Name and Version.
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. Accept the default web port 31000.
If changing ports, see Default Ports for a list of assigned port numbers.
Select the certificate created for Syncthing from the Certificates dropdown list.
Configure the storage settings. To allow Syncthing to create the configuration storage volume, leave Type set to ixVolume (Dataset created automatically by the system), then enter or browse to the location of the data1 dataset to populate the Host Path field under the Mount Path field.
To use an existing dataset created for Syncthing, select Host Path (Path that already exists on the system). Enter or browse to the dataset created to populate the Host Path field (for example, /mnt/tank/syncthing/config), then enter or browse to the location of the data1 dataset to populate the Host Path field under the Mount Path field.
To add another dataset path inside the container, see Storage Settings below for more information.
Click Install. The system opens the Installed Applications screen with the Syncthing app in the Deploying state. After installation completes the status changes to Running.
Click Web Portal on the Application Info widget to open the Syncthing web portal to begin configuring folders, devices, and other settings.
Secure Syncthing by setting up a username and password.
The following sections provide detailed explanations of the settings found in each section of the Install Syncthing screen for the Enterprise train app.
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
Select the timezone where your TrueNAS SCALE system is located.
You can accept the defaults settings in User and Group Configuration, or enter new user and group IDs. The default value for User Id and Group ID is 568.
Accept the default port numbers in Web Port for Syncthing. The SCALE Syncthing chart app listens on port 31000. Before changing the default port and assigning a new port number, 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.
We recommend not selecting Host Network. This binds to the host network.
Select the self-signed certificate created in SCALE for Syncthing from the Certificate dropdown list. You can edit the certificate after deploying the application.
You can allow the Syncthing app to create the configuration storage volume or you can create datasets to use for the configuration storage volume and to use for storage within the container pod.
To allow the Syncthing app to create the configuration storage volume, leave Type set to ixVolume (Dataset created automatically…).
To use existing datasets, select Host Path (Path that already exist on the system) in Type to show the Host Path field, then enter or browse to and select the dataset an existing dataset created for the configuration storage volume.
If mounting a storage volume inside the container pod, enter or browse to the location of the data1 dataset to populate the Host Path field below the Mount Path populated with data1.
In addition to the data1 dataset, you can mount additional datasets to use as other storage volumes within the pod. Click Add to the right of Additional Storage to show another set of Mount Path and Host Path fields for each dataset to mount. Enter or browse to the dataset to populate the Host Path and Mount Path fields.
The TrueNAS SCALE Syncthing Enterprise app includes the option to mount an SMB share inside the container pod. This allows data synchronization between the share and the app.
The SMB share mount does not include ACL protections at this time. Permissions are currently limited to the permissions of the user that mounted the share. Alternate data streams (metadata), finder colors tags, previews, resource forks, and MacOS metadata is stripped from the share along with filesystem permissions, but this functionality is undergoing active development and implementation planned for a future TrueNAS SCALE release.
To mount an SMB share inside the Syncthing application, select SMB Share (Mounts a persistent volume claim to a system) in Type if not mounting a dataset in the container pod. If mounting a dataset inside the pod and to mount an SMB share, click Add to the right of Additional Storage to add a set of select settings then select the SMB share option.
Enter the server for the SMB share in Server, the name of the share in Share, then enter the username and password credentials for the SMB share Determine the total size of the SMB share to mount and access via TrueNAS SCALE and Syncthing, and enter this value in Size. You can edit the size after deploying the application if you need to increase the storage volume capacity for the share.
Accept the default values in Resources Configuration or enter new CPU and memory values. By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container (pod) Syncthing uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.
Accept the default value 8Gb allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123MiB.
Syncthing uses inotify to monitor filesystem events, with one inotify watcher per monitored directory. Linux defaults to a maximum of 8192 inotify watchers. Using the Syncthing Enterprise app to sync directories with greater than 8191 subdirectories (possibly lower if other services are also utilizing inotify) produces errors that prevent automatic monitoring of filesystem changes.
Increase inotify values to allow Syncthing to monitor all sync directories. Add a sysctl variable to ensure changes persist through reboot.
Go to System Settings > Advanced and locate the Sysctl widget.
Click Add to open the Add Sysctl screen.
Enter fs.inotify.max_user_watches in Variable.
Enter a Value larger than the number of directories monitored by Syncthing. There is a small memory impact for each inotify watcher of 1080 bytes, so it is best to start with a lower number, we suggest 204800, and increase if needed.
Enter a Description for the variable, such as Increase inotify limit.
Select Enabled and click Save.
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 portal 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 listeners, total uptime, sync state, and the device ID and version.
Actions displays a dropdown list of options. Click Advanced to access GUI, LDAP, folder, device, and other settings.
You can manage directional settings for sync configurations, security, encryption, and UI server settings through the Actions options.
TrueNAS Sandboxes and Jailmaker are not supported by iXsystems. This is provided solely for users with advanced command-line, containerization, and networking experience.
There is significant risk that using Jailmaker causes conflicts with the built-in Apps framework within SCALE. Do not mix the two features unless you are capable of self-supporting and resolving any issues caused by using this solution.
Beginning with 24.04 (Dragonfish), TrueNAS SCALE includes the systemd-nspawn containerization program in the base system. This allows using tools like the open-source Jailmaker to build and run containers that are very similar to Jails from TrueNAS CORE or LXC containers on Linux. Using the Jailmaker tool allows deploying these containers without modifying the base TrueNAS system. These containers persist across upgrades in 24.04 (Dragonfish) and later SCALE major versions.
Log in to the web interface and go to Datasets.
Select your root pool and click Add Dataset:
a. Name the dataset jailmaker.
b. Leave all other settings at their defaults.
c. Click Save.
Open a Shell (SSH preferred) session and run these commands as root:
a.
cd /mnt/tank/jailmaker/
.
Replace tank with the name of your pool.
b.
curl --location --remote-name https://raw.githubusercontent.com/Jip-Hop/jailmaker/main/jlmkr.py
c.
chmod +x jlmkr.py
Before making any sandboxes, configure TrueNAS to run the Jailmaker tool when the system starts. This ensures the sandboxes start properly.
Log in to the web interface and go to System Settings > Advanced.
Find the Init/Shutdown Scripts widget and click Add:
a. Enter this or a similar note in Description: Jailmaker Startup
b. Set Type to Command.
c. Enter this string in Command:
/mnt/tank/jailmaker/jlmkr.py startup
.
Replace tank with the name of your pool.
d. Set When to Post Init.
e. Set the Enabled checkbox.
f. Leave Timeout at the default and click Save. If you intend to create many sandboxes, increase the timeout integer to a longer wait period.
With a TrueNAS dataset configured for sandboxes and the Jailmaker script set to run at system startup, sandboxes can now be created.
Creating and managing sandboxes is done only in TrueNAS Shell sessions using the
jlmkr
command.
For full usage documentation, refer to the open-source Jailmaker project.
From a TrueNAS Shell session, go to your sandboxes dataset and enter
./jlmkr.py -h
for embedded usage notes.
Report any issues encountered when using Jailmaker to the project Issues Tracker.
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.
TrueCommand offers enhanced features for reporting 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.
You can configure TrueNAS to export Netdata information to any time-series database, reporting cloud service or application installed on a server. For example, Graphite, Grafana, etc., installed on a server or use their cloud service.
Creating reporting exporters enables SCALE to send Netdata reporting metrics, formatted as a JSON object, to another reporting entity.
For more information on exporting Netdata records to other servers or services, refer to the Netdata exporting reference guide.
Graphite is a monitoring tool available as an application you can deploy on a server or use their cloud service. It stores and renders time-series data based on a plaintext database. Netdata exports reporting metrics to Graphite in the format prefix.hostname.chart.dimension. For additional information, see the Netdata Graphite exporting guide.
To configure a reporting exporter in SCALE, you need the:
For more information on reporting exporter settings, see Add Reporting Exporter.
Go to Reporting and click on Exporters to open the Reporting Exporters screen. Any reporting exporters configured on the system display on the Reporting Exporters screen.
Click Add to open the Add Reporting Exporter screen to configure a third party reporting integration.
Enter a unique name for the exporter configuration in Name. When configuring multiple exporter instances, give each a distinct name.
Select the report object format from Type. At present, only GRAPHITE is available. The screen shows the exporter configuration fields.
Select Enable to send reporting metrics to the configured exporter instance. Clearing the checkmark disables the exporter without removing configuration.
Enter the IP address for the data collection server or cloud service.
Enter the port number the report collecting server, etc. listens on.
Enter the file hierarchy structure, or where in the collecting server, etc. to send the data. First enter the top-level in Prefix and then the data collection folder in the Namespace field. For example, entering DF in Prefix and test in Namespace creates two folders in Graphite with DF as the parent to Test.
You can accept the defaults for all other settings, or enter configuration settings to match your use case.
Click Save.
To view the Graphite web UI, enter the IPaddress:Port# of the system hosting the application.
SCALE can now export the data records as Graphite-formatted JSON objects to the other report collection and processing application, service, or servers.
SCALE also populates the exporter screen with default settings. To view these settings, click Edit on the row for the exporter.
SCALE system management options are collected in this section of the UI and organized into a few different screens:
Update controls when the system applies a new version. There are options to download and install an update, have the system check daily and stage updates, or apply a manual update file to the system.
General shows system details and has basic, less intrusive management options, including web interface access, localization, and NTP server connections. This is also where users can input an Enterprise license or create a software bug ticket.
Advanced contains options that are more central to the system configuration or meant for advanced users. Specific options include configuring the system console, log, and dataset pool, managing sessions, adding custom system controls, kernel-level settings, scheduled scripting or commands, global two-factor authentication, and determining any isolated GPU devices. Warning: Advanced settings can be disruptive to system function if misconfigured.
Boot lists each ZFS boot environment stored on the system. These restore the system to a previous version or specific point in time.
Services displays each system component that runs continuously in the background. These typically control data sharing or other external access to the system. Individual services have their own configuration screens and activation toggles, and can be set to run automatically.
Shell allows users to use the TrueNAS Operating System command-line interface (CLI) directly in the web UI. Includes an experimental TrueNAS SCALE-specific CLI for configuring the system separately from the web interface. See the CLI Reference Guide for more information.
Alert Settings allows users to configure Alert Services and to adjust the threshold and frequency of various alert types. See Alerts Settings Screens for more information.
Enclosure appears when the system is attached to compatible SCALE hardware. This is a visual representation of the system with additional details about disks and other physical hardware components.
TrueNAS has several software branches (linear update paths) known as trains. If SCALE is in a prerelease train it can have various preview/early build releases of the software.
The Update Screen only displays the current train. When looking to upgrade SCALE to a new major version, make sure to upgrade SCALE along the path of major versions until the system is on the desired major version release. For more information on other available trains and the upgrade path from one version to the next, see Software Releases.
See the Software Status page for the latest recommendations for software usage. Do not change to a prerelease or nightly release unless the system is intended to permanently remain on early versions and is not storing any critical data.
If you are using a non-production train, be prepared to experience bugs or other problems. Testers are encouraged to submit bug reports and debug files. For information on how to file an issue ticket see Filing an Issue Ticket in SCALE.
The TrueNAS SCALE Update screen provides users with two different methods to update the system, automatic or manual.
We recommend updating SCALE when the system is idle (no clients connected, no disk activity, etc.). The system restarts after an upgrade. Update during scheduled maintenance times to avoid disrupting user activities.
All auxiliary parameters are subject to change between major versions of TrueNAS due to security and development issues. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
If an update is available, click Apply Pending Update to install it.
The Save configuration settings from this machine before updating? window opens.
Click Export Password Secret Seed then click Save Configuration. The Apply Pending Updates window opens.
Click Confirm, then Continue to start the automatic installation process. TrueNAS SCALE downloads the configuration file and the update file, then starts the install.
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
If the system detects an available update, to do a manual update click Download Updates and wait for the file to download to your system.
SCALE Manual update files are available from the TrueNAS SCALE Download page website.
Click Install Manual Update File. The Save configuration settings from this machine before updating? window opens. Click Export Password Secret Seed then click Save Configuration. The Manual Update screen opens.
Click Choose File to locate the update file on the system. Select a temporary location to store the update file. Select Memory Device or select one of the mount locations on the dropdown list to keep a copy in the server.
Click Apply Update to start the update process. A status window opens and displays the installation progress. When complete, a Restart window opens.
Click Confirm, then Continue to restart the system.
When a system update starts, appears in the toolbar at the top of the UI. Click the icon to see the current status of the update and which TrueNAS administrative account initiated the update.
After updating, you might find that you can update your storage pools and boot-pool to enable new supported and requested features that are not enabled on the pool.
Go to System Settings > Shell and enter cli
to enter the CLI if Shell does not open in the CLI.
To show which pools you can update, first enter a query command to see the list of pools on your system and the id number for each pool.
storage pool query
Next, check the update status:
storage pool is_upgraded id=2
where 2 is the pool ID number you want to check the update status for.
To update the pool, enter:
storage pool upgrade id=2
Upgrading pools is a one-way operation. After upgrading pools to the latest zfs features, you might not be able to boot into older versions of TrueNAS.
TrueNAS EnterpriseThis procedure only applies to SCALE Enterprise (HA) systems. If attempting to migrate from CORE to SCALE, see Migrating from TrueNAS CORE.
If the system does not have an administrative user account, create the admin user as part of this procedure.
Take a screenshot of the license information found on the Support widget on the System Settings > General screen. You use this to verify the license after the update.
To update your Enterprise (HA) system to the latest SCALE release, log into the SCALE UI using the virtual IP (VIP) address and then:
Check for updates. Go to the main Dashboard and click Check for Updates on the System Information widget for the active controller. This opens the System Settings > Update screen. If an update is available it displays on this screen.
Save the password secret seed and configuration settings to a secure location. Click Install Manual Updates. The Save configuration settings window opens. Select Export Password Secret Seed then click Save Configuration. The system downloads the file. The file contains sensitive system data and should be maintained in a secure location.
Select the update file and start the process. Click Choose File and select the update file downloaded to your system, then click Apply Update to start the update process. After the system to finishes updating it reboots.
Sign into the SCALE UI. If using root to sign in, create the admin account now. If using admin, continue to the next step.
Verify the system license after the update. Go to System Settings > General. Verify the license information in the screenshot of the Support widget you took before the update matches the information on the Support widget after updating the system.
Verify the admin user settings, or if not created, create the admin user account now.
If you want the admin account to have the ability to execute sudo
commands in an SSH session, select the option for the sudo access you want to allow.
Also, verify Shell is set to bash if you want the admin user to have the ability to execute commands in Shell.
To set a location where the admin user can save to, browse to, and select the dataset in Home Directory. If set to the default /nonexistent files are not saved for this user.
Test the admin user access to the UI.
a. Log out of the UI.
b. Enter the admin user credentials in the sign-in splash screen.
After validating access to the SCALE UI using the admin credentials, disable the root user password. Go to Credentials > Local User and edit the root user. Select Disable Password and click Save.
Finish the update by saving your updated system configuration file to a secure location and create a new boot environment to use as a restore point if it becomes necessary.
The TrueNAS SCALE General Settings section provides settings options for support, graphic user interface, localization, NTP servers, and system configuration.
TrueNAS SCALE allows users to manage the system configuration by uploading or downloading configurations, or by resetting the system to the default configuration.
The Manage Configuration option on the System Settings > General screen provides three options:
The Download File option downloads your TrueNAS SCALE current configuration to the local machine.
When you download the configuration file, you have the option to Export Password Secret Seed, which includes encrypted passwords in the configuration file. This allows you to restore the configuration file to a different operating system device where the decryption seed is not already present. Users must physically secure configuration backups containing the seed to prevent unauthorized access or password decryption.
We recommend backing up the system configuration regularly. Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues. Save the configuration file each time the system configuration changes.
Go to System Settings > General and click on Manage Configuration. Select Download File.
The Save Configuration dialog displays.
Click Export Password Secret Seed and then click Save. The system downloads the system configuration. Save this file in a safe location on your network where files are regularly backed up.
Anytime you change your system configuration, download the system configuration file again and keep it safe.
The Upload File option gives users the ability to replace the current system configuration with any previously saved TrueNAS SCALE configuration file.
All passwords are reset if the uploaded configuration file was saved without selecting Save Password Secret Seed.
TrueNAS Enterprise
Save the current system configuration with the Download File option before resetting the configuration to default settings! If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.
The Reset to Defaults option resets the system configuration to factory settings. After the configuration resets, the system restarts and users must set a new login password.
SCALE does not automatically back up the system configuration file to the system dataset.
Users who want to schedule an automatic backup of the system configuration file should:
Users can manually back up the SCALE config file by downloading and saving the file to a location that is automatically backed up.
The TrueNAS SCALE General Settings section provides settings options for support, graphic user interface, localization, NTP servers, and system configuration.
The Support widget shows information about the TrueNAS version and system hardware. Links to the open source documentation, community forums, and official Enterprise licensing from iXsystems are also provided.
Add License opens the sidebar with a field to paste a TrueNAS Enterprise license (details).
File Ticket opens a window to provide feedback directly to the development team.
The GUI widget allows users to configure the TrueNAS SCALE web interface address. Click Settings to open the GUI Settings configuration screen.
The system uses a self-signed certificate to enable encrypted web interface connections. To change the default certificate, select a different certificate that was created or imported in the Certificates section from the GUI SSL Certificate dropdown list.
To set the WebUI IP address, if using IPv4 addresses, select a recent IP address from the Web Interface IPv4 Address dropdown list. This limits the usage when accessing the administrative GUI. The built-in HTTP server binds to the wildcard address of 0.0.0.0 (any address) and issues an alert if the specified address becomes unavailable. If using an IPv6 address, select a recent IP address from the Web Interface IPv6 Address dropdown list.
To allow configuring a non-standard port to access the GUI over HTTPS, enter a port number in the Web Interface HTTPS Port field.
Select the cryptographic protocols for securing client/server connections from the HTTPS Protocols dropdown list. Select the Transport Layer Security (TLS) versions TrueNAS SCALE can use for connection security.
To redirect HTTP connections to HTTPS, select Web Interface HTTP -> HTTPS Redirect. A GUI SSL Certificate is required for HTTPS. Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year. A warning displays when setting this function.
Special consideration should be given when TrueNAS is installed in a VM, as VMs are not configured to use HTTPS. Enabling HTTPS redirect can interfere with the accessibility of some apps. To determine if HTTPS redirect is active, go to System Settings > General > GUI > Settings and locate the Web Interface HTTP -> HTTPS Redirect checkbox. To disable HTTPS redirects, clear this option and click Save, then clear the browser cache before attempting to connect to the app again.
To send failed HTTP request data which can include client and server IP addresses, failed method call tracebacks, and middleware log file contents to iXsystems, select Crash Reporting.
To send anonymous usage statistics to iXsystems, select the Usage Collection option.
To display console messages in real time at the bottom of the browser, select the Show Console Messages option.
To change the WebUI on-screen language and set the keyboard to work with the selected language, click Settings on the System Settings > General > Localization widget. The Localization Settings configuration screen opens.
Select the language from the Language dropdown list, and then the keyboard layout in Console Keyboard Map.
Enter the time zone in Timezone and then select the local date and time formats to use.
Click Save.
The NTP Servers widget allows users to configure Network Time Protocol (NTP) servers. These sync the local system time with an accurate external reference. By default, new installations use several existing NTP servers. TrueNAS SCALE supports adding custom NTP servers.
The Email widget displays information about current system mail settings. When configured, an automatic script sends a nightly email to the administrator account containing important information such as the health of the disks.
To configure the system email send method, click Settings to open the Email Options screen. Select either SMTP or GMail OAuth to display the relevant configuration settings.
For users with a valid TrueNAS license, click Add License. Copy your license into the box and click Save.
You are prompted to reload the page for the license to take effect, click RELOAD NOW. Log back into the WebUI where the End User License Agreement (EULA) displays. Read it thoroughly and completely. After you finish, click I AGREE. The system information updates to reflect the licensing specifics for the system.
Silver and Gold level Support customers can also enable Proactive Support on their hardware to automatically notify iXsystems if an issue occurs. To find more details about the different Warranty and Service Level Agreement (SLA) options available, see iXsystems Support.
When the system is ready to be in production, update the status by selecting This is a production system and then click the Proceed button. This sends an email to iXsystems declaring that the system is in production.
While not required for declaring the system is in production, TrueNAS has the option to include an initial debug with the email that can assist support in the future.
Silver/Gold Coverage Customers can enable iXsystems Proactive Support. This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
To configure proactive support, click Get Support on the Support widget located on the System Settings > General screen. Select Proactive Support from the dropdown list.
Complete all available fields and select Enable iXsystems Proactive Support, then click Save.
An automatic script sends a nightly email to the administrator account containing important information such as the health of the disks. Configure the system to send these emails to the administrator remote email account for fast awareness and resolution of any critical issues.
Scrub Task issues and S.M.A.R.T. reports are mailed separately to the address configured in those services.
Configure the email address for the admin user as part of your initial system setup or using the procedure below. You can also configure email addresses for additional user accounts as needed.
Before configuring anything else, set the local administrator email address.
Add a new user as an administrative or non-administrative account and set up email for that user. Follow the directions in Configuring the Admin User Email Address above for an existing user or see Managing Users for a new user.
After setting up the admin email address, you need to set up the send method for email service.
There are two ways to access email configuration options. Go to the Systems Settings > General screen and locate the Email widget to view current configuration or click the Alerts icon in the top right of the UI, then click the gear icon, and select Email to open the General settings screen. Click Settings on the Email Widget to open the Email Options configuration screen.
Send Mail Method shows two different options:
The configuration options change based on the selected method.
After configuring the send method, click Send Test Mail to verify the configured email settings are working. If the test email fails, verify that the Email field is correctly configured for the admin user. Return to Credentials > Users to edit the admin user.
Save stores the email configuration and closes the Email Options screen.
To set up SMTP service for the system email send method, you need the outgoing mail server and port number for the email address.
To set up the system email using Gmail OAuth, you need to log in to your Gmail account through the TrueNAS SCALE web UI.
If the system email send method is configured, the admin email receives a system health email every night/morning.
You can also add/configure the Email Alert Service to send timely warnings when a system alert hits a warning level that is specified in Alert Settings.
From the Alerts
panel, select the icon and then Alert Settings, or go to System Settings > Alert Settings.Locate Email under Alert Services, select the
icon, and then click Edit to open the Edit Alert Service screen.Add the system email address in the Email Address field.
Use the Level dropdown to adjust the email warning threshold or accept the default Warning.
Use Send Test Alert to generate a test alert and confirm the email address and alert service works.
Advanced Settings provides configuration options for the console, syslog, kernel, sysctl, replication, cron jobs, init/shutdown scripts, system dataset pool, isolated GPU device(s), self-encrypting drives, system access sessions, allowed IP addresses, audit logging, and global two-factor authentication.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
This article provides information on sysctl, system dataset pool, setting the maximum number of simultaneous replication tasks the system can perform, and managing sessions.
Use the System Settings > Advanced screen Allowed IP Addresses configuration screen to restrict access to the TrueNAS SCALE web UI and API.
Entering an IP address limits access to the system to only the address(es) entered here. To allow unrestricted access to all IP addresses, leave this list empty.
Use Add on the Sysctl widget to add a tunable that configures a kernel module parameter at runtime.
The Add Sysctl or Edit Sysctl configuration screens display the settings.
Enter the sysctl variable name in Variable. Sysctl tunables configure kernel module parameters while the system runs and generally take effect immediately.
Enter a sysctl value for the loader in Value.
Enter a description and then select Enabled. To disable but not delete the variable, clear the Enabled checkbox.
Click Save.
Storage widget displays the pool configured as the system dataset pool and allows users to select the storage pool they want to hold the system dataset. The system dataset stores core files for debugging and keys for encrypted pools. It also stores Samba4 metadata, such as the user and group cache and share-level permissions.
Configure opens the Storage Settings configuration screen.
If the system has one pool, TrueNAS configures that pool as the system dataset pool. If your system has more than one pool, you can set the system dataset pool using the Select Pool dropdown. Users can move the system dataset to an unencrypted pool, or an encrypted pool without passphrases.
Users can move the system dataset to a key-encrypted pool, but cannot change the pool encryption type afterward. If the encrypted pool already has a passphrase set, you cannot move the system dataset to that pool.
Swap Size lets users enter an amount (in GiB) of hard disk space to use as a substitute for RAM when the system fully utilizes the actual RAM.
By default, the system creates all data disks with the specified swap amount. Changing the value does not affect the amount of swap on existing disks, only disks added after the change. Swap size does not affect log or cache devices.
The Replication widget displays the number of replication tasks that can execute simultaneously configured on the system. It allows users to adjust the maximum number of replication tasks the system can execute simultaneously.
Click Configure to open the Replication configuration screen.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
The Access widget displays a list of all active sessions, including the user who initiated the session and what time it started. It also displays the Token Lifetime setting for your current session. It allows administrators to manage other active sessions and to configure the token lifetime for their account.
The Terminate Other Sessions button ends all sessions except for the one you are currently using. You can also end individual sessions by clicking the logout button next to that session. You must check a confirmation box before the system allows you to end sessions.
The logout icon is inactive for the currently logged in administrator session and active for any other current sessions. It cannot be used to terminate the currently logged in active administrator session.
Token Lifetime displays the configured token duration for the current session (default five minutes). TrueNAS SCALE logs out user sessions that are inactive for longer than that configured token setting for the user. New activity resets the token counter.
If the configured token lifetime is exceeded, TrueNAS SCALE displays a Logout dialog with the exceeded ticket lifetime value and the time that the session is scheduled to terminate.
Click Extend Session to reset the token counter. If the button is not clicked, the TrueNAS SCALE terminates the session automatically and returns to the log in screen.
Click Configure to open the Token Settings screen and configure Token Lifetime for the current account.
Select a value that fits user needs and security requirements. Enter the value in seconds.
The default lifetime setting is 300 seconds, or five minutes.
The minimum value allowed is 30 seconds.
The maximum is 2147482 seconds, or 20 hours, 31 minutes, and 22 seconds.
Click Save.
Cron jobs allow users to configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Cron Jobs widget on the System > Advanced screen displays No Cron Jobs configured until you add a cron job, and then it displays information on cron job(s) configured on the system.
Click Add to open the Add Cron Job configuration screen and create a new cron job. If you want to modify an existing cron job, click anywhere on the item to open the Edit Cron Jobs configuration screen populated with the settings for that cron job. The Add Cron Job and Edit Cron Job configuration screens display the same settings.
Enter a description for the cron job.
Next, enter the full path to the command or script to run in Command. For example, for a command string to create a list of users on the system and write that list to a file, enter cat /etc/passwd > users_$(date +%F).txt
.
Select a user account to run the command from the Run As User dropdown list. The user must have permissions allowing them to run the command or script.
Select a schedule preset or choose Custom to open the advanced scheduler. An in-progress cron task postpones any later scheduled instances of the task until the one already running completes.
If you want to hide standard output (stdout) from the command, select Hide Standard Output. If left cleared, TrueNAS emails any standard output to the user account cron that ran the command.
To hide error output (stderr) from the command, select Hide Standard Error. If left cleared, TrueNAS emails any error output to the user account cron that ran the command.
Select Enabled to enable this cron job. Leave this checkbox cleared to disable the cron job without deleting it.
Click Save.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Console widget on the System Setting > Advanced screen displays current console settings for TrueNAS.
Click Configure to open the Console configuration screen. The Console configuration settings determine how the Console setup menu displays, the serial port it uses and the speed of the port, and the banner users see when it is accessed.
To display the console without being prompted to enter a password, select Show Text Console without Password Prompt. Leave it clear to add a login prompt to the system before showing the console menu.
Select Enable Serial Console to enable the serial console but do not select this if the serial port is disabled.
Enter the serial console port address in Serial Port and set the speed (in bits per second) from the Serial Speed dropdown list. Options are 9600, 19200, 38400, 57600 or 115200.
Finally, enter the message you want to display when a user logs in with SSH in MOTD Banner.
Click Save
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
By default, TrueNAS writes system logs to the system boot device. The Syslog widget on the System > Advanced screen allows users determine how and when the system sends log messages to a connected syslog server. The Syslog widget displays the existing system logging settings.
Before configuring your syslog server to use TLS as the Syslog Transport method, first make sure you add a certificate and certificate authority (CA) to the TrueNAS system. Go to Credentials > Certificates and use the Certificate Authority (CA) and Certificates widgets to verify you have the required certificates or to add them.
Click Configure to open the Syslog configuration screen. The Syslog configuration screen settings specify the logging level the system uses to record system events, the syslog server DNS host name or IP, the transport protocol it uses, and if using TLS, the certificate and certificate authority (CA) for that server, and finally if it uses the system dataset to store the logs.
Enter the remote syslog server DNS host name or IP address in Syslog Server. To use non-standard port numbers like mysyslogserver:1928, add a colon and the port number to the host name. Log entries are written to local logs and sent to the remote syslog server.
Enter the transport protocol for the remote system log server connection in Syslog Transport. Selecting Transport Layer Security (TLS) displays the Syslog TLS Certificate and Syslog TSL Certificate Authority fields.
Next, select the transport protocol for the remote system log server TLS certificate from the Syslog TLS Certificate dropdown list, and select the TLS CA for the TLS server from the Syslog TLS Certificate Authority dropdown list.
Select Use FQDN for Logging to include the fully-qualified domain name (FQDN) in logs to precisely identify systems with similar host names.
Select the minimum log priority level to send to the remote syslog server from Syslog Level the dropdown list. The system only sends logs at or above this level.
Click Save.
The Init/Shutdown Scripts widget on the System > Advanced screen allows you to add scripts to run before or after initialization (start-up), or at shutdown. For example, creating a script to backup your system or run a systemd command before exiting and shutting down the system.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before creating and executing script tasks.
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, and then the widget lists the scripts configured on the system.
Click Add to open the Add Init/Shutdown Script configuration screen.
Enter a description and then select Command or Script from the Type dropdown list. Selecting Script displays additional options.
Enter the command string in Command, or if using a script, enter or use the browse to the path in Script. The script runs using dash(1).
Select the option from the When dropdown list for the time this command or script runs.
Enter the number of seconds after the script runs that the command should stop in Timeout.
Select Enable to enable the script. Leave clear to disable but not delete the script.
Click Save.
Click a script listed on the Init/Shutdown Scripts widget to open the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
You can change from a command to a script, and modify the script or command as needed.
To disable but not delete the command or script, clear the Enabled checkbox.
Click Save.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Self-Encrypting Drive(s) widget on the System > Advanced screen allows you set the user and global SED password in SCALE.
The Self-Encrypting Drive (SED) widget displays the ATA security user and password configured on the system.
Click Configure to open the Self-Encrypting Drive configuration screen. The Self-Encrypting Drive configuration screen allows users set the ATA security user and create a SED global password.
Select the user passed to camcontrol security -u to unlock SEDs from the ATA Security User dropdown list. Options are USER or MASTER.
Enter the global password to unlock SEDs in SED Password and in Confirm SED Password.
Click Save.
Systems with more than one graphics processing unit (GPU) installed can isolate additional GPU device(s) from the host operating system (OS) and allocate them for use by a virtual machine (VM). Isolated GPU devices are unavailable to the OS and for allocation to applications.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Isolated GPU Device(s) widget on the System > Advanced screen shows configured isolated GPU device(s).
To isolate a GPU, you must have at least two in your system; one available to the host system for system functions and the other available to isolate for use by a VM. One isolated GPU device can be used by a single VM. Isolated GPU cannot be allocated to applications.
To allocate an isolated GPU device, select it while creating or editing VM configuration. When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM and becomes unavailable for any other allocations.
Click Configure on the Isolated GPU Device(s) widget to open the Isolate GPU PCI Ids screen, where you can select a GPU device to isolate.
Select the GPU device(s) to isolate from the dropdown list.
Click Save.
Global Two-factor authentication (2FA) is great for increasing security.
TrueNAS offers global 2FA to ensure that entities cannot use a compromised administrator root password to access the administrator interface.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
To use 2FA, you need a mobile device with the current time and date, and an authenticator app installed. We recommend Google Authenticator. You can use other authenticator applications, but you must confirm the settings and QR codes generated in TrueNAS are compatible with your particular app before permanently activating 2FA.
Two-factor authentication is time-based and requires a correct system time setting. Ensure Network Time Protocol (NTP) is functional before enabling two-factor authentication is strongly recommended!
Unauthorized users cannot log in since they do not have the randomized six-digit code.
Authorized employees can securely access systems from any device or location without jeopardizing sensitive information.
Internet access on the TrueNAS system is not required to use 2FA.
2FA requires an app to generate the 2FA code.
If the 2FA code is not working or users cannot get it, the system is inaccessible through the UI and SSH (if enabled). You can bypass or unlock 2FA using the CLI.
Set up a second 2FA device as a backup before proceeding.
Before you begin, download Google Authenticator to your mobile device.
Go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save.
If you want to enable two-factor authentication for SSH logins, select Enable Two-Factor Auth for SSH before you click Save.
TrueNAS takes you to the Two-Factor Authentication screen to finish 2FA setup.
When using Google Authenticator, set Interval to 30 or the authenticator code might not function when logging in.
Click Show QR and scan the QR code using Google Authenticator.
After scanning the code click CLOSE to close the dialog on the Two-Factor Authentication screen.
Accounts that are already configured with individual 2FA are not prompted for 2FA login codes until Global 2FA is enabled. When Global 2FA is enabled, user accounts that have not configured 2FA settings yet are shown the Two-Factor Authentication screen on their next login to configure and enable 2FA authentication for that account.
Go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config. Clear the Enable Two-Factor Authentication Globally checkbox and click Save.
If the device with the 2FA app is not available, you can use the system CLI to bypass 2FA with administrative IPMI or by physically accessing the system.
To unlock 2FA in the SCALE CLI, enter:
auth two_factor update enabled=false
If you want to enable 2FA again, go to System Settings > Advanced, scroll down to the Global Two Factor Authentication widget, and click Config.
Check Enable Two Factor Authentication Globally, then click Save. To change the system-generated Secret, go to Credentials > 2FA and click Renew 2FA Secret.
Enabling 2FA changes the login process for both the TrueNAS web interface and SSH logins.
The login screen adds another field for the randomized authenticator code. If this field is not immediately visible, try refreshing the browser.
Enter the code from the mobile device (without the space) in the login window and use the root username and password.
If you wait too long, a new number code displays in Google Authenticator, so you can retry.
Confirm that you set Enable Two-Factor Auth for SSH in System Settings > Advanced > Global Two Factor Authentication.
Go to System Settings > Services and edit the SSH service.
a. Set Log in as Admin with Password, then click Save.
b. Click the SSH toggle and wait for the service status to show that it is running.
Open the Google Authentication app on your mobile device.
Open a terminal (such as Windows Shell) and SSH into the system using either the host name or IP address, the administrator account user name and password, and the 2FA code.
Developer mode is for developers only. Users that enable this functionality will not receive support on any issues submitted to iXsystems.
Only enable when you are comfortable with debugging and resolving all issues encountered on the system. Never enable on a system that has production storage and workloads.
TrueNAS is an Open Source Storage appliance, not a standard Linux operating system (OS) that allows customization of the OS environment.
By default, the root/boot filesystem and tools such as apt
are disabled to prevent accidental misconfiguration that renders the system inoperable or puts stored data at risk.
However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.
Do not make system changes using the TrueNAS UI web shell. Using package management tools in the web shell can result in middleware changes that render the system inaccessible.
Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.
To enable developer mode, log into the system as the root account and access the Linux shell.
Run the install-dev-tools
command.
Running install-dev-tools
removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS.
These changes do not persist across updates and install-dev-tools
must be re-run after every system update.
System Settings > Boot contains options for monitoring and managing the ZFS pool and devices that store the TrueNAS operating system.
The Stats/Settings option displays current system statistics and provides the option to change the scrub interval, or how often the system runs a data integrity check on the operating system device.
Go to System Settings > Boot screen and click Stats/Settings. The Stats/Settings window displays statistics for the operating system device: Boot pool Condition as ONLINE or OFFLINE, Size in GiB and the space in use in Used, and Last Scrub Run with the date and time of the scrub. By default, the operating system device is scrubbed every 7 days.
To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.
From the System Settings > Boot screen, click the Boot Pool Status button to open the Boot Pool Status screen. This screen shows the boot-pool and expands to show the devices that are allocated to that pool. Read, write, or checksum errors are also shown for the pool.
A manual data integrity check (scrub) of the operating system device can be initiated at any time.
On the System Settings > Boot screen, and click Scrub Boot Pool to open the Scrub dialog.
Click Confirm and then Start Scrub.
TrueNAS supports a ZFS feature known as boot environments. These are snapshot clones of the TrueNAS boot-pool install location that TrueNAS boots into. Only one boot environment is used for booting at a time.
A boot environment allows rebooting into a specific point in time and greatly simplifies recovering from system misconfigurations or other potential system failures. With multiple boot environments, the process of updating the operating system becomes a low-risk operation.
For example, the TrueNAS update process automatically creates a snapshot of the current boot environment and adds it to the boot menu before applying the update. If anything goes wrong during the update, the system administrator can activate the snapshot of the pre-update environment and reboot TrueNAS to restore system functionality.
Boot environments do not preserve or restore the state of any attached storage pools or apps, only the system boot-pool. Storage backups must be handled through the ZFS snapshot feature or other backup options. TrueNAS applications also use separate upgrade and container image management methods to provide app update and rollback features.
To view the list of boot environments on the system, go to System Settings > Boot. Each boot environment entry contains this information:
To access more options for a boot environment, click to display the list of options:
System Settings > Services displays each system component that runs continuously in the background. These typically control data-sharing or other external access to the system. Individual services have configuration screens and activation toggles, and you can set them to run automatically.
Documented services related to data sharing or automated tasks are in their respective Shares and Tasks articles.
The File Transfer Protocol (FTP) is a simple option for data transfers. The SSH options provide secure transfer methods for critical objects like configuration files, while the Trivial FTP options provide simple file transfer methods for non-critical files.
Options for configuring FTP, SSH, and TFTP are in System Settings > Services. Click the edit to configure the related service.
FTP requires a new dataset and a local user account.
Go to Storage to add a new dataset to use as storage for files.
Next, add a new user. Go to Credentials > Local Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory. You can do this for every user or create a global account for FTP (for example, OurOrgFTPaccnt).
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields. Select Apply User and Apply Group. Select the Read, Write, and Execute for User, Group, and Other you want to apply. Click Save.
To configure FTP, go to System Settings > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
To confine FTP sessions to the home directory of a local user, select both chroot and Allow Local User Login.
Do not allow anonymous or root access unless it is necessary. Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Click Save and then start the FTP service.
FTP requires a new dataset and a local user account.
Go to Storage and add a new [dataset]](/scale/scaletutorials/datasets/datasetsscale/).
Next, add a new user. Go to Credentials > Local Users and click Add to create a local user on the TrueNAS.
Assign a user name and password, and link the newly created FTP dataset as the user home directory. Then, add ftp to the Auxiliary Groups field and click Save.
Edit the file permissions for the new dataset. Go to Datasets, then click on the name of the new dataset. Scroll down to Permissions and click Edit.
Enter or select the new user account in the User and Group fields. Enable Apply User and Apply Group. Select the Read, Write, and Execute for User, Group, and Other you want to apply, then click Save.
Go to System Settings > Services and find FTP, then click edit to open the Services > FTP screen.
Configure the options according to your environment and security considerations. Click Advanced Settings to display more options.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
To confine FTP sessions to the home directory of a local user, select chroot.
Do not allow anonymous or root access unless it is necessary. Enable TLS when possible (especially when exposing FTP to a WAN). TLS effectively makes this FTPS for better security.
Click Save, then start the FTP service.
Use a browser or FTP client to connect to the TrueNAS FTP share. The images below use FileZilla, which is free.
The user name and password are those of the local user account on the TrueNAS system. The default directory is the same as the user home directory. After connecting, you can create directories and upload or download files.
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
You can access it from System Settings > Services screen. Locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
We recommend using the default NFS settings unless you require specific settings.
Select the IP address from the Bind IP Addresses dropdown list if you want to use a specific static IP address, or leave this field blank for NFS to listen to all available addresses.
By default, TrueNAS dynamically calculates the number of threads the kernel NFS server uses. However, if you want to manually enter an optimal number of threads the kernel NFS server uses, clear Calculate number of threads dynamically and enter the number of threads you want in the Specify number of threads manually field.
If using NFSv4, select NFSv4 from Enabled Protocols. NFSv3 ownership model for NFSv4 clears, allowing you to enable or leave it clear.
If you want to force NFS shares to fail if the Kerberos ticket is unavailable, select Require Kerberos for NFSv4.
Next, enter a port to bind to in the field that applies:
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
Only select Allow non-root mount if the NFS client requires it to allow serving non-root mount requests.
Select Support > 16 groups when a user is a member of more than 16 groups. This setting assumes group membership is configured correctly on the NFS server.
Click Save.
Start the NFS service.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
There is a special consideration when installing TrueNAS in a Virtual Machine (VM), as S.M.A.R.T services monitor actual physical devices, which are abstracted in a VM. After the installation of TrueNAS completes on the VM, go to System Settings > Services > and click the blue toggle button on the S.M.A.R.T. service to stop the service from running. Clear the Start Automatically checkbox so the service does not automatically start when the system reboots.
Use the Services > S.M.A.R.T. screen to configure when S.M.A.R.T. tests run and when to trigger alert warnings and send emails.
Click the edit Configure icon to open the screen.
Enter the time in minutes smartd to wake up and check if any tests are configured to run in Check Interval.
Select the Power Mode from the dropdown list. Choices include Never, Sleep, Standby, and Idle. TrueNAS only performs tests when you select Never.
Set the temperatures that trigger alerts in Difference, Informational and Critical.
Click Save after changing any settings.
Start the service.
The Services > SMB screen displays after going to the Shares screen, finding the Windows (SMB) Shares section, and clicking
+ Config Service. Alternatively, you can go to System Settings > Services and click the edit icon for the SMB service.The SMB Services screen displays setting options to configure TrueNAS SMB settings to fit your use case. In most cases, you can set the required fields and accept the rest of the setting defaults. If you have specific needs for your use case, click Advanced Options to display more settings.
Enter the name of the TrueNAS host system if not the default displayed in NetBIOS Name. This name is limited to 15 characters and cannot be the Workgroup name.
Enter any alias name or names that do not exceed 15 characters in the NetBIOS Alias field. Separate each alias name with a space between them.
Enter a name that matches the Windows workgroup name in Workgroup. TrueNAS detects and sets the correct workgroup from these services when unconfigured with enabled Active Directory or LDAP active.
If using SMB1 clients, select Enable SMB1 support to allow legacy SMB1 clients to connect to the server. Note: SMB1 is deprecated. We advise you to upgrade clients to operating system versions that support modern SMB protocol versions.
If you plan to use the insecure and vulnerable NTLMv1 encryption, select NTLMv1 Auth to allow smbd attempts to authenticate users. This setting enables backward compatibility with older versions of Windows, but we don’t recommend it. Do not use on untrusted networks.
Enter any notes about the service configuration in Description
For more advanced settings, see SMB Services Screen.
Use Auxiliary Parameters to enter additional smb.conf options, or to log more details when a client attempts to authenticate to the share, add log level = 1, auth_audit:5
. Refer to the Samba Guide for more information on these settings.
Click Save.
Start the SMB service.
SNMP (Simple Network Management Protocol) monitors network-attached devices for conditions that warrant administrative attention. TrueNAS uses Net-SNMP to provide SNMP. To configure SNMP, go to System Settings > Services page, find SNMP, and click the edit.
See SNMP Service Screen for setting information.
Port UDP 161 listens for SNMP requests when starting the SNMP service.
Click to view or download a static copy of the SCALE 24.10 (Electric Eel) MIB file.
To download an MIB from your TrueNAS system, you can enable SSH and use a file transfer command like scp
.
When using SSH, make sure to validate the user logging in has SSH login permissions enabled and the SSH service is active and using a known port (22 is default).
Management Information Base (MIB) files are located in
Example (replace mytruenas.example.com with your system IP address or hostname):
PS C:\Users\ixuser> scp admin@mytruenas.example.com:/usr/local/share/snmp/mibs/* .\Downloads\
admin@mytruenas.example.com's password:
TRUENAS-MIB.txt 100% 11KB 112.0KB/s 00:00
PS C:\Users\ixuser>
The SSH service lets users connect to TrueNAS with the Secure SHell Transport Layer Protocol. When using TrueNAS as an SSH server, the users in the network must use SSH client software to transfer files with SSH.
Allowing external connections to TrueNAS is a security vulnerability! Do not enable SSH unless you require external connections. See Security Recommendations for more security considerations when using SSH.
To configure SSH go to System Settings > Services, find SSH, and click edit to open the basic settings General Options configuration screen.
Use the Password Login Groups and Allow Password Authentication settings to allow specific TrueNAS account groups the ability to use password authentication for SSH logins.
Click Save. Select Start Automatically and enable the SSH service.
If your configuration requires more advanced settings, click Advanced Settings. The basic options continue to display above the Advanced Settings screen. Configure the options as needed to match your network environment.
These Auxiliary Parameters can be useful when troubleshooting SSH connectivity issues:
ClientAliveInterval
if SSH connections tend to drop.MaxStartups
value (10 is default) when you need more concurrent SSH connections.Remember to enable the SSH service in System Settings > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
SFTP (SSH File Transfer Protocol) is available by enabling SSH remote access to the TrueNAS system. SFTP is more secure than standard FTP as it applies SSL encryption on all transfers by default.
Go to System Settings > Services, find the SSH entry, and click the edit to open the Services > SSH basic settings configuration screen.
Select Allow Password Authentication.
Go to Credentials > Local Users. Click anywhere on the row of the user you want to access SSH to expand the user entry, then click Edit to open the Edit User configuration screen. Make sure that SSH password login enabled is selected. See Managing Users for more information.
SSH with root is a security vulnerability. It allows users to fully control the NAS remotely with a terminal instead of providing SFTP transfer access.
Choose a non-root administrative user to allow SSH access.
Review the remaining options and configure them according to your environment or security needs.
Remember to enable the SSH service in System Settings > Services after making changes.
Create and store SSH connections and keypairs to allow SSH access in Credentials > Backup Credentials or by editing an administrative user account. See Adding SSH Credentials for more information.
Open an FTP client (like FileZilla) or command line. This article shows using FileZilla as an example.
Using FileZilla, enter SFTP://{TrueNAS IP} {username} {password} {port 22}
. Where {TrueNAS IP} is the IP address for your TrueNAS system, {username} is the administrator login user name, and {password} is the adminstrator password, and {port 22} to connect.
SFTP does not offer chroot locking. While chroot is not 100% secure, lacking chroot lets users move up to the root directory and view internal system information. If this level of access is a concern, FTP with TLS might be the more secure choice.
An Uninterruptible Power Supply (UPS) is a power backup system that ensures continuous electricity during outages, preventing downtime and damage.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support. For supported device and driver information, see their hardware compatibility list.
Report UPS bugs and feature requests to the NUT project.
Connect the TrueNAS system to the UPS device. To configure the UPS service, go to System settings > Services, finding UPS, and click edit.
See UPS Service Screen for details on the UPS service settings.
TrueNAS EnterpriseTrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
Some UPS models are unresponsive with the default polling frequency (default is two seconds).
TrueNAS displays the issue in logs as a recurring error like libusb_get_interrupt: Unknown error.
If you get an error, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10
.
The SCALE Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information.
Warning! The supported mechanisms for making configuration changes are the TrueNAS WebUI, CLI, and API exclusively. All other are not supported and result in undefined behavior that can result in system failure!
The Set font size slider adjusts the Shell displayed text size. Restore Default resets the font size to default.
The Shell stores the command history for the current session.
Leaving the Shell screen clears the command history.
Click Reconnect to start a new session.
This section provides keyboard navigation shortcuts you can use in Shell.
zsh is the default shell, but you can change this by going to Credentials > Local Users. Select the admin or other user to expand it. Click Edit to open the Edit User screen. Scroll down to Shell and select a different option from the dropdown list. Most Linux command-line utilities are available in the Shell. Click Save.
Admin users can set the Shell to default to the TrueNAS CLI by selecting TrueNAS CLI in Shell on the Edit User screen. See SCALE CLI Reference Guide for more information on using the TrueNAS CLI. To change the Shell to default to the Console Setup Menu, select TrueNAS Console in Shell on the Edit User screen.
Clicking other SCALE UI menus options closes the shell session and stops commands running in the Shell screen.
Tmux allows you to detach sessions in Shell and then reattach them later. Commands continue to run in a detached session.
The new SCALE command-line interface (CLI) lets you directly configure SCALE features using namespaces and commands based on the SCALE API.
TrueNAS CLI is still in active development. We are not accepting bug reports or feature requests at this time.
See SCALE CLI Reference Guide for more information on using the TrueNAS CLI.
We intend the CLI to be an alternative method for configuring TrueNAS features. Because of the variety of available features and configurations, we include CLI-specific instructions in their respective UI documentation sections.
TrueNAS SCALE auditing and logs provide a trail of all actions performed by a session, user, or service (SMB, middleware).
The audit function backends are both the syslog and the Samba debug library. Syslog sends audit messages via explicit syslog call with configurable priority (WARNING is the default) and facility (for example, USER). The default is syslog sent audit messages. Debug sends audit messages from the Samba debug library and these messages have a configurable severity (WARNING, NOTICE, or INFO).
The System Settings > Audit screen lists all session, user, or SMB events. Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).
SCALE includes a manual page with more information on the VFS auditing functions.
Administrative users can enter
man vfs_truenas_audit
in a SCALE command prompt to view the embedded manual page.
Events are organized by session and user, and SMB auditing.
Session and user auditing events
Audit records contain information that establishes:
Each audit message is a single JSON file containing mandatory fields. It can also include additional optional records. Message size is limited to not exceed 1024 bytes for maximum portability with different syslog implementations.
Use the Export to CSV button on an audit screen to download audit logs in a format readable in a spreadsheet program. Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file. The JSON object for an audit message contains the version information, the service which is the name of the SMB share, a session ID and the tree connection (tcon_id).
Authentication and other events are captured by the TrueNAS audit logging functions. The TrueNAS SCALE auditing logs event data varies based on the type of event tracked.
Users have access to audit information from three locations in the SCALE UI:
Click Audit Logging on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user.
Click Audit Logging on the SMB row on the Services screen to open the Audit log screen with the Search field filter added to show only SMB events.
The main System Settings > Audit screen shows all system events such as authentication and SMB events.
The audit screen includes basic and advanced search options. Click Switch to Basic to change to the basic search function or click Switch to Advanced to show the advanced search operators.
You can enter any filters in the basic Search field to show events matching the entry.
To enter advanced search parameters, use the format displayed in the field, for example, Service = “SMB” AND Event = “CLOSE” to show closed SMB events. Event types are listed in Auditing Event Types.
Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering. Parentheses define query priority. Clicking the advanced Search field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.
For example, to search for any SMB connect or close event from the user smbuser or any non-authentication SMB events, enter (Service = "SMB" AND Event in ("Connect", "Close") AND User in ("smbuser")) OR (Event != "Authentication" AND Service = "SMB")
.
The advanced search automatically checks syntax and shows done when the syntax is valid and warning for invalid syntax.
Click on a row to show details of that event in the Metadata and Event Data widgets.
Export as CSV sends the event log data to a csv file you can open in a spreadsheet program (i.e., MS Excel, Google Sheets, etc.) or other data management app that accept CSV files.
The assignment (Copy to Clipboard) icon shows two options, Copy Text and Copy Json. Copy Text copies the event to a text file. Copy Json copies the event to a JSON object.
Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.
SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.
From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.
Selecting Enable turns auditing on for the share you are creating or editing.
Use the Watch List and Ignore List functions to add audit logging groups to include or exclude. Click in Watch List to see a list of user groups on the system. Click on a group to add it to the list and record events generated by user accounts that are members of the group. Leave Watch List blank to include all groups, otherwise auditing is restricted to only the groups added.
Click in Ignore List to see a list of user groups on the system.. Click on a group to add it to the list and explicitly avoid recording any events generated by user accounts that are members of this group.
The Watch List takes precedence over the Ignore List when using both lists.
Click Save.
To configure session auditing settings, go to System Settings > Advanced, then click Configure on the Audit widget.
Welcome to the TrueNAS SCALE UI Reference Guide!
This document shows and describes each screen and configurable option contained within the TrueNAS web interface. The document is arranged in a parallel manner to the TrueNAS web interface, beginning with the top panel and then descending through each option displayed in the web interface left side menu. To display this document in a linear HTML format, export it to PDF, or physically print it, please select ⎙ Download or Print.
The top toolbar icon buttons provide access to the iXsystems website, displays the status of TrueCommand and directory services configured on your system, and displays other configuration menu options.
Icon | Name | Description |
---|---|---|
Toggle collapse | Click to expand or collapse the main menu panel on the left side of the screen. | |
iXsystems | Opens the iXsystems home page website where users can find information about storage and server systems. Users can also use the iXsystems home page to access their customer portal and community section for support. | |
How would you rate this page? | Opens the How would you rate this page? feedback window for sending UI ratings, bug reports, and improvement suggestions to the TrueNAS developers. | |
Status of TrueCommand | Displays either the status of a TrueCommand cloud connection or a dialog that allows users to sign up for a new TrueCommand cloud connection. | |
Update Status | Shows the system update progress and which user account started the update. Only appears in the top bar when a TrueNAS system update starts. | |
Directory Services status | Displays a dialog with the status of Active Directory and LDAP directory servers configured on the system. | |
Jobs | Displays the Jobs dialog. Click the History button to display the Tasks screen with a list of All, Active or Failed tasks or processes. | |
Alerts | Displays a list of system alerts and a dropdown list with the alert options Alert Settings and Email. | |
Settings | Displays a dropdown list of setting options Change Password, Two-Factor Authentication, API Keys, Guide and About. | |
Power options | Displays the power related options Log Out, Restart or Shut Down. |
The How would you rate this page? icon opens a feedback window. Alternately, go to System Settings > General, find the Support widget, and click File Ticket to see the feedback window.
The feedback window allows users to send page ratings, comments, and report issues or suggest improvements directly to the TrueNAS development team. Submitting a bug report or improvement suggestion requires a free Atlassian account.
Click between the different tabs at the top of the window to see different options for your specific feedback.
The Status of TrueCommand icon lets users sign up with and connect to TrueCommand Cloud.
Clicking Signup opens the TrueCommand sign-up page in a new tab.
After users sign up, they can click the Connect button and enter their API key to connect SCALE to TrueCommand Cloud.
TrueNAS displays a message telling users to check their email for verification instructions.
The Directory Services Monitor
icon button displays the status of Active Directory and LDAP services.Click on either service to go to its configuration screen.
The Jobs
icon button displays all running and failed jobs/processes. Users can see minimized jobs/processes here.Users can minimize a job/process by clicking the minus (-) at the top right corner of any dialog or pop-up window.
Click on a running task to display a dialog for that running task.
You can abort active jobs (for example, wiping a disk) by clicking the white circled X next to the active job.
Click on History to open the Tasks screen with lists of all successful, active, and failed jobs. Click on the All, Active, or Failed button at the top of the screen to show the log of jobs that fit that classification.
Click View next to a task to see the log information and error message for that task.
For more information, see Tasks Screens.
The Alerts
icon displays a list of current alert notifications. To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.Use the
icon to display the Alerts dropdown list with two options: Alert Settings and Email.Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you. See Alerts Settings Screens for more information.
TrueNAS EnterpriseThe Alert Settings Screens article includes information about the SCALE Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.
The
Settings icon button displays a menu of general system settings options. The options are Change Password, Two-Factor Authentication, Preferences, API Keys, Guide and About.The
Change Password icon button displays a dialog where you can change the login password for the currently logged-in administrator password.The Two-Factor Authentication icon button opens the Two-Factor Authentication Screen.
The API Keys screen that lists current API keys and where you can add or manage API keys that identify outside resources and applications without a principal.
API Keys icon button displays theThe
Guide icon button opens the TrueNAS Documentation Hub website in a new browser tab.The
About icon button displays a window with links to the TrueNAS Documentation Hub, the TrueNAS Community Forums, the FreeNAS Open Source Storage Appliance GitHub repository, and the iXsystems home page. Use the Close button to close the window.The Power
button provides three options that let the user log out of the web UI, restart, or shut down their TrueNAS system.The Alerts
icon displays a list of current alert notifications. To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.Use the
icon to display the Alerts dropdown list with two options: Alert Settings and Email.Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you. See Alerts Settings Screens for more information.
TrueNAS EnterpriseThe Alert Settings Screens article includes information about the SCALE Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts. See Setting Up System Email for information about configuring the system email service and alert emails.
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies. To access this screen, click the
icon, then click the icon and select Alert Settings on the dropdown list.Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default. To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the
icon for the service, and then click Edit to display the Edit Alert Service screen.Setting | Description |
---|---|
Name | Enter a name for the new alert service. |
Enabled | Clear the checkmark to disable this service without deleting it. |
Type | Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS. |
Level | Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. |
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Use the Category dropdown list to display alert settings for each category.
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
TrueNAS Enterprise
Hardware alert settings apply to the IPMI network connections, and S.M.A.R.T. and smartd that monitors the hard drives installed on your TrueNAS system.
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Plugins alert settings apply to plugins installed on your TrueNAS.
Network alert settings apply to network interfaces configured on your TrueNAS.
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system reboots, updates, and the web interface.
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
UPS alert settings apply to a UPS connected to your TrueNAS.
Use the Set Warning Level dropdown list to customize alert importance. Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
Level | Icon | Alert Notification? |
---|---|---|
INFO | No | |
NOTICE | Yes | |
WARNING | Yes | |
ERROR | Yes | |
CRITICAL | Yes | |
ALERT | Yes | |
EMERGENCY | Yes |
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
The top toolbar Alerts
icon button and icon display the Alerts dropdown list with two options: Alert Settings and Email.Select Email to go to the General settings screen and find the Email widget.
The Email widget on the General settings screen displays information about current system mail settings.
Settings opens the Email Options screen that allows users to configure the system email send method.
An automatic script sends a nightly email to the administrator account containing important information such as the health of the disks. Users must first configure an email address for the admin account or another administrative user in Credentials > Local Users.
The Email Options screen offers two options to set up email. Select either SMTP or GMail OAuth. The configuration settings change based on the selected radio button.
If SMTP is selected, the screen displays the SMTP configuration fields.
Setting | Description |
---|---|
From Email | The email address to use for sending emails. You must first configure the user account email in Credentials > Local Users. |
From Name | The name to show in front of the sending email address, for example: TrueNAS. |
Outgoing Mail Server | Host name or IP address of SMTP server to use for sending emails. |
Mail Server Port | SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission). |
Security | Select the security option from the dropdown list. Options are Plain (No Encryption), SSL (Implicit TLS), or TLS (STARTTLS). See email encryption for more information on types. |
SMTP Authentication | Select to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password. |
Username | Displays when SMTP Authentication is selected. The user name for the sending email account, typically the full email address. |
Password | Displays when SMTP Authentication is selected. The password for the sending email account. |
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
If GMail OAuth is selected, the screen displays Log in to Gmail to set up Oauth Credentials and the Log In To Gmail button.
After setting up Gmail OAuth authentication, the screen displays Gmail credentials have been applied and the button changes to Log In To Gmail Again.
Send Test Mail generates a test email to confirm the system email works correctly.
Save stores the email configuration and closes the Email Options screen.
The
Settings icon button displays a menu of general system settings options. The options are Change Password, Preferences, API Keys, Guide and About.Click on the Change Password
icon button to display the change password dialog where you can enter a new password for the currently logged-in user.Click on the
icon to display entered passwords. To stop displaying the password, click on the icon.Click on
API Keys to display the API Keys screen where you can add new or manage existing API keys on your system.Click on
Guide to display the TrueNAS Documentation Hub in a new tab.Click on About to display the information window links to the TrueNAS Documentation Hub, TrueNAS Community Forums, FreeNAS Open Source Storage Appliance GitHub repository, and iXsystems home page.
The API Keys option on the top toolbar Settings dropdown menu displays the API Keys screen. This screen displays a list of TrueNAS SCALE API keys on your system and allows you to add, edit, or delete keys.
Click the icon to the right of an API key to display options for that key. API key options are Edit and Delete.
Use Add to add a new API key to your TrueNAS.
Always back up and secure keys. The key string displays only one time, at creation!
To manage API keys in the TrueNAS SCALE CLI, use theauth api_key
namespace.
Click API Docs to access API documentation for your system.
The Tasks screens, accessed from the Jobs list after clicking History, displays all jobs executed on the system.
There are three tab views, All, Active and Failed. All displays by default.
Use the arrow display options to change the number of jobs per screen. Options are the default 10, 50 or 100.
Click View to display the argument passed for the selected job.
Use the
arrow beside the State or ID header to change the display order, or the arrow to return to the top down display order.The Failed screen displays the list of failed jobs.
Use the View button to display the task log. The system error for this failed job displays at the bottom of the log file.
The Dashboard screen displays the first time you log into the SCALE web interface. To display the Dashboard screen again click Dashboard on the left side panel.
The Dashboard displays basic information about your TrueNAS system in widgets or information cards that group information about your TrueNAS by type. For example, CPU information appears in the CPU widget. These widgets display in a default layout that you can change.
Use the Reorder button to change the layout of the various widgets to suit your preference.
Use Configure turn the widget display on or off. When on, the widget displays on the dashboard.
The Dashboard Configuration panel allows you to turn widget displays on or off. There are three widget group types: System Widgets, Storage Widgets and Network Widgets. Storage and network widgets vary based on the pools and network interfaces configured on your TrueNAS.
Click on the slider to turn the information display on or off.
System Widgets control the display of the System Information, Help, CPU, Memory, and Backup widgets.
Storage Widgets control the display of the Storage widget and individual widgets for each pool configured on your TrueNAS.
Network Widgets control the display of the Network widget and any individual interfaces configured on your TrueNAS.
Use Save to retain any setting changes you make. Click on the X or on any part of the UI screen away from the Dashboard Configure panel to close it without saving changes.
Click on the assessment icon to display the report screen that corresponds to that widget. For example, clicking the assessment icon on the CPU widget opens the Reporting > CPU screen.
The System Information widget displays general information about the SCALE system. It includes an option to synchronize the system server time with TrueNAS SCALE time if they get out of sync.
The CPU widget displays information on the system CPU.
The Memory widget displays information on the system memory.
The Network widget displays network the status of the system interfaces, link status, and the system IP address and port number. Clicking assessment opens the Reporting screen and shows more network statistics.
The Interface widgets display traffic stats, link status, and provide more information on that interface media type and subtype, any VLANS and the IP Address and port number.
The Storage widget displays information on the root and other storage pools configured on your system.
When no backup tasks exist, this shows links to quickly set up an automated data backup schedule. Click open_in_new to open the Data Protection screen with all options for checking or backing up stored data.
When a backup task exists, the widget shows details about the various backup tasks that are configured on the system.
Details provided include how many tasks of each type of backup exist, if they send or receive data, how many times tasks have failed and succeeded, and weekly success counters.
The TrueNAS Help widget displays links to the TrueNAS Documentation Site and TrueNAS Community Forums. It also includes a link where users can sign up for the TrueNAS Newsletter, and a link to the Github web page for TrueNAS Open Source software. There is also a link for the iXsystems home page.
Click on each link to open it in a new browser tab.
The Storage Dashboard screen allows users to configure and manage storage resources such as pools (VDEVs), and disks, and keep the pool healthy (scrub). The dashboard widgets organize functions related to storage resources.
The No Pools screen displays before you add the first pool.
The Create Pool button in the center of the screen opens the Pool Creation Wizard screen.
The buttons at the top right of the Storage Dashboard screen provide access to pool and disk functions:
Disks opens the Disks screen.
Create Pool opens the Pool Creation Wizard.
After adding pools, the dashboard shows storage widgets and two more buttons.
After adding a pool, the screen displays storage widgets. The same set of four widgets and the Export/Disconnect and Expand buttons display for each pool created on the system. The Unassigned Disks widget at the top of the Storage Dashboard only shows when there are disks available to add to a new or existing pool.
Each set of pool widgets provides access to screens for disks, datasets, VDEVs, snapshots, quotas, and pool ZFS functions for the pool. For example, Manage Devices on the Topology widget opens the Devices screen with the VDEVs configured for only that pool.
The Unassigned Disks widget displays the number of disks available on your system to use in pools. The disk count includes disks assigned in an exported pool. If you attempt to use a disk assigned in an exported pool, a warning message displays that prompts you to select a different disk.
To see information on each disk on the system, click Manage Disks on the Disk health widget
The Topology widget shows information on the VDEVs configured on the system and the status of the pool.
The widget lists each VDEV type (data, metadata, log, cache, spare, and dedup). A Data VDEV includes the data type (stripe, mirror, RAID, or mixed configuration), the number of disks (wide), and the storage capacity of that VDEV.
Manage Devices opens the Devices screen where you can add or manage existing VDEVs.
The Usage widget shows information on the space datasets consume in the pool, and the status of pool usage.
The widget includes a color-coded donut chart that illustrates the percentage of space the pool uses. Blue indicates space usage in the 0-80% range and red indicates anything above 80%. A warning displays below the donut graph when usage exceeds 80%.
Usable Capacity details pool space statistics by Used, Available, and Used by Snapshots.
View Disk Space Reports opens the pool usage reports for the selected pool.
Large (>1 petabyte) systems could report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits. For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Manage Datasets opens the Datasets screen.
The ZFS Health widget shows information on the health of the pool.
Widget details include:
View all Scrub Tasks opens the Data Protections > Scrub Tasks details screen. This lists all scheduled scrub tasks and allows you to add a new or edit an existing task.
The Disk Health widget shows information on the health of the disks in a pool. The details on the widget include the non-dismissed disk temperature alerts for highest, lowest, and average temperature, and failed S.M.A.R.T. tests.
Manage Disks opens the Storage > Disk screen.
View Reports opens the Report screen for the disks in the selected pool.
View all S.M.A.R.T. Tests opens the Data Protection > S.M.A.R.T. Tests screen.
Each widget in the set of four pool widgets includes a color-coded icon just to the right of the header. This icon indicates the status of the pool as healthy (green checkmark), offline (orange triangle), or in a warning state (purple warning sign).
This same information displays on both the Storage widget and a pool widget you can add to the Dashboard.
The Storage Dashboard shows the Upgrade button for existing pools after an upgrade to a new TrueNAS release that includes new OpenZFS feature flags. Newly created pools are always up to date with the OpenZFS feature flags available in the installed TrueNAS release.
Storage pool upgrades are typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation. Consider these factors before upgrading a storage pool to the latest OpenZFS feature flags.
Upgrading can affect data. Before performing any operation that affects data on a storage disk, always back up data first and verify the backup integrity.
New OpenZFS feature flags are permanently applied to the upgraded pool. An upgraded pool cannot be reverted or downgraded to an earlier OpenZFS version. A storage pool with the latest feature flags cannot import into another operating system that does not support those feature flags.
Upgrading a ZFS pool is optional. Do not upgrade the pool when reverting to an earlier TrueNAS version or repurposing the disks in another operating system that supports ZFS is a requirement.
The upgrade itself only takes a few seconds and is non-disruptive. It is not necessary to stop any sharing services to upgrade the pool. However, it is best to upgrade when the pool is not in heavy use. The upgrade process suspends I/O for a short period but is nearly instantaneous on a quiet pool.
The Disks screen lists the physical drives (disks) installed in the system. The list includes the names, serial numbers, sizes, and pools for each system disk.
Use the Columns dropdown list to select options to customize disk the information displayed. Options are Select All, Serial (the disk serial number), Disk Size, Pool (where the disk is in use), Disk Type, Description, Model, Transfer Mode, Rotation Rate (RPM), HDD Standby, Adv. Power Management, Enable S.M.A.R.T., S.M.A.R.T. extra options, and Reset to Defaults. Each option displays the information you enter in the Edit Disk screen or when you install the disk.
Select the checkbox to the left of a disk to display the Batch Operations options. The checkbox at the top of the table selects all disks in the system. Select again to clear the checkboxes.
Storage in the breadcrumb at the top of the screen returns to the Storage Dashboard.
Click anywhere on a disk row to expand it and show the traits specific to that disk and available options. The expanded view of a disk includes details for the disk and options to edit disk properties, run a SMART test and view the test results, and in some instances the ability to wipe the disk.
Edit opens the Edit Disk screen.
Manual Test opens the Manual S.M.A.R.T. test where you can initiate a S.M.A.R.T. test of the disk.
S.M.A.R.T. Test Results opens the S.M.A.R.T. Test Results of diskname screen with the results of each S.M.A.R.T. test run for that disk.
Wipe opens the Wipe Disk dialog.
Select a checkbox to the left of a disk on the Disks screen to display the Batch Operations functions: Edit Disk(s) and Manual Test.
Edit Disk(s) opens the Bulk Edit Disks screen.
Manual Test opens the Manual SMART Test dialog with a list of the disk(s) selected.
The Bulk Edits Disks screen allows you to change disk settings for multiple disks simultaneously. The screen lists the device names for each selected disk in the Disks to be edited section.
The Manual S.M.A.R.T. Test dialog displays the name of the selected disk(s) and the option to specify the type of test you want to run outside of a scheduled S.M.A.R.T. test.
The S.M.A.R.T. Test Results of diskname lists test results for the selected disk. The Storage and Disks breadcrumbs return to other storage pages. Storage opens the Storage Dashboard and Disks opens the Disks screen.
The option to wipe a disk only displays when a disk is unused by a pool. Wipe opens three dialogs, one to select the method, a confirmation dialog, and a progress dialog that includes the option to abort the process.
The Wipe Disk diskname opens after clicking Wipe on the expanded view of a disk on the Disks screen.
Method provides options for how you want the system to wipe the disk. Options are Quick, Full with zeros, or Full with random data. See Wiping Disks for more information.
Wipe opens the wipe disk confirmation dialog.
Confirm activates Continue, and Continue starts the disk wipe process and opens a progress dialog with the Abort button.
Abort stops the disk wipe process. At the end of the disk wipe process a success dialog displays. Close closes the dialog and returns you to the Disks screen.
The Edit Disk screen allows users to configure and manage general disk, power management, temperature alert, S.M.A.R.T., and SED settings for system disks not assigned to a pool.
Click Edit Disk on the Devices screen to open the the Edit Disk screen.
Setting | Description |
---|---|
Name | Displays the current name of the disk. To change, enter a Linux disk device name. |
Serial | Displays the serial number for the selected disk. To change, enter the disk serial number. |
Description | Enter notes about this disk. |
Setting | Description |
---|---|
HDD Standby | Select a value from the dropdown list of options or leave it set to the default Always On. This specifies the minutes of inactivity before the drive enters standby mode. This forum post describes identifying spun-down drives. Temperature monitoring is disabled for standby disks. |
Advanced Power Management | Select a power management profile from the dropdown list of options that include Disabled (the default setting), Level 1 - Minimum power usage with Standby (spindown), Level 64 - Intermediate power usage with Standby, Level 127 - Maximum power usage with Standby, Level 128 - Minimum power usage without Standby (no spindown), Level 192 - Intermediate power usage without Standby, or Level 254 - Maximum performance, maximum power usage. |
Setting | Description |
---|---|
Critical | Enter a threshold temperature in Celsius. If the drive temperature is higher than this value, it creates a LOG_CRIT level log entry and sends an email to the address entered in the Alerts. Enter 0 to disable this check. |
Difference | Enter a value in degrees Celsius that triggers a report if the temperature of a drive changes by this value since the last report. Enter 0 to disable this check. |
Informational | Enter a value in degrees Celsius that triggers a report if the drive temperature is at or above this temperature. Enter 0 to disable this check. |
Setting | Description |
---|---|
Enable S.M.A.R.T. | Select to enable the system to conduct periodic S.M.A.R.T. tests. |
S.M.A.R.T. extra options | Enter additional smartctl(8) options. |
SED Password | Enter a password to set or change the password of the SED for this disk and to use instead of the global SED password. |
Clear SED Password | Select to clear the SED password for this disk. |
The Pool Creation Wizard configuration screens include a configuration preview and an inventory list of disks available on the system.
Create Pool at the top right of the Storage Dashboard screen opens the Pool Creation Wizard.
Configuration Preview displays a list of pool and VDEV settings that dynamically update as you configure settings in the wizard.
Inventory displays the number of available disks by size on the system, and this list dynamically updates as disks move to VDEVs added in the wizard.
The Pool Creation Wizard has seven configuration screens, numbered in sequence, to create a pool with VDEVs.
Each wizard VDEV configuration screen includes the Automated Disk Selection and Advanced Options areas. Click Manual Disk Selection to open the Manual Selection screen.
Back and Next move to either the previous or next wizard screen. Reset Step clears the VDEV settings for the VDEV type selected. For example, Data VDEV configuration. Save And Go To Review saves the current selections and goes directly to the Review wizard screen.
The General Info area includes two default settings, Name and Encryption.
Name is a required field. Enter a pool name of up to 50 characters in length that follows ZFS naming conventions. Use lower-case alpha characters to avoid potential problems with sharing protocols. Names can include numbers and special characters such as underscore (_), hyphen (-), colon (:), or a period (.).
Encryption applies key-type encryption to the pool. Select to enable ZFS encryption for the pool and all datasets (or zvols) created within the pool. See Storage Encryption for more information on using SCALE storage encryption. An encryption warning dialog displays with a Confirm checkbox. Select to enable the I Understand button. I Understand allows you to continue adding the pool with encryption applied.
Applying encryption at the pool level also encrypts all datasets (and zvols) within the pool.
Keep the encryption key file in a safe location where you perform regular backups. Losing the encryption key file results in lost data you cannot recover.
If system disks contain data exported from pools, a warning displays with a checkbox for the pool name.
If system disks have non-unique serial numbers, a warning displays with additional fields.
Allow non-unique serialed disks has two radio buttons, Allow and Don’t Allow.
Allow permits using disks with non-unique serial numbers, such as those that can occur on virtual disks, and displays them as available disks on the Data wizard screen. Don’t Allow does not permit using disks with non-unique serial numbers.
The Data wizard screen includes the option to automatically or manually add disks to a data VDEV. You must add a data VDEV before you can add other types of VDEVs to the pool.
Use the Log wizard screen to configure a log VDEV. ZFS log devices can improve the speeds of synchronous writes.
Use the Spare wizard screen to configure a hot spare for a drive in a data VDEV.
Use the Cache wizard screen to configure a ZFS L2ARC read-cache VDEV.
Use the Metadata wizard screen to configure a special allocation class VDEV. Metadata VDEVS are used when creating a fusion pool. This VDEV type is used to speed up metadata and small block IO.
Use the Dedup wizard screen to configure a VDEV. A Dedup VDEV is used to store de-duplication tables. Size dedup VDEVs as x GiB for each x TiB of general storage.
The Manual Selection screen allows adding a Stripe or the Data VDEV Layout, then selecting individual disks to add to the new VDEV. You can filter disks by type or size.
Add places a VDEV area to populate with individual disks.
The screen shows disk icons for available disks, or click on the system field to expand the dropdown list to show a list of available system disks. You can use the disk filters separately or together to find disks of the same type and size. Drag disks to the VDEV to add them.
Save Selection creates the VDEV and closes the window.
Setting | Description |
---|---|
Search | Enter the disk name or other details to search for disks matching the specified value to filter available disks in the system. |
Filter by Disk Type | Resets the available disks list to show only the selected type (HDD or SSD). |
Filter by Disk Size | Resets the available disks list to show only disks matching the selected size. |
TrueNAS System | Click to expand and show the list of available disks in the system. Filter options change disks displayed on this list. |
The Review wizard screen displays a summary of the pool VDEV configuration.
Inspect VDEVs opens the Inspect VDEVs screen that shows the VDEVs with assigned disks added to the pool.
Start Over clears the current pool configuration so you can start over.
Create Pool completes the configuration process and adds the pool.
The Devices screen lists VDEVS and disks configured for the selected pool. Go to Storage and click on Manage Devices on the Topology widget to view the Devices screen.
Click anywhere on the VDEV to see the drives included in it, and the ZFS Info widget for that VDEV.
Click anywhere on a drive to see the drive widgets.
Add VDEV opens the Add a VDEVs to Pool screen with the Pool Creation Wizard for the selected pool. For example, find the Topology widget for a pool and click Manage Devices. This opens the Pool Creation Wizard with tank prepopulated but not editable.
The ZFS Info widget for the VDEV shows a count of read, write, and checksum errors for that VDEV, and the Extend and Remove options.
Extend opens the Extend VDEV dialog where you select a disk from the New Disk dropdown to add a new disk to the VDEV.
Remove opens the Remove device dialog where you confirm you want to remove the selected VDEV. To remove a drive from the VDEV, select the drive then select Detach on the ZFS Info widget to remove the drive from the VDEV (pool).
Each disk in a VDEV has a set of four widgets that show information for that disk. After selecting a disk, the widgets display on the right side of the screen in the Details for diskname area of the screen.
The ZFS Info widget for each device (disk drive) in the VDEV shows the name of the VDEV (Parent) the read, write, and checksum errors for that drive, and the Detach and Offline options.
Detach opens a confirmation dialog and removes the selected drive from the parent VDEV.
Offline opens a confirmation dialog and takes the selected drive to an offline state. After taking a drive offline you can remove or replace the physical drive.
The Hardware Disk Encryption widget shows information on the drive SED password status (set, not set).
The Manage SED Password link opens a Manage SED Password dialog where you enter an SED password for the drive to set the disk encryption password.
Global SED Password shows the status as set or not set. The Manage Global SED Password link opens the System Settings > Advanced screen where you can change the global SED password that overrides the disk passwords.
The **S.M.A.R.T. Info for devicename widget, where devicename is the name of the disk, provides the number of Completed S.M.A.R.T. Tests and the number of S.M.A.R.T. Tests configured on the system.
The Disk Info widget shows the Disk Size, Transfer Mode, the Serial and Model numbers for the drive, the Type of drive it is, the HDD Standby setting, and any Description associated with the selected drive.
Replace opens the Replacing disk diskname dialog, where diskname is the name of the selected disk.
Select the new disk for the pool from the Member Disk dropdown list. The system prevents losing existing data by stopping the add operation for the new disk if the disk is already in use or has partitions present.
Force overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
Replace Disk adds the new disk to the pool.
The Datasets screen and widgets display information about datasets, provide access to data management functions, indicate the dataset roles, list the services using the dataset, and show the encryption status and the permissions the dataset has in place. The screen focuses on managing data storage including user and group quotas, snapshots, and other data protection measures.
The Datasets screen displays No Datasets with a Create Pool button in the center of the screen until you add a pool and the first root dataset.
The screen has two main sections, the dataset tree table on the left and the Details for datasetname on the right. After creating a dataset, the tree table that lists parent and child datasets (or zvols) on the system. The Details for datasetname area displays a set of dataset widgets.
Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits. For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Add Zvol opens the Add Zvol screen.
Add Dataset opens the Add Dataset screen.
Begin typing the name of a dataset in the Search field to filter datasets to a short list of those matching what is typed.
The datasets tree table lists datasets in an expandable hierarchical structure with the root dataset first, then each child or non-root parent dataset, and the child datasets of each nested under them.
Click on any parent dataset to expand the tree table and show nested child datasets. Select a dataset to display the dataset widgets for that dataset.
The table includes used and available storage space for that dataset, encryption status (locked, unlocked, or unencrypted), the role of that dataset, and what service uses it (i.e., the system dataset, a share, virtual machine, or application).
Each dataset has a set of information cards (widgets) that display in the Details for datasetname area of the screen. These widgets provide information grouped by functional areas. The set of widgets for a root or parent dataset differs from child datasets or datasets used by another service or with encryption.
Dataset widgets are:
The Dataset Details widget lists information on dataset type, sync type, compression level, case sensitivity, Atime, and ZFS deduplication settings. Path displays the full path for the selected dataset.
A root dataset path displays the pool name alone.
The Delete window for a parent dataset (non-root) includes information about snapshots, shares or other services such as Kubernetes or VMs that use the dataset. If a parent to other datasets, the window includes the services a child dataset uses.
The Dataset Space Management widget displays space allocation (reserved, used, available) for all datasets. The widget displays if an encrypted dataset is unlocked. After locking the dataset this widget disappears until you unlock the dataset.
The Data Protection widget displays for all datasets. It shows the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system.
The Permissions widget displays for all datasets. It shows the type of ACL as either NFSv4 or Unix Permissions (POSIX), and lists access control user or group entries and the owner and group for the dataset.
The Roles widget displays the dataset role or the service that uses it (i.e., a share, application, virtual machine, or the system dataset). A parent dataset displays information on child datasets that a service uses. If the dataset is also the system dataset, the widget includes a link to the System Settings > Advanced screen where you can manage the system dataset.
The ZFS Encryption widget displays for datasets configured with encryption. The options in the widget vary based on the type of dataset (root, non-root parent, or child dataset). It includes the current state of the dataset encryption, the encryption root, the type, and the algorithm used.
The Add Dataset and Edit Dataset screens allow admin users with the right permission level to create and or modify datasets. Both screens include the same settings but you cannot change the dataset name, Dataset Preset selection, or on the Advanced Options screen, change the Case Sensitivity settings after you click Save on the Add Dataset screen.
After adding a dataset, click Edit on the Dataset Details widget to open the Edit Dataset screen. To edit encryption options, click Edit on the ZFS Encryption widget. To edit dataset permissions, click Edit on the Permissions widget.
Add Dataset and Edit Dataset screens include the Basic Options and Advanced Options. TheBasic Options and Advanced Options screens include the Name and Options section.
Advanced Options screen settings include:
Basic Options and Advanced Options screens both show the Name and Options settings. The common settings are Parent Path, Name, and the Dataset Preset (previously known as the share type).
Shows only on the Advanced Options screen. The This Dataset and This Dataset and Child Datasets sections include the same setting options. This Dataset applies the quota settings to the for the dataset you are creating or editing. This Dataset and Child Datasets applies to any children of the dataset. These settings also display on the Capacity Settings screen.
Setting a quota defines the maximum allowed space for the dataset or the dataset and child datasets. You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space. You can configure quotas for only the new dataset or include all child datasets.
Encryption setting options display on the Advanced Options of the Add Dataset screen but not on the Edit Dataset screen. To edit encryption settings, click Edit on the ZFS Encryption widget. This opens the Edit Encryption Options for datasetName window where you can change encryption settings for an existing dataset.
If you create an unencrypted dataset, the default setting is Inherit (Non-Encrypted), and you can create encrypted or unencrypted child datasets under it. If you create an encrypted dataset, the default setting is Inherit (Encryption), and all child datasets created under it are encrypted. The default Inherit option is pre-selected.
Clear the Encryption option (pre-selected) checkbox to show the key type encryption settings. Select Passphrase in Encryption Type to show other settings.
The Other Options tune the dataset for specific data-sharing protocols by setting compression level and sync type options, ACL type and mode, and other settings.
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.
The zvol screens and widgets, accessed from the Datasets screen, allow you to add or edit a zvol and manage the volume storage. Zvols are listed on the Datasets screen tree table.
The tree table includes storage space used and available for that zvol (or dataset), encryption status (locked, unlocked, or unencrypted), and the role of that zvol or dataset or what service uses it (i.e., the system dataset, a share, virtual machine, or application).
Add Zvol displays after you select a root, non-root parent, or child dataset. It does not display if you select an existing zvol.
Click on any root or non-root parent dataset to expand the tree table.
Click on any zvol to select it and display the widgets for that zvol.
Each zvol has a set of information cards (widgets) that display in the Details for zvolname area of the screen and provide information grouped by functional areas. Add Zvol opens the Add Zvol screen. Dataset widgets are:
The Zvol Details widget lists information on volume type, and the sync, compression level, case sensitivity, Atime, and ZFS deduplication settings. The Zvol Details widget shows information on volume type, and the sync, compression level, case sensitivity, Atime, and ZFS deduplication settings. Path displays the full path for the selected zvol.
Edit opens the Edit Zvol screen for the selected zvol.
Delete opens the Delete zvol dialog.
The Delete Zvol dialog shows information about other options or services that use the zvol. It also shows the services child datasets use. This includes information about snapshots, shares, or if used, other services such as Kubernetes or VMs that use the dataset. Parent and child datasets include the Delete button.
The window includes a field where you type the path for the zvol, and a Confirm option you must select to activate the Delete Dataset button.
The Zvol Space Management widget displays space allocation (reserved, used, available) for the zvol.
The widget displays after unlocking encrypted zvols.
The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected zvol.
This includes data written and space allocated to child datasets of this dataset.
It provides access to quota configuration options for the parent dataset and the child dataset of the parent, and for users and groups with access to the dataset.
Edit opens the Capacity Settings screen where you can set quotas for the zvol.
The widget displays quotas set for users or groups.
The ZFS Encryption widget displays for zvols configured with encryption. It shows the current state of the encryption, the encryption root, the type, and the algorithm used. The ZFS Encryption widget displays the Lock or Unlock options if it uses key encryption instead of a passphrase. The Export Key option displays if the zvol uses key encryption.
Edit opens the Edit Encryption Options for dataset window for the selected zvol.
For more details on encryption windows and functions see Encryption Settings.
The Data Protection widget displays for all datasets or zvols. It shows information for the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system. It provides access to the tasks found on the Data Protection screen through links.
Create Snapshot opens the Add Snapshot screen.
Manage Snapshots opens the Snapshots screen list view where you can manage snapshots.
Manage Snapshot Tasks opens the Data Protection > Periodic Snapshot Tasks screen list view where you can manage scheduled periodic snapshot tasks.
Manage Replication Tasks opens the Data Protection > Replications Tasks screen list view where you can manage scheduled replication tasks.
Manage Cloud Sync Tasks opens the Data Protection > Cloud Sync Tasks screen list view where you can manage scheduled cloud sync tasks.
Manage Rsync Tasks opens the Data Protection > Rsync Tasks screen list view where you can manage scheduled rsync tasks.
The Add Zvol and Edit Zvol screens allow admin users with the right permission level to create and modify zvols. Both screens include the same settings but you cannot change the zvol name, Block Size, or select the Sparse option after you click Save on the Add Zvol screen.
After adding a zvol, click Edit on the Zvol Details widget to open the Edit Zvol screen. To edit encryption options, click Edit on the ZFS Encryption widget.
Encryption options do not display unless you create the zvol and encrypted dataset.
Depending on their workload, zvols can require additional tuning for optimal performance. See the OpenZFS handbook workload tuning chapter for more information.
Select the compression algorithm that best suits your needs from the Compression dropdown list of options.
LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.
ZSTD offers highly configurable compression speeds, with a very fast decoder.
Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.
ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.
LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.
Encryption Options only display on the Add Zvol screen. To change encryption settings, use the Edit button on the ZFS Encryption widget.
The default setting is Inherit. Clearing the checkbox displays the key encryption options. Clear the Inherit(non-encrypted) checkbox to display additional settings.
The Capacity Settings screen allows users to set quotas for the selected dataset and for the selected dataset and any of the child datasets for the selected dataset apart from the dataset creation process.
The settings on the Capacity Settings screen are the same as those in the quota management section on the Add Dataset > Advanced Options screen.
Setting | Description |
---|---|
Quota for this dataset Quota for this dataset and all children | Enter a value to define the maximum allowed space for the dataset. 0 disables quotas. |
Quota warning alert at, % | Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value. |
Quota critical alert at, % | Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value. |
Reserved space for this dataset Reserved space for this dataset and all children | Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited. |
The Snapshots screen lists dataset snapshots on the system. It allows you to add new or manage existing snapshots.
Access to the Snapshots screen is available using the Manage Snapshots link on the Data Protection widget on the Datasets screen and by clicking Snapshots on the Periodic Snapshot Tasks widget on the Data Protection screen.
If the selected dataset does not have snapshots, the screen displays No Snapshots are Available.
Enter a dataset path in the search field at the top of the screen to check for snapshots for other datasets.
Add opens the Add Snapshot screen.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Click anywhere on a snapshot to expand it and view more information about the snapshot and the options for that snapshot.
Select the checkbox to the left of each snapshot to select multiple snapshots and display the Batch Operations option to Delete the selected snapshots.
Option | Description |
---|---|
Delete | Opens a Delete confirmation dialog for the selected snapshot(s). Select Confirm to activate the Delete button. |
Clone to New Dataset | Opens the Clone to New Dataset) window where you enter a new name or clone with the default value in the Dataset Name field. |
Rollback | Opens the Dataset Rollback From Snapshot window with three radio button options. Confirm activates the Rollback button. |
Hold | Select to prevent the snapshot from being deleted. If selected and you batch-operation delete datasets, this opens an error display with the name of the dataset and prevents the delete operation from continuing. |
The snapshot Rollback option replaces the data in the selected dataset with the information saved in the snapshot.
There are three Stop Rollback if Snapshot Exists radio button options that impose safety levels on the rollback operation. When the safety check finds additional snapshots directly related to the dataset you are rolling back it cancels the rollback.WARNING: Rolling the dataset back destroys data on the dataset and can destroy additional snapshots that are related to the dataset. This can result in permanent data loss! Do not roll back until all desired data and snapshots are backed up.
Use the Clone to New Dataset button to create a clone of the snapshot. The clone appears directly beneath the parent dataset in the dataset tree table on the Datasets screen. Click Clone to New Dataset to open a clone confirmation dialog.
Click Clone to confirm.
The Go to Datasets button opens the Datasets screen.
Click on the clone name in the dataset listing to populate the Dataset Details widget and display the Promote button.
After clicking the Promote button, the dataset clone is promoted and this button no longer appears.
Promote now displays on the Dataset Details widget when you select the demoted parent dataset.
See zfs-promote.8 for more information.
The snapshot Delete option opens a window that lists the snapshot(s) you select.
Confirm activates the Delete button.
To delete more than one snapshot in one operation, select the checkbox beside the datasets you want to delete to display the Batch Operations Delete option.
Batch Operations Delete opens a window listing all selected snapshots.
Confirm activates the Delete button. If a snapshot has the Hold option selected, an error displays to prevent you from deleting that snapshot.
The Add Snapshots screen allows you to create a snapshot while on the Snapshots screen. It also opens when you click Create Snapshot on the Dataset Protection widget on the Datasets screen.
Save retains the settings and returns to the Snapshots screen.
TrueNAS allows setting data or object quotas for user accounts and groups cached on, or connected to the system.
Select Manage User Quotas on the Dataset Space Management widget to open the User Quotas screen. The User Quotas screen displays names and quota data of user accounts cached on or connected to the system. If no users exist, the screen displays No User Quotas in the center of the screen.
The Show All Users toggle button displays all users or hides built-in users.
{< trueimage src="/images/SCALE/Datasets/UserQuotasDataQuotaSCALE.png" alt=“User Quotas List View” id=“User Quotas List View” >}}
Add opens the Set User Quotas screen.
If you have several user quotas set up, the Actions options include Set Quotas (Bulk).
Click on a user name to display the Edit User window.
The Edit User Quota window allows you to modify the user data quota and user object quota values for an individual user.
Click Save to save changes or click the “X” to close the window without saving.
Settings | Description |
---|---|
User | Displays the name of the selected user. |
User Data Quota (Examples: 500KiB, 500M, 2 TB) | Enter the amount of disk space the selected user can use. Entering 0 allows the user to use all disk space. You can enter human-readable values such as 50 GiB, 500M, 2 TB, etc. If units are not specified, the value defaults to bytes. |
User Object Quota | Enter the number of objects the selected user can own. Entering 0 allows unlimited objects. |
To display the Set User Quotas screen click the Add button.
Click Manage Group Quotas on the Dataset Space Management widget to open the Group Quotas screen.
The Group Quotas screen displays the names and quota data of any groups cached on or connected to the system. If no groups exist, the screen displays No Group Quotas in the center of the screen.
The Show All Groups toggle button displays all groups or hides built-in groups. Add displays the Set Group Quotas screen.
If you have several group quotas set up, the Actions options include Set Quotas (Bulk).
Click on a group name to display the Edit Group window.
!
The Edit Group window allows you to modify the group data quota and group object quota values for an individual group.
Click Save to set the quotas or click the “X” to exit without saving.
To display the Set Group Quotas screen, click the Add button.
Datasets, root, non-root parent, and child, or zvols with encryption include the ZFS Encryption widget in the set of dataset widgets displayed on the Datasets screen.
The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.
Icon | State | Description |
---|---|---|
Locked | Displays for locked encrypted root, non-root parent and child datasets. | |
Unlocked | Displays for unlocked encrypted root, non-root parent and child datasets. | |
Locked by ancestor | Displays for locked datasets that inherit encryption properties from the parent. | |
Unlocked by ancestor | Displays for unlocked datasets that inherit encryption properties from the parent. |
The Encryption option on the Pool Manager screen sets encryption for the pool and root dataset. The Download Encryption Key warning window displays when you create the pool. It downloads a JSON file to your downloads folder.
The ZFS Encryption widget for root datasets with encryption includes the Export All Keys and Export Key options. It does not include the Lock option.
If a dataset is encrypted using a key, the ZFS Encryption widget for that dataset includes the Export Key option.
Export All Keys opens a confirmation dialog with the Download Keys option that exports a JSON file of all encryption keys to the system download folder.
Export Key opens a dialog with the key for the selected dataset and the Download Key option that exports a JSON file with the encryption key to your system download folder.
Encryption type and options are set for a dataset when it is first created and are inherited from the root dataset. The Edit Encryption Options for datasetname displays the current encryption option settings for the selected encrypted dataset. Use to change the encryption type from or to key or passphrase, and the related settings.
The Edit Encryption Options for datasetname window opens with the current dataset encryption settings displayed. The encryption settings options are the same as those on Add Dataset > Encryption Options.
Lock displays on encrypted non-root parent or child datasets ZFS Encryption widgets. An encrypted child that inherits encryption from a non-root parent does not see the Lock option on its ZFS Encryption widget because the lock state is controlled by the parent dataset for that child dataset. The locked icon for child datasets that inherit encryption is the locked by ancestor icon.
Lock opens the Lock Dataset confirmation dialog with the option to Force unmount and Lock the dataset. Force unmount disconnects any client system accessing the dataset via sharing protocol. Do not select this option unless you are certain the dataset is not used or accessed by a share, application, or other system services.
After locking a dataset, the ZFS Encryption screen displays Locked as the Current State and adds the Unlock option.
Unlock on the ZFS Encryption widget displays for locked datasets that are not child datasets that inherit encryption from the parent dataset. Unlock opens the Unlock Datasets screen, which allows you to unlock the selected dataset and child datasets simultaneously.
If you select a child dataset of the root dataset or a non-root parent, the screen includes only the one Dataset Passphrase field, and the option to Unlock Child Encrypted Roots pre-selected.
TrueNAS SCALE offers two Access Control List (ACL) types: POSIX (the SCALE default) and NFSv4. For a more in-depth explanation of ACLs and configurations in TrueNAS SCALE, see our ACL Primer.
The Dataset Preset option on the Add Dataset screen sets the ACL type applied for SMB shares, apps, multi-protocol shares, and general-use datasets.
The ACL Type setting in the Advanced Options on both the Add Dataset and Edit Dataset screens, determines the ACL presets available on the ACL Select a preset ACL window. It also determines which permissions editor screens you see after you click the
edit icon on the Dataset Permissions widget.Set ACL Type to NSFv4 to activate and select which ACL Mode the dataset uses.
If you set Dataset Preset to Generic, or selected POSIX or Inherit as the ACL Type settings on the Add Dataset > Advanced Options screen, the first screen you see after clicking Edit on the Permissions widget is the Dataset > Edit Permissions screen Unix Permissions Editor.
Use the settings on this screen to configure basic ACL permissions.
The Access section lets users define the basic Read, Write, and Execute permissions for the User, Group, and Other accounts that might access this dataset.
A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets. Removing this permission results in lost access to the path.
The Advanced section lets users Apply Permissions Recursively to all directories, files, and child datasets within the current dataset.
To access advanced POSIX ACL settings, click Add ACL on the Unix Permissions Editor. The Select a preset ACL window displays with two radio buttons.
There are two different Select a preset ACL windows, one for the POSIX ACL and the other for the NFSv4 ACL. Selecting a preset replaces the ACL currently displayed on the Edit ACL screen and deletes any unsaved changes.
For a POSIX ACL, a window with three setting options displays before you see the Edit ACL screen. These setting options allow you to select and use a pre-configured set of permissions that match general permissions situations or to create a custom set of permissions. You can add to a pre-configured ACL preset on the Edit ACL screen.
For an NFSv4 ACL, click Use Preset ACL on the Edit ACL screen to access the NFS4 Select a Preset ACL window.
The ACL Type setting determines the pre-configured options presented on the Default ACL Options dropdown list on each of these windows. For POSIX, the options are POSIX_OPEN, POSIX_RESTRICTED, or POSIX_HOME. For NFSv4, the options are NFS4_OPEN, NFS4_RESTRICTED, NFS4_HOME, and NFS4_DOMAIN_HOME.
Setting | Description |
---|---|
Select a preset ACL | Click to populate the Default ACL Options dropdown list with pre-configured POSIX permissions. |
Create a custom ACL | Click to open the Edit ACL screen with no default permissions, users, or groups or to configure your own set of permissions. Click Continue to display the Edit ACL screen. |
The Edit ACL screen options are based on ACL type (POSIX or NFSv4). The Dataset Preset and ACL Type settings determine the ACL type. They are under Advanced Options in the Add Dataset and Edit Dataset screens
The section below describes the differences between screens for each ACL type.
Select any user account or group manually entered or imported from a directory service in the Owner or Owner Group. The value entered or selected in each field displays in the Access Control List below these fields.
Dataset displays the dataset path (name) you selected to edit.
The Access Control List section displays the items and a permissions summary for the owner@, group@, and everyone@ for both POSIX and NSFv4 ACL types. The list of items changes based on a selected pre-configured set of permissions.
To add a new item to the ACL, click Add Item, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.
These functions display on the Edit ACL screen for both POSIX and NSFv4 ACL types except for Strip ACL, which only displays for NSFv4 types.
The POSIX Access Control Entry settings include Who, Permissions, and Flags options.
There are two Access Control Entry settings, Who and ACL Type.
The NFSv4 ACL Type radio buttons change the Permissions and Flags setting options. Select Allow to grant the specified permissions or Deny to restrict the permissions for the user or group in Who.
TrueNAS divides permissions and inheritance flags into basic and advanced options. The basic permissions options are commonly-used groups of advanced options. Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.
Click the Basic radio button to display the Permissions dropdown list of options that applies to the user or group in Who.
Click the Advanced radio button to display the Permissions options for the user or group in Who.
Click the Basic radio button to display the flag settings that enable or disable ACE inheritance.
Click the Advanced radio button to display the flag settings that enable or disable ACE inheritance and offer finer control for applying an ACE to new files or directories.
File sharing is one of the primary benefits of a NAS. TrueNAS helps foster collaboration between users through network shares.
TrueNAS SCALE allows users to create and configure Windows SMB shares, Unix (NFS) shares, and block (iSCSI) shares targets.
Click Shares on the main navigation panel to display the Sharing screen, which displays options to access SMB, NFS, and iSCSI shares.
If you have not added SMB shares to the system, the SMB widget shows No records have been added yet.
Add at the top right of the widget opens the Add SMB screen where you configure SMB shares. After adding an SMB share it displays on the widget.
Click on Windows (SMB) Shares Sharing > SMB screen.
to open theEach SMB share includes a toggle that provides quick access to enable or disable the share, and four icons for different individual share functions:
The Windows (SMB) Shares
toolbar displays the status of the SMB service as either STOPPED (red) or RUNNING (blue). Before adding the first share, the STOPPED status displays in the default color.Click on the widget header to open the Sharing > SMB details screen.
Add opens the Add SMB share configuration screen.
The
icon displays four options available to SMB shares in general:The
trash can icon displays the Delete dialog.Select Confirm to activate the Delete button.
The Sharing >SMB details screen, lists all SMB shares added to the system.
Add opens the Add SMB configuration screen.
Columns displays a set of options to customize the list view. Options include Unselect All, Path, Description, Enabled and Reset to Defaults.
Enabled indicates whether the share is enabled or disabled. If selected, the share path is available when the SMB service is active. If cleared, the share is disabled but not deleted from the system.
The
displays a dropdown list of options for each share:To return to the Share screen, click Shares on the main navigation panel or Sharing on the breadcrumb at the top of the screen.
The two SMB share configuration screens, Add SMB and Edit SMB, display the same setting options. The Create Dataset option does not show on the Edit SMB screen, but you can change to another existing dataset on the system.
Click Save to create the share (or save an existing one) and add it to the Windows (SMB) Shares widget and Sharing SMB details screen.
The Basic Options settings in this section also display in the Advanced Options.
Setting | Description |
---|---|
Path | Enter the path or use the | icon to the left of /mnt to locate the dataset and populate the path. Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
/mnt | Click the | icon to expand the path at each dataset until you get to the SMB share dataset you want to use. This populates the Path.
Create Dataset | Click to open the Create Dataset dialog. Enter a name to create a new dataset for the share. Click Create to add the dataset and populate the Name field on the Add SMB screen. |
Name | Enter a name for this share that is less than or equal to 80 characters. Because of how the SMB protocol uses the name, the name must not exceed 80 characters. The name cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. If not supplied, the share name becomes the last component of the path. This forms part of the full share path name when SMB clients perform and SMB tree connect. If you change the name, follow the naming conventions for files and directories or share names. |
Purpose | Select a preset option from the dropdown list. The option applies predetermined settings (presets) and disables changing some share setting options. |
Description | Enter a brief description or notes on how you use this share. |
Enabled | Selected by default to enable sharing the path when the SMB service is activated. Clear to disable this SMB share without deleting it. |
This table details the options found on the Purpose dropdown list.
Setting | Description |
---|---|
No presets | Select to retain control over all Advanced Options settings. |
Default share parameters | The default option when you open the Add SMB screen and to use for any basic SMB share. |
Basic time machine share | Select to set up a basic time machine share. |
Multi-User time machine | Select to set up a multi-user time machine share. |
Multi-Protocol (NFSv3/SMB) shares | Select for multi-protocol (NFSv3/SMB) shares. |
Private SMB Datasets and Shares | Select to use private SMB datasets and shares. |
SMB WORM. Files become read-only via SMB after 5 minutes | The SMB WORM preset only impacts writes over the SMB protocol. Before deploying this option in a production environment, the user should determine whether the feature meets their requirements. |
Click Advanced Options to display settings made available or locked based on the option selected in Purpose.
The Access settings customize access to the share and files, and also specifying allow or deny access for host names or IP addresses.
Setting | Description |
---|---|
Enable ACL | Select to enable ACL support for the SMB share. A warning displays if you clear this option and the SMB dataset has an ACL, and you are required to strip the ACL from the dataset prior to creating the SMB share. |
Export Read-Only | Select to prohibit writes to the share. |
Browsable to Network Clients | Select to determine whether this share name is included when browsing shares. Home shares are only visible to the owner regardless of this setting. Enabled by default. |
Allow Guest Access | Select to enable. Privileges are the same as the guest account. Guest access is disabled by default in Windows 10 version 1709 and Windows Server version 1903. Additional client-side configuration is required to provide guest access to these clients. MacOS clients: Attempting to connect as a user that does not exist in FreeNAS does not automatically connect as the guest account. You must specifically select the Connect As: Guest option in macOS to log in as the guest account. See the Apple documentation for more details. |
Access Based Share Enumeration | Select to restrict share visibility to users with read or write access to the share. Open is the default for this setting. See the smb.conf manual page. |
Hosts Allow | Enter a list of allowed host names or IP addresses. Separate entries by pressing Enter. You can find a more detailed description with examples here. |
Hosts Deny | Enter a list of denied host names or IP addresses. Separate entries by pressing Enter. |
The Audit Logging settings enable the auditing function for the SMB share, and allow configuring a watch and ignore list for groups administrators want to monitor.
Setting | Description |
---|---|
Enabled | Select to enable audit logging for the SMB share. |
Watch List | Select groups from the dropdown list that you want to generate audit logging message for. Leaving this blank includes all SMB users with access to the share. If also setting a limit list, when a conflict exists the watch list takes precedence. |
Limit List | Select groups from the dropdown list that you want to ignore or exclude from audit logging. If a group is a member of both the watch and limit lists, the watch list takes precedence and the group generates audit messages. |
The Other Options settings include improving Apple software compatibility, ZFS snapshot features, and other advanced features.
Setting | Description |
---|---|
Use as Home Share | Select to allow the share to host user home directories. Each user has a personal home directory they use when connecting to the share that is not accessible by other users. Home Shares allow for personal, dynamic shares. You can only use one share as the home share. See Adding an SMB Home Share for more information. |
Time Machine | Enables Apple Time Machine backups on this share. This option requires SMB2/3 protocol extension support. You can enable this in the general SMB server configuration. |
Legacy AFP Compatibility | Select to enable the share to behave like the deprecated Apple Filing Protocol (AFP). Leave cleared for the share to behave like a normal SMB share. This option controls how the SMB share reads and writes data. Only enable this when this share originated as an AFP sharing configuration. You do not need legacy compatibility for pure SMB shares or macOS SMB clients. This option requires SMB2/3 protocol extension support. You can enable this in the general SMB server configuration. |
Enable Shadow Copies | Select to export ZFS snapshots as Shadow Copies for Microsoft Volume Shadow Copy Service (VSS) clients. |
Export Recycle Bin | Select to enable. Deleted files are renamed to a per-user subdirectory within the .recycle directory at either the root of the SMB share if the path is the same dataset as the SMB share (default is share and dataset have the same name), or at the root of the current dataset if datasets are nested. Nested datasets do not have automatic deletion based on file size. Do not rely on this function for backups or replacements of ZFS snapshots. |
Use Apple-style Character Encoding | Select to convert NTFS illegal characters in the same manner as macOS SMB clients. By default, Samba uses a hashing algorithm for NTFS illegal characters. |
Enable Alternate Data Streams | Select to allow multiple NTFS data streams. Disabling this option causes macOS to write streams to files on the file system. |
Enable SMB2/3 Durable Handles | Select to allow using open file handles that can withstand short disconnections. Support for POSIX byte-range locks in Samba is also disabled. We do not recommend this option when configuring multi-protocol or local access to files. |
Enable FSRVP | Select to enable support for the File Server Remote VSS Protocol (FSVRP). This protocol allows remote procedure call (RPC) clients to manage snapshots for a specific SMB share. The share path must be a dataset mount point. Snapshots have the prefix fss- followed by a snapshot creation timestamp. A snapshot must have this prefix for an RPC user to delete it. |
Path Suffix | Appends a suffix to the share connection path. Use to provide individualized shares on a per-user, per-computer, or per-IP address basis. Suffixes can contain a macro. See the smb.conf manual page for a list of supported macros. The connect path must be preset before a client connects. |
The Purpose setting you select in the Basic Options affects which Advanced Options settings (presets) you can select. Some presets are available or locked based on your choice. The expandable below provides a comparison table listing these presets and shows whether the option is available or locked.
The Share ACL for sharename screen opens when you click the share Edit Share ACL icon on the Windows (SMB) Shares widget or the Sharing SMB details screen. These settings configure new ACL entries for the selected SMB share and apply them at the entire SMB share level. It is separate from file system permissions.
on theACL Entries are listed as a block of settings. Click Add to add a new entry.
Setting | Description |
---|---|
SID | Shows the SID trustee value (who) this ACL entry (ACE) applies to. SID is a unique value of variable length that identifies the trustee. Shown as a Windows Security Identifier. Click Save and re-open Edit Share ACL to update. |
Who | Select the domain for account (who) this ACL entry applies to. Options are: |
Permission | Select predefined permission combinations from the dropdown list. Options are: |
Type | Select the option from the dropdown list that specifies how TrueNAS applies permissions to the share. Options are: |
Save stores the share ACL and immediately applies it to the share.
The Edit Filesystem ACL option opens the Edit ACL screen for the dataset the share uses. See **Edit ACL Screen more information on the settings found on this screen.
Use the ACL editor screen to set filesystem permissions for the shared dataset. See Permissions for more information on configuring permissions.
You can access the SMB Status screen from the SMB option on the System Settings > Services screen with the list icon and from the
on the Shares > Windows (SMB) Shares widget.The SMB Status screen has four tabs with information related to SMB shares:
Refresh updates the information displayed on the selected tab.
Column displays a dropdown list of options for the selected tab to customize the information included on the screen.
Click Sharing or SBM on the top breadcrumb to open the selected screen. The breadcrumb displays when you access the SMB Status screen from the System Settings > Services SMB row.
The Sharing screen opens after you click Shares on the main navigation panel.
The Unix (NFS) Share
widget includes the widget toolbar that displays the status of the NFS service and the Add button. After adding NFS shares, the widget displays a list of the shares below the toolbar.After adding the first NFS share, the system opens an enable service dialog.
Enable Service turns the NFS service on and changes the toolbar status to Running.
The Enable toggle for each share shows the current status of the share. Disabling the share does not delete the configuration from the system.
The
delete icon displays a delete confirmation dialog that removes the share from the system.Click on Unix (NFS) Share to open the Sharing > NFS screen with the list view of NFS shares.
The NFS share on the widget opens the Edit NFS screen.
Add opens the Add NFS screen.
The
icon displays three options available to NFS shares in general:The toolbar displays the STOPPED service status in red before you start the service or click Enable Service when the dialog displays. When service starts, it displays RUNNING in blue.
The Sharing > NFS details screen displays the same list of NFS shares as the Unix (NFS) Share widget.
Customize the information using the Columns dropdown list. Select from the Unselect All, Description, Enabled, and Reset to Defaults options.
Each share includes these options:
Select Confirm and then UNSHARE to remove the share without affecting the data in the shared dataset.
The Add NFS and Edit NFS display the same Basic Options and Advanced Options settings.
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
The Basic Options settings display by default and also show in the Advanced Options settings.
Setting | Description |
---|---|
Path | Enter the path or use the | icon to the left of /mnt to locate the dataset and populate the path. Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
/mnt | Click the | icon to expand the path at each dataset until you get to the SMB share dataset you want to use. This populates the Path.
Create Dataset | Click to open the Create Dataset dialog. Enter a name to create a new dataset for the share. Click Create to add the dataset and populate the Name field on the Add NFS screen. |
Description | Enter any notes or reminders about the share. |
Enabled | Select to enable this NFS share. Clear the checkbox to disable this NFS share without deleting the configuration. |
Add networks | Click Add to display the Authorized Networks IP address and CIDR fields. Enter an allowed network IP and select the mask CIDR notation. Click Add for each network address and CIDR you want to define as an authorized network. Defining an authorized network restricts access to all other networks. Leave empty to allow all networks. |
Add hosts | Click Add to display the Authorized Hosts and IP addresses field. Enter a host name or IP address to allow that system access to the NFS share. Click Add for each allowed system you want to define. Defining authorized systems restricts access to all other systems. Leave the field empty to allow all systems access to the share. |
Advanced Options settings tune the share access permissions and define authorized networks. Only the Access settings display on the Advanced Options screen.
Setting | Description |
---|---|
Read-Only | Select to prohibit writing to the share. |
Maproot User | Enter a string or select a user from the dropdown to apply permissions for that user to the root user. |
Maproot Group | Enter a string or select a group from the dropdown to apply permissions for that group to the root user. |
Mapall User | Enter a string or select a user to apply permission for the chosen user to all clients. |
Mapall Group | Enter a string or select a group to apply permission for the chosen group to all clients. |
Security | Select a security option from the dropdown list. Options are SYS, KRB5, KRB5I, KRB5P. Selecting KRB5 allows you to use a Kerberos ticket. |
Setting | Description |
---|---|
SYS | Uses locally acquired UIDs and GIDs. No cryptographic security. |
KRB5 | Uses Kerberos for authentication. |
KRB5I | Uses Kerberos for authentication and includes a hash with each transaction to ensure integrity. |
KRB5P | Uses Kerberos for authentication and encrypts all traffic between the client and server. KRB5P is the most secure but also incurs the most load. |
You can access the NFS Sessions screen from the NFS option on the System Settings > Services screen with the list icon and from the
on the Shares > Unix (NFS) Shares widget.The NFS Sessions screen shows current NFS sessions.
Refresh updates the information displayed on the screen.
Column displays a dropdown list of options for the selected tab to customize the information included on the screen.
Click Sharing on the top breadcrumb to open the Shares dashboard.
The Sharing screen opens after you click Shares on the main navigation panel.
The Block (iSCSI) Shares Targets widget displays the widget toolbar with the status of the iSCSI service. Click Configure to open the iSCSI screen on the Target Global Configuration tab. Click Wizard to open the Wizard iSCSI screen.
After adding an iSCSI target or share, the widget toolbar displays the STOPPED service status in red and includes the share below.
Before you add your first iSCSI block share, click anywhere on Block (iSCSI) Shares Targets Add ISCSI Target screen. Click Wizard to open the Wizard iSCSI screen. After adding a block share, the widget displays shares below the toolbar. The No Targets screen opens only when the system does not have an iSCSI target configured on the system.
to open the Sharing > iSCSI screen with the Targets iSCSI configuration tab displayed. Click Add in the top right or Add Target in the middle of the screen to open theThe Target Global Configuration screen.
on the toolbar displays options to turn the iSCSI service on or off. Turn Off Service displays if the service is running. Otherwise, Turn On Service displays. The Config Service option opens the configuration tabsIf you have other share types added to your TrueNAS system, the widget displays as a card on the Sharing screen.
View Details also opens the iSCSI configuration tabs. Each tab includes details on the block shares added to the system.
Setting | Description |
---|---|
Target Name | Required. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn. |
Target Alias | Enter an optional user-friendly name. |
To display the iSCSI Group settings, click Add.
Setting | Description |
---|---|
Portal Group ID | Required if specifying an iSCSI Group. Select the number of the existing portal to use. This is the portal group ID created in Portals. |
Initiator Group ID | Select the existing initiator group ID that has access to the target from the dropdown list of options. When initiator groups exist, the dropdown populates with options to select a created group by ID, allow all groups, or allow no groups. |
Authentication Method | Select the method from the dropdown list of options. None, CHAP or Mutual Chap. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP you must enter or create a new group in Discovery Authentication Group. |
Authentication Group Number | Select the option from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is set to CHAP or Mutual CHAP. Select None or the value representing the number of the existing authorized accesses. |
The iSCSI configuration screens display seven tabs, one for each of the share configuration areas.
The Add button at the top of the Sharing > iSCSI screen works with the currently selected tab or screen. For example, if Portals is the current tab/screen, the Add button opens the Add Portal screen.
The more_vert on configure tab screens with list views display the Edit and Delete options. Edit opens the Edit screen for the selected tab screen. For example, when on the Portals tab/screen, the Sharing > iSCSI > Portals > Edit screen opens.
The Delete option opens the delete dialog for the screen currently selected.
The Add and Edit screens display the same settings.
The Target Global Configuration displays configuration settings that apply to all iSCSI shares. There are no add, edit, or delete options for this screen. It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System Settings > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
Setting | Description |
---|---|
Base Name | Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721. |
ISNS Servers | Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter. |
Pool Available Space Threshold (%) | Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents. |
iSCSI listen port | The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators. |
Asymmetric Logical Unit Access (ALUA) | Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server. |
The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
The more_vert next to the portal displays the Edit and Delete options. Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
Setting | Description |
---|---|
Description | Enter an optional description. Portals are automatically assigned a numeric group. |
Setting | Description |
---|---|
Discovery Authentication Method | Select the discovery method you want to use for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None, you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP, you must enter or create a new group in Discovery Authentication Group. |
Discovery Authentication Group | Select the discovery authentication group you want to use from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is CHAP or Mutual CHAP. Select None or Create New. Create New displays additional setting options. |
Setting | Description |
---|---|
IP Address | Select the IP addresses the portal listens to. Click Add to add IP addresses with a different network port. 0.0.0.0 listens on all IPv4 addresses, and :: listens on all IPv6 addresses. |
Port | TCP port used to access the iSCSI target. The default is 3260. |
Add | Adds another IP address row. |
The Initiators Groups screen display settings to create new authorized access client groups or edit existing ones in the list.
The more_vert next to the initiator group displays the Edit and Delete options. Delete opens the Delete dialog for the selected group ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Sharing > iSCSI > Initiators > Add screen. Edit opens the Sharing > iSCSI > Initiators > Edit screen. Both screens have the same setting options.
Setting | Description |
---|---|
Allow All Initiators | Select to allows all initiators. |
Allowed Initiators (IQN) | Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local. |
Description | Enter any notes about the initiators. |
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Add opens the Add Authorized Access screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Authorized Access screen, and Delete opens a dialog to delete the authorized access for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Group ID | Enter a number. This allows configuring different groups with different authentication profiles. Example: all users with a group ID of 1 inherit the authentication profile associated with Group 1. |
Setting | Description |
---|---|
User | User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name. |
Secret | Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a “password does not match” error until you enter the same password in Secret (Confirm). |
Secret (Confirm) | Enter the same password to confirm the user password. |
Setting | Description |
---|---|
Peer User | Optional. Enter only when configuring mutual CHAP. Usually the same value as User. |
Peer Secret | Enter the mutual secret password. Required if entering a Peer User. Must be a different password than the password in Secret. |
Peer Secret (Confirm) | Enter the same password to confirm the mutual secret password. |
The Targets screen displays settings to create new TrueNAS storage resources or edit existing ones in the list.
Add opens the Add iSCSI Targets screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit iSCSI Targets screen, and Delete opens a dialog to delete the select target. The Add iSCSI Targets and Edit iSCSI Targets screens display the same settings.
The Add iSCSI Target and Edit iSCSI Target screens display the same settings, but the current settings populate the Edit iSCSI Target screen settings for the selected share.
To access the Add iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click Add at the top of the screen. To access the Edit iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click more_vert next to the share and then click Edit.
The Extents screen displays settings to create new shared storage units or edit existing ones in the list.
Add opens the Add Extent screen.
The more_vert next to each entry opens two options, Edit and Delete. Edit opens the Edit Extent screen, and Delete opens a dialog to delete the extents for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Name | Enter a name for the extent. An Extent where the size is not 0, cannot be an existing file within the pool or dataset. |
Description | Enter any notes about this extent. |
Enabled | Select to enable the iSCSI extent. |
Setting | Description |
---|---|
Extent Type | Select the extent (zvol) option from the dropdown list. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. |
Device | Required. Displays if Extent Type is set to Device. Select the unformatted disk, controller, or zvol snapshot. |
Path to the Extent | Displays when Extent Type is set to File. Click the | to browse an existing file. Create a new file by browsing to a dataset and appending /{filename.ext} to the path. Users cannot create extents inside a jail root directory.
Filesize | Only appears if File is selected. Entering 0 uses the actual file size and requires that the file already exists. Otherwise, specify the file size for the new file. |
Logical Block Size | Enter a new value or leave it at the default of 512 unless the initiator requires a different block size. |
Disable Physical Block Size Reporting | Select if the initiator does not support physical block size values over 4K (MS SQL). |
Setting | Description |
---|---|
Enable TPC | Select to allow an initiator to bypass normal access control and access any scannable target. This allows xcopy operations that are otherwise blocked by access control. |
Xen initiator compat mode | Select when using Xen as the iSCSI initiator. |
LUN RPM | Select the option from the dropdown list. Options are UNKNOWN, 5400, 7200, 10000 or 15000. Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. |
Read-only | Select to prevent the initiator from initializing this LUN. |
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Target | Required. Select an existing target. |
LUN ID | Select the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID. |
Extent | Required. Select an existing extent. |
The Data Protection screen allows users to set up multiple redundant tasks that protect and/or backup data in case of drive failure.
Scrub tasks and S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) tests can provide early disk failure alerts by identifying data integrity problems and detecting various indicators of drive reliability.
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.
The Data Protection screen Scrub Task widget displays a list of scrub tasks configured on the system. Scrubs identify data integrity problems, detect silent data corruptions caused by transient hardware issues, and provide early disk failure alerts. TrueNAS generates a default scrub task when you create a new pool and sets it to run every Sunday at 12:00 AM.
Add opens the Add Scrub Task screen.
Each task is a link that opens the Edit Scrub Task Screen.
The
icon opens a delete confirmation dialog.The Add Scrub Task and Edit Scrub Task screens display the same settings that specify the pool, threshold, and schedule for when to run the ZFS scan on the data in a pool.
Setting | Description |
---|---|
Pool | Select the pool to scrub from the dropdown list. |
Threshold days | Enter the number of days before a completed scrub is allowed to run again. This controls the task schedule. For example, scheduling a scrub to run daily and setting Threshold days to 7 means the scrub attempts to run daily. When the scrub succeeds, it continues to check daily but does not run again until the seven days have elapsed. Using a multiple of seven ensures the scrub always occurs on the same weekday. |
Description | Enter a description for this scrub tasks. |
Schedule | Select a preset from the dropdown list that runs the scrub task according to that schedule time. Select Custom to use the advanced scheduler. |
Enabled | Select to enable the scrub task to run. Leave checkbox clear to disable the task without deleting it. |
The settings specify times when new resilver tasks can start, and run, at a higher priority or when a resilver task cannot run at a lower priority.
Setting | Description |
---|---|
Enabled | Select to run resilver tasks between the configured times. |
Begin | Select the hour and minute when a resilver task can start from the dropdown list. The resilver process can run at a higher priority. |
End | Select the hour and minute when new resilver tasks are not allowed to start. This does not affect active resilver tasks. The resilver process must return to running at a lower priority. A resilver process running after this time likely takes much longer to complete due to running at a lower priority compared to other disk and CPU activities, such as replications, SMB transfers, NFS transfers, Rsync transfers, S.M.A.R.T. tests, pool scrubs, user activity, etc. |
Days of the Week | Select the days to run resilver tasks from the dropdown list. |
The Cloud Sync Tasks widget on the Data Protection screen shows configured cloud sync tasks, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS SCALE and a cloud storage provider. Cloud sync tasks are an effective method to back up data to a remote location.
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
The Cloud Sync Task widget shows a list of tasks configured on the system.
The widget shows No Cloud Sync Tasks configured until cloud sync task are added.
Click on the widegt header to open the Cloud Sync Task screen that lists all tasks configured on the system.
Add on the widget and the Cloud Sync Task screen opens the Cloudsync Task Wizard.
Each task includes five icons for various functions:
The Edit Cloud Sync Task screen populated with with the settings for that task.
Edit icon opens theThe play_arrow Run Now icon starts the cloud sync, running it outside of the scheduled time.
The
Dry Run icon performs the same function as the Dry Run button on the add and edit configuration screens. It performs a test of the configured settings. When doing a dry run, you can close the window and monitor the task using the Jobs option on the top toolbar.The
Restore icon creates a new cloud sync task from an existing task. The new task has the same settings but reverses the data transfer.The
Delete icon opens a confirmation dialog before the system deletes the task.State displays the status of the next cloud sync task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet. Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
The Cloud Sync Task screen lists all tasks configured on the system.
Expand any task to see details on the configured task, such as the cloud sync provider, direction, transfer mode, path to the dataset or directories and other options for that task.
Buttons for these task options perform the same functions as the icons on the widget:
Run Now starts the task outside of the scheduled period.
Dry Run performs a test of the configuration. This is the same function as the Dry Run button on the Edit Cloud Sync Task screen and the Advanced Options for the Cloudsync Task Wizard.
Restore opens the Restore Cloud Sync Task window where you can create a new cloud sync task from an existing task with the same options but the new task reverses the transfer from PUSH to PULL and vice-versa.
Edit opens the Edit Cloud Sync Task screen.
Delete opens a dialog where you confirm the action before the system deletes the task.
The Cloud Sync Task wizard screens simplify the task creation process. It includes two screens, Provider and What and When.
The Provider wizard screen allows you to select the cloud sync provider with the Credentials dropdown. Select the provider from the dropdown list to show the additional credential settings that provider requires to establish a connection.
Select Add New to open the Cloud Credentials screen. This is the same configuration screen as when you click Add on the Credentials > Backup Credentials screen.
Advanced Options opens a screen with the same settings as the Edit Cloud Sync Task screen.
Verify Credentials tests the settings before you advance to the settings on the What and When wizard screen.
The What and When screen sets the direction (PUSH or PULL), transfer mode (move, copy, or sync), the datasets or directories source and destination, and sets the schedule for the transfer. The Bucket field displays for providers that use buckets to hold transferred files, folders, etc.
The Advanced Options button shows at the bottom of this screen as well.
The Advanced Options accessed from the Cloudsync Task Wizard and Edit Cloud Sync Task display the same settings. Settings are grouped into the the Transfer, Remote, Control, and Advanced Options for advanced users.
The Manage Credentials link opens the Backup Credentials screen.
Transfer settings change the cloud sync task direction (PUSH or PULL), data transfer method (COPY, MOVE, or SYNC), and allows selecting the dataset or directory to use in the task. Selecting the dataset or file populates the Directory/Files field.
Settings | Description |
---|---|
Description | Enter a description of the cloud sync task. |
Direction | Select a direction option from the dropdown list. PUSH sends data to cloud storage. PULL receives data from cloud storage and is the default setting. |
Transfer Mode | Select the transfer mode type from the dropdown list. To keep all files identical between the two storage locations, select SYNC. This changes files on the destination to match those on the source. If a file does not exist on the source, it is also deleted from the destination. There are three options: |
Directory/Files | Enter or click the | arrow to the left of /mnt folder to expand and show datasets and directories within that folder. When you locate the dataset or directory location to send to the cloud for push syncs, or as the destination to write to for pull syncs. Be cautious with pull destinations to avoid overwriting existing files. Click the arrow to the left of /mnt folder again to collapse the directory tree.
The Remote settings specify the cloud sync provider and destination storage locations. The option selected in Credential changes settings displayed in the Remote settings area. The Manage Credentials link opens the Backup Credentials screen where you can add a new provider credential.
Settings | Description |
---|---|
Credential | Select an exiting backup cloud storage provider credential from the dropdown list. A Bucket setting displays after selecting a credential that uses S3, like Amazon S3. TrueNAS automatically validates the selected credential. |
Bucket | Select the pre-defined bucket S3 to use. |
Folder | Enter or click the | arrow to the left of the folder icon and at each dataset or directory to reach the storage location to use for this task.
Control settings establish a schedule for when the cloud sync task occurs.
Settings | Description |
---|---|
Schedule | Select a schedule preset or choose Custom to open the advanced scheduler. |
Enabled | Select to enable this cloud sync task. Leave clear to disable the task without deleting it and keep the configuration available without allowing the specified schedule to run the task. You can use the toggle in the Enable column on the Cloud Sync Tasks widget to enable or disable the task. |
Advanced Options settings are for advanced users. Selecting Push in Direction adds the Take Snapshot option in Advanced Options.
Settings | Description |
---|---|
Take Snapshot | Displays if Direction is set to Push. Select to take a snapshot before transferring data to the cloud storage provider. |
Create empty source dirs on destination after sync | Select to create an empty source directory in the cloud storage provider folder when pushing data to the cloud provider location, or in TrueNAS if pulling data from the cloud storage provider. |
Follow Symlinks | Select to follow symbolic links (symlinks) and copy the items to which they link. |
Pre-Script | For advanced users. Enter a script to execute before running sync. See the Cloud Sync tutorial for more information. |
Post-Script | For advanced user. Enter a script to execute after running sync. See the Cloud Sync tutorial for more information. |
Exclude | Enter a list of files and directories to exclude from sync. Separate entries by pressing Enter. Examples of proper syntax to exclude files/directories are: photos</code> excludes a file named photos/photos > excludes a file named photos from root directory (but not subdirectories)photos/ excludes a directory named *photos/photos/ excludes a directory named photos from root directory (but not subdirectories).--exclude option. |
The Advanced Remote Options settings are for advanced users to configure remote encryption and transfer bandwidth speed and limit.
Settings | Description |
---|---|
Remote Encryption | Select to use rclone crypt encryption during pull and push transfers. Selecting PUSH in Direction encrypts files before transfer and stores the encrypted files on the remote system. Files are encrypted using the encryption password and encryption salt values. Selecting PULL decrypts files stored on the remote system before the transfer. Transferring the encrypted files requires entering the same encryption password and encryption salt used to encrypt the files. Additional details about the encryption algorithm and key derivation are available in the rclone crypt File formats documentation. |
Filename Encryption | Selected by default. When selected, the pull and push tranfers encrypt or decrypt file names with the rclone Standard file name encryption mode. The original directory structure of the files is preserved. When enabled, file names are encrypted, file names are limited to 143 characters, directory structure is visible, and files with identical names have identical uploaded names. File names can use sub-paths, single copy files, and shortcuts to shorten the directory recursion. When disabled, encryption does not hide file names or directory structure, file names can be 246 characters long, use sub-paths, and copy single files. |
Encryption Password | Enter the password to encrypt and decrypt remote data. Warning: Always securely back up this password! Losing the encryption password results in data loss. |
Encryption Salt | Enter a long string of random characters for use as salt for the encryption password. Warning: Always securely back up the encryption salt value! Losing the salt value results in data loss. |
Transfers | Enter the number of simultaneous file transfers. Enter a number based on the available bandwidth and destination system performance. See rclone –transfers. |
Bandwidth limit | Enter a single bandwidth limit or bandwidth limit schedule in rclone format. Separate entries by pressing <kbdEnter. Example: 08:00,512 12:00,10MB 13:00,512 18:00,30MB 23:00,off. You can specify units with the beginning letter b, k (default), M, or G. See rclone –bwlimit. |
The Rsync Task widget on the Data Protection screen shows configured rsync tasks configured on the TrueNAS system, and provides access to configuration screens to add single-time or scheduled recurring transfers between TrueNAS SCALE and an rsync backup server. Rsync tasks are an effective method to back up data to a remote location.
The Rsync Tasks widget shows a list of tasks configured on the system.
The Rsync Tasks widget shows No Rsync Tasks configured before adding a task.
Click on the widegt header to open the Rsync Task screen that lists all tasks configured on the system.
Add opens the Add Rsync Task screen.
Each task includes three icons for various functions:
The Edit Rsync Task screen populated with with the settings for that task.
Edit icon opens theThe play_arrow Run Now icon starts the rsync, running it outside of the scheduled time.
The
Delete icon opens a confirmation dialog before the system deletes the task.State displays the status of the next cloud sync task as SUCCESS for completed tasks, FAILED if the task fails to complete the sync, and PENDING for tasks that have not run yet. Click on the state oval to open the Logs dialog for that task. Download Logs saves a copy of the current task logs.
The Rsync Task screen lists all tasks configured on the system.
Each task shows details about the configured task and the same icon buttons found on the Rsync Task widget to run the task outside of the scheduled time, edit and/or delete the task.
The Add Rsync Task and Edit Rsync Task display the same settings.
Source settings specify the location of the stored data to sync with a remote server, sets the user that performs the task, and the direction of the task (send or receive data). The Remote settings specify the mode for the task and remote host connection information. Settings change base on the Rsync Mode selected (Module or SSH).
Schedule defines when the remote sync task occurs. The More Options specify other settings related to when and how the rsync occurs.
The Data Protection screen Periodic Snapshot Task widget displays periodic snapshot tasks created on the system. A periodic snapshot task allows scheduling the creation of read only versions of pools and datasets at a given point in time.
The Periodic Snapshot Task widget displays a list of tasks configured on the system.
If a periodic snapshot task is not yet configured No Periodic Snapshot Task configured displays in the widget.
Add opens the Add Periodic Snapshot Task screen.
VMware Snapshot Integration opens the VMware Snapshots screen. Snapshots opens the Snapshots screen.
Each task listed is a link that opens the Edit Periodic Snapshot Task screen populated with with the settings for that task. Click on the Description, Frequency, or Next Run column entry to open the edit task screen.
State displays the status of the next cloud sync task. While on the widget, click on the state for the task to display a Logs window for that task. Click Download Logs to save a copy of the current task logs.
The
Delete icon opens a simple delete dialog where you confirm before the system deletes the saved periodic snapshot task.Periodic snapshot tasks display on both the Data Protection widget and Periodic Snapshot Tasks list screen.
The Add Periodic Snapshot Task and Edit Periodic Snapshot Task display the same settings.
The Dataset setting options display on both the add and edit configuration screens.
These Schedule setting options display on both the add and edit configuration screens.
Use the VMware Snapshot Integration option on the Data Protection > Periodic Snapshot Tasks widget to create snapshots when you are using TrueNAS SCALE as a VMWare datastore. See Creating VMWare Snapshots for a detailed tutorial.
VMware Snapshot Integration opens the VMWare Snapshots screen.
Add opens the Add VMware Snapshot screen.
Setting | Description |
---|---|
Hostname | Enter the IP address or host name of the VMWare host. When clustering, enter the vCenter server for the cluster. |
Username | Enter the user on the VMWare host with permission to snapshot virtual machines. |
Password | Enter the password associated with the user entered in Username. |
Datastore | Select a VMFS datastore to synchronize with the host from the dropdown list of options. Click Fetch DataStores to populate this list with options from the VMWare host. You must click Fetch Datastores before you click in this field or the creation process fails. Selecting a datastore also selects any mapped datasets. |
ZFS Filesystem | Select a TrueNAS ZFS dataset from the dropdown list of options. This field does not populate until you click Fetch Datastores. You must click Fetch Datastores before clicking in this field or the creation process fails. |
Click Fetch DataStores to connect TrueNAS SCALE to the VMWare host. This synchronizes TrueNAS SCALE with the VMWare host and populates the ZFS Filesystem and Datastore dropdown lists with the information from TrueNAS and the VMWare host response.
Configured snapshots show on the VMware Snapshots screen.
The Data Protection screen S.M.A.R.T. Tests widget displays the S.M.A.R.T. tests configured on the system and provides access to create or edit S.M.A.R.T. tests.
The S.M.A.R.T. Tests widget displays No S.M.A.R.T. Tests configured when no tests are configured on the system.
After adding tests, each becomes a link to open the Edit S.M.A.R.T. Tests screen.
Click on S.M.A.R.T. Tests widget header to open the S.M.A.R.T. Tests list screen.
Use Columns to display options to customize the information displayed in the list screen. Options are Unselect All, Description, Frequency, Next Run, and Reset to Defaults.
Add opens the Add S.M.A.R.T. Test configuration screen.
The
for each test has two options, Edit and Delete. Edit opens the Edit S.M.A.R.T. Test configuration screen and Delete opens a Delete confirmation dialog. The delete icon on the widget also opens the Delete dialog for the selected S.M.A.R.T. test. Click Confirm to activate Delete.The Add S.M.A.R.T. Test and Edit S.M.A.R.T. Test configuration screens displays the same settings.
Name | Description |
---|---|
Disks | Select the disks to monitor from the dropdown list. |
All Disks | Select to monitor every disk on the system with S.M.A.R.T. enabled. Leave clear to choose individual disks on the Disks dropdown list to include in the test. |
Type | Select the test type from the dropdown list. Options are LONG, SHORT, CONVEYANCE or OFFLINE. See smartctl(8) for descriptions of each type. Some types degrade performance or take disks offline. |
Description | Enter information about the S.M.A.R.T. test. |
Schedule | Select a preset test schedule from the dropdown list. Select Custom to open the advanced scheduler and define a new schedule for running the test. |
The Replication Task widget on the Data Protection screen lists replication tasks configured on the TrueNAS system. Replication tasks work with periodic snapshot tasks to complete the replication.
The Replication Tasks widget displays No Replication Tasks configured before you add a task.
The Replication Task widget heading is a link that opens the Data Protection > Replications Tasks list view screen.
Add opens the Add Replication Task wizard.
Each replication task is a link to open the Edit Replication Task screen.
The widget displays the status of a task as PENDING, RUNNING, SUCCESS or FAILED. Click on the status to open a Logs window where you can see details on the task and download the log file.
The icon opens a dialog. Run Now
The icon to opens the Restore Replication Task window. Restore
The Download encryption keys icon downloads any encryption keys associated with the task.
The icon opens a delete confirmation dialog. Delete
Configure SSH in TrueNAS before creating a remote replication task. This ensures that new snapshots are regularly available for replication.
The Data Protection > Replications Tasks list view screen displays the replication tasks configured on the system.
Columns displays a list of option to customize the list view to add or remove information to the table. Options are Select All, Direction, Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, Auto, Enabled, State, Last Snapshot, and Reset to Defaults.
If no tasks are configured on the system, this screen displays Not Replication Tasks and the option to Add Replication Tasks that opens the Add Replication Task wizard.
Click anywhere on a task listed to expand the task and show details about that task and options to run, restore, edit or delete that task.
The details view of each replication task shows the Transport, SSH Connection, Source Dataset, Target Dataset, Recursive, and Auto settings.
The Edit Replication Task screen.
Edit button opens theThe
Run Now button opens a Run Now dialog.Click CONTINUE to start the replication task.
The
Restore button opens the Restore Replication Task window.Enter a new name for the task and select the location to store the data, then click Restore. The system creates the new file and displays the task on both the widget and list screen with the PENDING status.
When a replication task involves an key-encrypted source or destination, the icon appears in the task options. This downloads any encryption keys to your local system.
The
Delete icon opens a delete confirmation dialog.Click Confirm to activate Delete.
There are two ways to add a replication task, the wizard and the advanced creation screen. These two methods share many settings that are described below. Some settings shared by the wizard and the advanced creation screen display more related setting options. Shared settings are documented these sections:
Add, or if no replication task exist, Add Replication Tasks open the wizard.
The wizard has two screens.
Advanced Replication Creation on the What and When screen opens the advanced replication creation screen.
The What and When screen options specify a previous replication task, source and destination information and a name for the task.
The Encryption option, used on both the replication task wizard and advanced creation screen, displays more options based on the selection made.
The Source Location and Destination Location selections each display more options based on the selection made.
The SSH Connection option displays for both source and destination if the location setting is On a Different System.
The Also include snapshots with the name options display in both the wizard and advanced creation screen but different replicating snapshots settings related to naming result in them displaying.
Wizard screen settings change based on the option selected in Source Location. Selecting On this system displays the Source field with the option to browse to the dataset location, and the Recursive option. Selecting On a Different System displays the Source and the Recursive options. It changes the Destination Location to On this System. It displays the Encryption option under Destination, adds SSH Connections to the source setting options, adds snapshot naming options, and the SSH Transfer Security options.
Wizard screen settings change based on the option selected in Destination Location and in the Source Location fields. Selecting On this System in Destination Location displays the Destination field with the option to browse to the dataset location and Encryption option under Destination. Selecting On a Different System displays the SSH Connections and SSH Transfer Security options.
These setting options display on the Add Replication Task wizard What and Where screen after selecting the Destination Location, and on the advanced creation Add Replication Task screen in the Destination settings. After selecting Encryption more setting options display.
Setting the source and/or destination location options to On a Different System displays more SSH setting options for whichever location has this setting.
This window allows you to set up a new SSH connection for the remote system.
Also include snapshots with the name radio button options set the snapshot naming pattern as schema or regular expression. This field display on both the wizard and advanced creation screens, but the radio buttons have different names. See Various Snapshot Options below for details. Also include snapshots with the name radio button options display after selecting On a Different System as either the Source Location or Destination Location or after selecting Replicate Custom Snapshots.
The Replication Schedule and Destination Snapshot Lifetime radio button selection changes the setting options displayed.
The Replication Schedule radio button options set the task to run on the schedule defined in Schedule or one time. Each radio button changes options displayed on the screen.
The radio buttons change settings displayed. Select when replicated snapshots are deleted from the destination system. Options are the three radio buttons below. Select Same as Source to use the configured snapshot Lifetime value from the source dataset periodic snapshot task. Select Never Delete to never delete snapshots from the destination system. Select Custom to define how long the snapshot remains on the destination system.
Advanced Replication Creation changes to the advanced Add Replication Task configuration screen. Click before or after adding values to any setting on the What and When wizard screen. Advanced Replication Creation on the What and Where wizard screen opens the Add Replication Task screen with advanced setting options.
Before adding a replication task, create an SSH connection to use when connecting to a remote system. The Add Replication Task wizard provides the option to configure a new SSH connection when adding the task but the advanced creation screen does not.
If adding a local replication task, where you replicate data from one pool and dataset to different pool and dataset on the same system, the SSH connection is not a required element.
The settings in General and Transport Options specify the name of the task, the direction of the data transfer, the transport connection type and method settings for each type. The Transport setting changes options displayed in the Transport Options area (SSH is the default setting). All three Transport field options share the two settings displayed for Local, and the SSH Connection field displays for both the SSH and SSH+NETCAT transport selections.
These setting display for all three Transport options.
These setting options display in addition to the two options displayed when Transport is set to SSH.
These setting options display in addition to the two options displayed when Transport is set to SSH+NETCAT.
The settings in Source specify the location of files you push or pull in the replication task, and the properties applied to the replicated data. The Source setting options change based on selections made in Recursive and Replicate Specific Snapshots and each display additional setting options.
The settings in Destination specify the location of files you push or pull in the replication task, and the properties applied to the replicated data. The destination setting options change based on selections made in Encryption and Snapshot Retention Policy which display additional setting options.
The snapshot settings below change options displayed based on selections made.
These schedule setting options are common to both the Add Replication Task wizard When and the advanced creation Add Replication Task screens.
The Edit Replication Task screen displays most of the settings found on the advanced Add Replication Task screen with a few exceptions.
See the section linked above for information on the Edit Replication Task screen settings.
The SCALE Network screen has network configuration and settings options, in widgets, for active interfaces, static routes, and the global configuration. The Network screen also displays OpenVPN information and IPMI channels. IPMI only displays on systems with physical hardware and not on virtual machine deployments.
Click the buttons or on an existing widget entry to view configuration options on side panels.
The Interfaces widget on the Network screen displays interface port names and IP addresses configured on your TrueNAS system, as well as their upload/download rates.
Use Add to open the Add Interface configuration screen.
Click on an interface to open the Edit Interface configuration screen.
Click the edit icon next to an interface to open the Edit Interface configuration screen.
Click the refresh icon next to a physical interface to reset configuration settings for that interface.
Click the delete icon next to any other interface to delete that interface.
TrueNAS EnterpriseHigh Availability (HA) Enterprise systems are unable to reset or delete interfaces while failover is enabled. On systems with HA failover enabled, the refresh or delete icons are disabled. Disable failover from the System Settings > Failover screen to modify interfaces.
The fields on the Edit Interface are almost identical to the Add Interface configuration screen except for the Type field that only displays on the Add Interface configuration screen. Type is a required field and after selecting the interface type additional configuration fields display for the type selected.
Use Apply to save your setting changes.
These settings display for all interface types. The Type setting is only available and required on the Add Interface configuration screen.
Setting | Description |
---|---|
Type | Required. Select the type of interface from the dropdown list or options Bridge, Link Aggregation or VLAN. Each option displays additional configuration settings for that type. Select Bridge to create a logical link between multiple networks. Select Link Aggregation to combine multiple network connections into a single interface. Select Virtual LAN (VLAN) to partition and isolate a segment of the connection. This field does not display on the Edit Interface screen. |
Name | Required. Enter a name for the interface. Use the format bondX, vlanX, or brX where X is a number representing a non-parent interface. You cannot change the interface name after you click Apply. It becomes a read-only field when editing an interface. |
Description | Enter a description for the interface. |
DHCP | Select to enable DHCP. Leave checkbox clear to create a static IPv4 or IPv6 configuration. Only one interface can be configured using DHCP. |
Autoconfigure IPv6 | Select to automatically configure the IPv6 address with rtsol(8). Only one interface can be configured this way. |
Bridge Settings only display after you select Bridge in for Type.
Setting | Description |
---|---|
Bridge Members | Select the network interfaces to include in the bridge from the dropdown list of options. |
Link aggregation settings only display after you select Link Aggregation as the Type. Additional settings display based on the selection in Link Aggregation Protocol.
Link aggregation settings only display after you select VLAN as the Type.
Setting | Description |
---|---|
Parent Interface | Select the VLAN parent interface from the dropdown list of options. Usually and Ethernet card connected to a switch port configured for the VLAN. New link aggregations are not available until you restart the system. |
VLAN Tag | Required field. Enter the numeric tag configured in the switched network. |
Priority Code Point | Select the Class of Service from the dropdown list of options. The available 802.1p Class of Service ranges from Best effort (default) to Network control (highest). |
Other Settings display for all types of interfaces.
Setting | Description |
---|---|
MTU | Maximum Transmission Unit (MTU), or the largest protocol data unit that can be communicated. The largest workable MTU size varies with network interfaces and equipment. 1500 and 9000 are standard Ethernet MTU sizes. Leaving blank restores the field to the default value of 1500. |
Use the Aliases Add to define an alias for the interface on the TrueNAS controller. The alias can be an IPv4 or IPv6 address.
Users may also select how many bits are a part of the network address from the dropdown list of options.
The Global Configuration widget displays the general TrueNAS networking settings not specific to any interface.
The SCALE information dislplayed the Global Configuration widget is the equivalent of the information displayed on the TrueNAS CORE Network Summary screen. Global Configuration settings configuration screens are similar in both SCALE and CORE but SCALE includes external communication settings.
Use Settings to display the Global Configuration screen where you can add or change global network settings.
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.
Many of these fields have default values, but users can change them to meet local network requirements.
TrueNAS displays the Hostname and Domain in the Dashboard System Information widget.
Some fields only display in the Global Configuration screen when the appropriate hardware is present.
Setting | Description |
---|---|
Hostname | System host name. |
Inherit domain from DHCP | When this checkbox is checked, the domain is inherited from DHCP. |
Hostname (TrueNAS Controller 2) | System host name for a second controller that displays only for High Availability (HA) systems where there is a second TrueNAS controller. Upper and lower case alphanumeric, (.) and (-) characters are allowed. |
Hostname (Virtual) | Virtual host name that displays when using a virtual host; this is also used as the Kerberos principal name. Enter the fully qualified host name plus the domain name. Upper and lower case alphanumeric, (.), and (-) characters are allowed. |
Domain | System domain name, like example.com |
Additional Domains | Additional domains to search. Separate entries by pressing Enter. Adding search domains can cause slow DNS lookups. |
Setting | Description |
---|---|
NetBIOS-NS | Select to use legacy NetBIOS name server. Advertises the SMB service NetBIOS name. Can be required for legacy SMB1 clients to discover the server. When advertised, the server appears in Network Neighborhood. |
mDNS | Select to multicast DNS. Uses the system host name to advertise enabled and running services. For example, this controls if the server appears under Network on MacOS clients. |
WS-Discovery | Select to use the SMB Service NetBIOS name to advertise the server to WS-Discovery clients. This causes the computer to appear in the Network Neighborhood of modern Windows OSes. |
Setting | Description |
---|---|
Nameserver 1 | Primary DNS server. |
Nameserver 2 | Secondary DNS server. |
Nameserver 3 | Third DNS server. |
Setting | Description |
---|---|
IPv4 Default Gateway | Enter an IPv4 address. This overrides the default gateway provided by DHCP. |
IPv6 Default Gateway | Enter an IPv6 address. This overrides the default gateway provided by DHCP. |
Select the radio button for the setting that matches your prefered system services external communicate ability.
Setting | Description |
---|---|
Allow All | Select to allow any system service to communicate externally. |
Deny All | Select to restrict this system so it cannot communicate externally. |
Allow Specific | select to define the system services that are allowed to communicate externally. All other external traffic is restricted. If selected, a dropdown list field displays where you can select the services to enable external communication. |
Setting | Description |
---|---|
HTTP Proxy | When using a proxy, enter the proxy information for the network in the format http://my.proxy.server:3128 or http://user:password@my.proxy.server:3128. |
Enable Netwait Feature | Select to delay the start of network services until pings return from the IP addresses added to the Netwait IP List field that displays only after you select the checkbox. |
Netwait IP List | Displays only after selecting the Enable Netwait Feature checkbox. Enter a list of IP addresses to ping. Separate entries by pressing Enter. Each address is tried until one is successful or the list is exhausted. Leave empty to use the default gateway. |
Host Name Database | Enter additional hosts to append to /etc/hosts. Separate entries by pressing. Separate entries by pressing Enter. Use the format IP_address space hostname where multiple hostnames can be used if separated by a space. Hosts defined here are still accessible by name even when DNS is not available. See hosts for additional information. |
The Static Routes widget on the Network screen displays static IP addresses configured as static routes. Use this to manually enter routes to network destinations outside the TrueNAS network so the router can send packets to a destination network.
TrueNAS does not have defined static routes by default. If you need a static route to reach portions of the network, add the route by going to Network and clicking Add in the Static Routes window.
Setting | Description |
---|---|
Destination | Enter the destination IP address using the format A.B.C.D/E where E is the CIDR mask. This is a required field. |
Gateway | Enter the IP address of the gateway. This is a required field. |
Description | Enter notes or an identifier describing the route. |
Use Save to add the static route.
The IPMI widget on the Network screen shows the available IPMI channels.
Click to open the IPMI manager in a new browser tab where users can log into the IPMI web interface.
Click edit to go to the IPMI configuration screen.
Click Show Events to show the IPMI Events log.
IPMI requires compatible hardware! Refer to your hardware documentation to determine if the TrueNAS web interface has IPMI options.
Click edit on the channel you wish to edit to open the configuration screen.
Setting | Description |
---|---|
DHCP | Select to use DHCP to assign IPv4 network values. Clear the checkbox to manually configure a static IPv4 connection. |
IPv4 Address | Enter the IPMI web interface static IPv4 address. |
IPv4 Netmask | Enter the IPv4 address subnet mask. |
IPv4 Default Gateway | Enter the IPv4 connection default gateway. |
VLAN ID | Enter the VLAN identifier if the IPMI out-of-band management interface is not on the same VLAN as management networking. |
Password | Enter an 8-16 character password for connecting to the IPMI interface from a web browser. The password must include at least one upper case letter, one lower case letter, one digit, and one special character (punctuation, e.g. ! # $ %, etc.). |
Save | Save the configuration. |
Manage | Opens the IPMI manager in a new browser tab where users can communicate with the server without having direct access to the hardware. |
Flash Identify Light | Flashes the system IPMI light on the compatible connected hardware. |
Stop Flashing | Stops flashing the system IPMI light on the compatible connected hardware. |
SCALE Credential options are collected in this section of the UI and organized into a few different screens:
The Credentials > Users screen displays a list of user accounts added to the system. By default built-in users except for root are hidden until you make them visible.
Toggle Build-In Users displays either the Show Built-In Users or Hide Built-in Users dialogs based on the current Users list view. If hidden, the Show Built-in Users dialog opens. Click Show to display the list of users.
To hide built-in users, click Toggle Built-In Users again to open the Hide Built-in Users dialog. Click Hide to display only non-built-in users again.
The Users screen shows the pre-defined administrator role assigned to the user.
Add opens the Add User screen.
Click on a user row to show the user details screen.
The expanded view of each user includes details for that user, including the home directory location, shell, Samba authentication, SSH key, and sudo command access (if assigned). It provides the option to edit or delete the user, and access user audit logs.
Edit opens the Edit User screen. Delete opens a delete confirmation dialog.
The Add User and Edit User configuration screens display the same setting options. Built-in users (except the root user) do not include the Home Directory Permissions settings, but all new users created, such as those for an SMB share like the smbguest user, do.
Identification settings specify the name, user name, password, and user email.
User ID and Group settings specify the user ID and groups this user belongs to.
Directory and Permissions settings specify the user home directory and the permissions for that home directory.
Authentication settings specify authentication methods, the public SSH key, user administration access, and enable/disable password authentication. The add and edit user screens grant access to a shell option, but the privilege screen Web Shell Access setting determines the ability to see the System Settings > Shell screen.
The Credentials > Local Groups screen displays a list of groups configured on the screen. By default, built-in groups are hidden until you make them visible.
To see built-in groups, click the Show Built-In Groups toggle. The toggle turns blue and all built-in groups display. Click the Show Built-In Groups toggle again to show only non-built-in groups on the system.
The Credentials > Local Groups screen displays the No groups screen if no groups other than built-in groups are configured on the system.
Add opens the Add Group configuration screen.
Privileges opens the Privileges screen
Click the
arrow or anywhere on a row to expand that group and show the group management buttons.Use Members to manage membership and Edit or Delete to manage the group.
Click Add to open the Add Group configuration screen.
Setting | Description |
---|---|
GID | Required. Enter a unique number for the group ID (GID) TrueNAS uses to identify a Unix group. Enter a number above 1000 for a group with user accounts (you cannot change the GID later). If a system service uses a group, the group ID must match the default port number for the service. |
Name | Required. Enter a name for the group. The group name cannot begin with a hyphen (-) or contain a space, tab, or any of these characters: colon (:), plus (+), ampersand (&), hash (#), percent (%), carat (^), open or close parentheses ( ), exclamation mark (!), at symbol (@), tilde (~), asterisk (*), question mark (?) greater or less than (<) (>), equal (=). You can only use the dollar sign ($) as the last character in a user name. |
Privileges | Attaches administrator role privileges to the group. Privileges is an experimental early release feature that defines administrator roles. Using custom administrator roles aside from the defaults is not supported. Do not modify the local administrator or primary admin user privileges! Only use if you need users in this group to access limited areas of the web UI or access in the TrueNAS API. |
Allowed sudo commands | Use to list specific sudo commands allowed for group members. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. Grants limited root-like permissions for group members when using these commands. Using sudo prompts the user for their account password. |
Allow all sudo commands | Select to give group members permission to use all sudo commands. Using sudo prompts the user for their account password. |
Allowed sudo commands with no password | Use to list specific sudo commands allowed for group members with no password required. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example /usr/bin/nano. Grants limited root-like permissions for group members when using these commands. Exercise caution when allowing sudo commands without password prompts. It is recommended to limit this privilege to trusted users and specific commands to minimize security risks. |
Allow all sudo commands with no password | Not recommended. Select to give group members the ability to use all sudo commands with no password required. |
Samba Authentication | Select to allow this group to authenticate to and access data shares with SMB samba shares. |
Allow Duplicate GIDs | Not recommended. Select to allow more than one group to have the same group ID. Use only if absolutely necessary, as duplicate GIDs can lead to unexpected behavior. |
Click Edit on an expanded group in the Groups screen to open the Edit Group screen.
Edit Group has the same fields and checkboxes as Add Group, except that it does not include Allow Duplicate GIDs.
Use the Update Members screen to manage group permissions and access for large numbers of user accounts.
To add user accounts to the group, select users and then click the right arrow . To remove user accounts from the group, select users and then click the left arrow . Select multiple users by holding Ctrl while clicking each entry.
Click Save.
The Privileges feature is an early release experimental feature. Use the Privileges screens to view default administrator groups and roles, or define customized groupings of roles for different local or Directory Service-imported account groups.
Only the Readonly Admin, Sharing Admin, and Full Admin roles are supported in the Web UI. Users can experiment with defining a new privilege but should NOT edit the existing predefined administrator roles! Editing the unrestricted administrator account privilege can result in lost access to the system!
Add opens the New Privilege screen.
Click on a listed privilege to expand the row and show details on the privilege. Edit opens the Edit Privilege screen.
The new and edit privilege screens show the same settings but not all settings are editable.
Setting | Description |
---|---|
Name | Enter a name for the new privilege. Names can include the dash (-) or underscore(_) special characters, and upper and lowercase alphanumeric characters. Enter a descriptive name for the privilege. |
Local Groups | Click in the field to see a dropdown list of available groups to apply the privilege to. Do not add the predefined administrator or builtin groups! Only select new user groups created if you experiment with this function. |
Directory Services Groups | Click in the field to see a dropdown list of available groups to apply the privilege to. |
Roles | Click in the field to see a dropdown list of all available roles available to assign to the new privilege. |
Web Shell Access | Select to allow a user assign the new privilege access to the System Settings > Shell screen. |
Assigned administrator roles display on the Users Screen.
The SCALE Directory Services section contains options to edit directory domain and account settings, set up Idmapping, and configure authentication and authorization services in TrueNAS SCALE.
The Directory Services screen opens with two options, Active Directory and LDAP. You can configure one or the other but not both.
Configure Active Directory opens the Active Directory configuration screen.
Configure LDAP opens the LDAP configuration screen.
After configuring Active Directory or LDAP, the Directory Services screen includes the widgets for each option.
Show to the right of Advanced Settings opens a dialog warning users of the risk incorrect configuration can cause. Continue closes the dialog and permits access to Idmap, Kerberos Settings, Kerberos Realms, and Kerberos Keytabs configuration widgets.
The Advanced Settings include the Idmap, Kerberos Settings, Kerberos Realms, and Kerberos Keytab widgets.
Changing Advanced settings can be dangerous if done incorrectly. Use caution before saving.
The Active Directory widget displays after you configure SCALE settings for your Active Directory instance. The widget includes Status, and the Domain Name and Domain Account Name you configured.
Settings opens the Active Directory screen with a subset of settings you can edit.
The Active Directory configuration screen has two screens, Basic Options the default view, and Advanced Options. After configuring Active Directory, the edit Active Directory screen includes both the basic and advanced options, but the basic options are a limited subset of settings of what is available when you add AD.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or there are fewer users than expected are available in the permissions editors.
Leave Domain disconnects the TrueNAS system from the Active Directory server.
The edit version of the Basic Options screen only includes the Domain Name and Enable options. The Basic Options settings are included on the Advanced Options screen.
The Advanced Options screen displays the same settings on both the add and edit versions of the Active Directory screen. On the add Active Directory screen, the Advanced Options screen includes the Basic Options settings. On the edit screen, the Advanced Options displays the subset found on the Basic Options screen.
The LDAP widget displays after you configure SCALE settings for your LDAP instance. The widget includes Status, and the Hostname and Base DN and Bind DN you configured.
Settings opens the LDAP screen.
The LDAP configuration screen has two screens, Basic Options the default view, and Advanced Options. After configuring LDAP, the edit LDAP screen includes both the basic and advanced options.
Rebuild Directory Service Cache resyncs the cache if it gets out of sync or there are fewer users than expected are available in the permissions editors.
The settings on the Basic Options also display on the Advanced Options screen.
The settings on the Advanced Options screen include the Basic Options screen.
Idmap in Linux is essentially a translation of a range of IDs into another or the same range of IDs. Idmap works in conjunction with the Winbind facility of SAMBA to map owner and group SIDs to user IDs (UIDs) and group IDs (GIDs).
Only administrators experienced with configuring Id mapping should attempt to add new or edit existing idmaps. Misconfiguration can impact system operation.
The Idmap widget in the Advanced Settings on the Directory Services screen displays idmaps added to SCALE.
Add opens the Add Idmap configuration screen.
Click on any instance to open the Edit Idmap screen.
The Idmap widget header opens the Idmap screen.
The Idmap screen displays a list view of idmaps configured on your SCALE system.
Add opens the Add Idmap screen.
Click on an Idmap on the widget to open the screen for the selected idmap.
The settings on the Add Idmap and Edit Idmap change based on the selection made in both the Name and Idmap Backend fields.
Setting | Description |
---|---|
Name | (Required) Select an option from the dropdown list, SMB - Primary Domain or Custom Value. SMB - Primary Domain reduces the fields displayed on the Add Idmap screen. Selecting Custom Value adds The Custom Name field. |
Custom Name | Displays below the Name field after selecting Custom Value in the Name field. Enter the pre-Windows 2000 domain name. |
Idmap Backend | (Required) Select the backend plugin interface for Winbind to use to store SID to UID/GID mapping tables. The correct setting depends on the environment you deployed the NAS in. Options are AD for Active Directory, LDAP for an LDAP environment. AUTORID is similar to RID but it can automatically assign IDs for different domains. NSS provides a means to map Unix users and groups to Windows accounts. RFC2307 provides a way for Winbind to read ID mappings from records in an LDAP server defined in RFC 2307. RID provides a way to use an algorithmic mapping scheme to map UIDs/GIDs and SIDs. TDB is similar to RID but it is an allocating backend, which means it needs to allocate new users and group IDs in order to create new mappings. The selected option changes the settings displayed on the Add Idmap screen. |
DNS Domain Name | Enter the DNS name of the domain. |
Range Low | (Required) Enter a value for the least number of members. Works with the Range High to establish the range of UID/GID numbers the Idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it. |
Range High | (Required) Enter a value for the greatest number of members. Works with the Range Low to establish the range of UID/GID numbers the Idmap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS ignores it. |
Options Settings The Options settings change based on the selected Name and Idmap Backend fields.
Setting | Description |
---|---|
Schema Mode | (Required) Select the schema to use with LDAP authentication for SMB shares. You must configure the LDAP server with Samba attributes to use a Samba Schema. Options include RFC2307 (included in Windows 2003 R2) and Service for Unix (SFU). For SFU 3.0 or 3.5, choose SFU. For SFU 2.0, choose SFU20. |
Unix Primary Group | Select to fetch the primary group membership from the LDAP attributes (gidNumber). If unselected, the primary group membership is calculated via the primaryGroupID LDAP attribute. |
Unix NSS Info | Select sets Winbind to retrieve the login shell and home directory from the LDAP attributes. If unselected, when the AD LDAP entry lacks the SFU attributes the smb4.conf parameters template shell and template homedir are used. |
The settings for Add Idmap displays a subset of those on the default screen.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to AD shares the same settings as the default screen but it includes DNS Domain Name.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to AUTORD shares the some of the same settings on the AD screen but the Options settings are different.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to LDAP shares the some of the same settings on the AD screen but it adds the Certificate option, and the Options settings are different.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to NSS shares the same settings as the AD screen. There is only one Options setting.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to RFC2307 shares the same settings as the LDAP screen, and some of the same Options settings.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to RID shares the same settings as the AD screen. There is only one Options setting.
The Add Idmap screen with Name set to Custom Value and Idmap Backend set to TDB shares the same settings as the AD screen. There is only one Options setting.
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.
The Kerberos Settings widget in the Advanced Settings on the Directory Services screen displays current settings.
Settings opens the Kerberos Settings configuration screen.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!
The Kerberos Settings screen includes two fields used to configure auxiliary parameters.
If you do not understand Kerberos auxiliary parameters, do not attempt to configure new settings!
Setting | Description |
---|---|
Appdefaults Auxiliary Parameters | Additional Kerberos application settings. See the appdefaults section of krb.conf(5) for available settings and usage syntax. |
Libdefaults Auxiliary Parameters | Additional Kerberos library settings. See the libdefaults section of krb.conf(5) for available settings and usage syntax. |
Kerberos 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.
The Kerberos Realms widget in the Advanced Settings on the Directory Services screen displays currently configured realms.
Add opens the Add Kerberos Realm configuration screen.
Click on any instance to open the Edit Kerberos Realm screen.
Click on the Kerberos Realms widget header to open the Kerberos Realms screen.
The Kerberos Realms screen displays a list view of realms configured on your SCALE system.
Actions includes the option to Add a new realm. Add opens the Add Kerberos Realm screen.
The
button opens the actions options for the selected realm. Options are Edit which opens the Edit Kerberos Realm screen for the selected realm, and Delete that opens a delete confirmation dialog.The settings found on the Add Kerberos Realm and Edit Kerberos Realm screens are the same.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!
Setting | Description |
---|---|
Realm | (Required) Enter the name of the realm as a domain name, For example, example.com. AD configured SCALE systems pre-populate this field with the required information. |
KDC | Enter the name of the Key Distribution Center (KDC).The KDC acts as as the third-party authentication service for Kerberos. Separate multiple values by pressing Enter. For example, kdc1.example.com press Enter then kdc2.example.com. |
Admin Server | Define the server that performs all database changes. Separate multiple values by pressing Enter. |
Password Server | Define the server that performs all password changes. Separate multiple values by pressing Enter. |
Kerberos 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.
The Kerberos Keytab widget in the Advanced Settings on the Directory Services screen displays added keytabs.
Add opens the Add Kerberos Keytab configuration screen.
Click on any instance to open the Edit Kerberos Keytab screen.
The Kerberos Keytab widget header opens the Kerberos Keytabs screen.
The Kerberos Realms screen displays a list view of realms configured on your SCALE system.
Actions includes the option to Add a new keytab. Add opens the Add Kerberos Keytab screen.
The
button opens the actions options for the selected keytab. Options are Edit which opens the Edit Kerberos Keytab screen for the selected keytab, and Delete that opens a delete confirmation dialog.The settings found on the Add Kerberos Keytab and Edit Kerberos Keytab screens are the same.
Kerberos is extremely complex. Only system administrators experienced with configuring Kerberos should attempt it. Misconfiguring Kerberos settings, realms, and keytabs can have a system-wide impact beyond Active Directory or LDAP, and can result in system outages. Do not attempt configure or make changes if you do not know what you are doing!
Setting | Description |
---|---|
Name | Enter a name for this Keytab. If configured, SCALE populates this field with what it detects in Active Directory. |
Kerberos Keytab | Browse to the keytab file to upload. |
TrueNAS stores cloud backup services credentials, SSH connections, and SSH keypairs configured using the widgets on the Backup Credentials screen. Users can set up backup credentials with cloud and SSH clients to back up data in case of drive failure.
The Backup Credentials screen displays the Cloud Credentials, SSH Connections and SSH Keypairs widgets.
The Cloud Credentials widget displays a list of cloud storage credentials configured on the system.
Before adding cloud credentials for a cloud storage provider, the Cloud Credentials widget displays No Cloud Credentials configured.
Add opens the Cloud Credentials configuration screen.
Click the name of a cloud credential to open the Cloud Credentials configuration screen populated with the settings for that credential.
The Cloud Credentials configuration screen displays settings to add or edit cloud credentials TrueNAS uses to integrate with cloud storage providers.
These providers are supported for Cloud Sync tasks in TrueNAS SCALE:
Use Verify Credentials after entering the authentication settings to verify you can access the cloud storage provider account with the credentials you entered.
The selection in Provider changes the Authentication settings.
Setting | Description |
---|---|
Provider | Required. Default is set to Storj. Select the cloud storage provider from the options on the dropdown list. |
Name | Enter a name for this cloud credential. For example, cloud1 or amazon1. |
Storj authentication includes going to the Storj-TrueNAS sign-in screen to either create a new Storj-TrueNAS account or log into an existing Storj-TrueNAS account, and then returning to SCALE to enter the S3 credentials provided by Storj for this credential.
Amazon S3 has basic authentication and advanced authentication settings. This section provides information on the basic authentication settings.
This section provides information on Amazon S3 advanced authentication settings for endpoints. The basic authentication settings are required when using the advanced settings.
This section provides information on the BackBlaze B2 authentication settings.
Several cloud storage providers use OAuth authentication and a required access token to authenticate the cloud storage account. Providers that use these methods are Box, Dropbox, Google Photo, pCloud, and Yandex.
FTP and SMTP cloud storage providers use host name, port, and user credentials to authenticate accounts. SMTP uses SSH hosts, port, and user credentials and also uses a private key.
Google Cloud Storage authentication uses a Google service account json key credential file generated by the Google Cloud Platform Console to authenticate the account. Obtain the json file, download it to the system server and then upload it to the Preview JSON Service Account Key field. Use Choose File to browse to the file location on the server.
Google Drive uses OAuth authentication, a required access token, and a team drive ID to authenticate accounts.
HTTP uses an HTTP host URL to authenticate account credentials.
Hubic uses an access token to authenticate the account. Enter the token generated by a Hubic account into the Access Token field.
Mega uses the username and password for the MEGA user account to authenticate the account credentials.
Microsoft Azure Blob Storage uses the Microsoft Azure account name and account key to authenticate the account credentials.
OpenStack Swift uses several required settings to authenticate credential accounts. The AuthVersion setting selection changes setting options displayed in Advanced Options.
The AuthVersion option selected changes the settings displayed in Authentication Advanced Options. Auto(vX), v1, and v2 use the same advanced authentication settings but V3 displays additional settings.
WebDAV uses the URL, service type and user credentials to authenticate the account credentials.
The Backup Credentials screen displays the SSH Connections and SSH Keypairs widgets.
You must also configure and activate the SSH Service to allow SSH access.
The SSH Connections and SSH Keypairs widgets display a list of SSH connections and keypairs configured on the system.
The SSH Connections widget allows users to establish Secure Socket Shell (SSH) connections. The SSH Keypairs widget allows users to generate SSH keypairs required to authenticate the identity of a user or process that wants to access the system using SSH protocol.
Add button in the SSH Connections widget opens the SSH Connections configuration window. The connection name on the widget is a link that opens the SSH Connections configuration screen already populated with the saved settings for the selected connection.
The settings displayed on the SSH Connections configuration screens are the same whether you add a new connection or edit an existing connection.
Name | Description |
---|---|
Name | Required. Enter a unique name for this SSH connection. For example, use ssh and a server name or number like sshsys1 or sshtn121 where sys1 or tn121 are server designations. |
Setup Method | Default is set to Semi-automatic (TrueNAS only). Select Semi-automatic (TrueNAS only) to simplify setting up an SSH connection with another TrueNAS or FreeNAS system without logging into that system to transfer SSH keys. Select Manual to enter all settings when setting up an SSH connection with a non-TrueNAS server. Displays other setting options required to manually configure an SSH connection. Requires copying a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt. |
These authentication settings display when Setup Method is Semi-automatic (TrueNAS only).
Name | Description |
---|---|
TrueNAS URL | Enter the host name or IP address of the remote system. Use a valid URL scheme for the remote TrueNAS URL. IP address example of https://10.231.3.76. |
Admin Username | Enter the user name for logging into the remote system. |
Admin Password | Enter the user account password for logging into the remote system. |
One-Time Password (if necessary) | One-Time Password if two-factor authentication is enabled. |
Username | Username on the remote system used to login via SSH. |
Private Key | Select a saved SSH keypair or you can import the private key from a previously created SSH keypair or select Generate New to create a new keypair to use for the connection to this remote system. |
These authentication settings display when Setup Method is Manual. You must copy a public encryption key from the local system to the remote system. A manual setup allows a secure connection without a password prompt.
Name | Description |
---|---|
Host | Enter the host name or IP address of the remote system. A valid URL scheme is required. An IP address example is https://10.231.3.76. |
Port | Enter the port number on the remote system to use for the SSH connection. |
Username | Enter the user name for logging into the remote system. |
Private Key | Select a saved SSH keypair or select Generate New to create a new keypair to use for the connection to this remote system. |
Remote Host Key | Enter the remote system SSH key for this system to authenticate the connection. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate this field. |
Discover Remote Host Key | Click to connect to the remote system and attempt to copy the key string to the related TrueNAS field. |
Name | Description |
---|---|
Connect Timeout | Enter time (in seconds) before the system stops attempting to establish a connection with the remote system. |
Save automatically opens a connection to the remote TrueNAS and exchanges SSH keys.
The SSH Keypairs widget on the Backup Credentials screen lists SSH keypairs added to the TrueNAS SCALE system.
The name of the keypair listed on the widget is a link that opens the SSH Keypairs configuration screen.
The
The
delete icon opens the a delete dialog. Click Confirm and then Delete to remove the stored keypairs from the system.The SSH Keypairs configuration screen displays the same settings for both add and edit options. Click Add to open a new configuration form, or click on an existing keypair to open the configuration screen populated with the settings for the selected keypair.
Name | Description |
---|---|
Name | Required. Enter a unique name for this SSH keypair. Automatically generated keypairs are named after the object that generated the keypair with key appended to the name. |
Generate Keypair | Click to have TrueNAS SCALE automatically generate a new keypair and populate the Private Key and Public Keys fields with these values. |
Private Key | See Authentication in SSH/Authentication. |
Public Key | See Authentication in SSH/Authentication |
Save adds the keypair to the widget and activates the more_vert with options to Download Private Key and Download Public key.
The Certificates screen displays widgets for Certificates, Certificate Signing Requests (CSRs), Certificate Authorities (CA), and ACME DNS-Authenticators that each provice access to all the information for certificates, certificate signing requests (CSRs), certificate authorities (CA), and ACME DNS-authenticators respectively.
Each TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface, but users can make custom certificates for authentication and validation while sharing data.
The Certificates widget on the Credentials > Certificates screen displays certificates added to SCALE, and allows you to add new certificates, or download, delete, or edit the name of an existing certificate. Each TrueNAS comes equipped with an internal, self-signed certificate that enables encrypted access to the web interface.
The
deletes the certificate from your server.
Each certificate listed on the widget is a link that opens the **Edit Certificate screen.
Add opens the Add Certificate wizard.
The Add Certificate wizard screens step users through configuring a new certificate on TrueNAS SCALE. The wizard has five different configuration screens, one for each step in the certificate configuration process:
Many of the settings in the Add Certificate wizard are the same as those in the Add CA and Add Certificate Signing Request wizards.Before creating a new certificate, configure a new CA if you do not already have one on your system. Creating a internal certificate requires a CA exist on the system.
The Identifier and Type options specify the certificate name and choose whether to use it for internal or local systems, or import an existing certificate.
Users can also select a predefined certificate extension from the Profiles dropdown list.
Certificate Options settings choose the signing certificate authority (CSR), the type of private key type to use (as well as the number of bits in the key used by the cryptographic algorithm), the cryptographic algorithm the certificate uses, and how many days the certificate authority lasts.
The Certificate Options settings change based on the selection in Type on the Identifier and Type screen.
The Key Type selection changes fields displayed. RSA is the default setting in Key Type. The Signing Certificate Authority field requires you have a CA already configured on your system. If you do not have a Certificate Authority (CA) configured on your system, exit the Add Certificate wizard and add the required CA.
Setting Type on the Identifier and Type screen to Import Certificate changes the options displayed on the Certificate Options configuration screen.
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.
The Certificate Subject screen does not display when Type on Internal Certificate is set to Import Certificate.
The Extra Constraints step contains certificate extension options.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that option needs.
When Type on Identifier and Type is set to Import Certificate the Import Certificate options screen displays.
The final step screen is the Confirm Options that displays the certificate Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and any configured Usages.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
The certificate listed on the Certificates widget is a link that opens the Edit Certificate screen.
The Edit Certificate screen displays the fixed Subject settings, the type, path, and other details about that certificate that are not editable. You can enter an alphanumeric name for the certificate in Identifier if you want to rename the certificate. You can use underscore (_) and or dash (-) characters in the name.
View/Download Certificate opens a window with the certificate string. Use the
clipboard icon to copy the certificate to the clipboard or Download to download the certificate to your server. Keep the certificate in a secure area where you can back up and save it.View/Download Key opens a window with the certificate private key. Use the
clipboard icon to copy the public key to the clipboard or Download to download the key to your server. Keep the private key in a secure area where you can back up and save it.The Certificate Authorities widget on the Credentials > Certificates screen displays certificate authorities(CAs) added to SCALE, and allows you to add new CAs, or download, delete, or edit the name of an existing CA.
The download icon downloads the CA to your server.
deletes the CA from your server.
Each CA listed on the widget is a link that opens the Edit CA screen.
Add opens the Add CA wizard that steps you through setting up a certificate authority (CA) that certifies the ownership of a public key by the named subject of the certificate.
The Add CA wizard screens step users through configuring a new certificate authority on TrueNAS SCALE. The wizard has five different configuration screens, one for each step in the CA configuration process:
The Identifier and Type options specify the CA name and choose whether to create a new CA or import an existing CA.
Users can also select a predefined certificate extension from the Profiles dropdown list.
The Certificate Options settings specify the type of private key to use (as well as the number of bits in the key used by the cryptographic algorithm), the cryptographic algorithm the CA uses, and how many days the CA lasts.
The Certificate Options settings do not display if Type on the Identifier and Type screen is set to Import CA.
The Key Type selection changes fields displayed. RSA is the default setting in Key Type.
The Certificate Subject settings define the location, name, and email for the organization using the certificate.
Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
The Certificate Subject settings do not display if Type on the Identifier and Type screen is set to Import CA.
The Extra Constraints options contain certificate extension options.
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that option needs.
When Type on Identifier and Type is set to Import CA the Import Certificate screen displays.
The final step screen is the Confirm Options that displays the CA Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and any configured Usages. For Import CA type, the screen displays Type and Certificate.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
The Certificates screen includes the Certificate Signing Requests widget that displays a list of certificate signing requires (CSRs) configured on the system.
Each CSR listed is a link that opens the Edit CA screen for the selected CSR.
The download icon downloads the CSR to your server.
deletes the CSR from your server.
Each CSR listed on the widget is a link that opens the Edit CSR screen.
Add opens the Add CSR wizard that steps you through setting up a CSR that certifies the ownership of a public key by the named subject of the certificate. The Certificate Signing Requests section allows users configure the message(s) the system sends to a registration authority of the public key infrastructure to apply for a digital identity certificate.
The Add CSR wizard screens step users through configuring a new certificate signing request (CSR) on TrueNAS SCALE. The wizard has five different configuration screens, one for each step in the CA configuration process:
The Identifier and Type settings specify the certificate signing request (CSR) name and whether to create a new CSR or import an existing CSR.
Users can also select a predefined certificate extension from the Profile dropdown list.
The Certificate Options settings specify the type of private key type to use, the number of bits in the key used by the cryptographic algorithm, and the cryptographic algorithm the CSR uses.
There are no Certificate Options settings if Type on the Identifier and Type screen is set to Import Certificate Signing Request.
The Key Type selection changes fields displayed. RSA is the default setting in Key Type.
The Certificate Subject settings lets users define the location, name, and email for the organization using the certificate. Users can also enter the system fully-qualified hostname (FQDN) and any additional domains for multi-domain support.
The Certificate Subject settings do not display if Type on the Identifier and Type screen is set to Import Certificate Signing Request.
The Extra Constraints settings contains certificate extension options:
The Extra Constraints settings change based on the selection in Type on the Identifier and Type screen.
After selecting Basic Constraints, Authority Key Identifier, Extended Key Usage, or Key Usage, each displays more settings that option needs.
When Type on Identifier and Type is set to Import Certificate Signing Request the Import Certificate screen displays.
The final step screen is the Confirm Options that displays the CA Type, Key Type, Key Length, Digest Algorithm, Lifetime, Country, and Basich Constraints Config. For Import Certificate Signing Request type, the screen displays Type, Signing Request and Private Key.
Save adds the certificate to SCALE. Back returns to previous screens to make changes before you save. Next advances to the next screen in the sequence to return to Confirm Options.
The Certificates screen includes the ACME DNS-Authenticators widget that displays a list of configured authenticators. The Automatic Certificate Management Environment (ACME) DNS-Authenticators screen allows users to automate certificate issuing and renewal. The user must verify ownership of the domain before TrueNAS allows certificate automation.
ACME DNS is an advanced feature intended for network administrators or AWS professionals. Misconfiguring ACME DNS can prevent you from accessing TrueNAS.
Each authenticator listed is a link that opens the Edit ACME DNS-Authenticator screen for the selected authenticator.
deletes the authenticator from your server.
Add opens the Add ACME DNS-Authenticator screen.
The system requires an ACME DNS authenticator and CSR to configure ACME certificate automation.
Fields change based on Authenticator selection.
Setting | Description |
---|---|
Name | Required. Enter an internal identifier for the authenticator. |
Authenticator | Select a DNS provider from the dropdown list and configure any required authenticator attributes. Options are cloudflare, Amazon route53, OVH, and shell. |
cloudflare activates the Cloudflare Email, API Key, and API Token fields.
Setting | Description |
---|---|
Cloudflare Email | Enter the email address for the Cloudflare account. |
API Key | Enter the API Key. |
API Token | Enter the API token. |
route53 activates the Access Key Id and Secret Access Key fields.
Setting | Description |
---|---|
Access Key Id | Enter the access key ID. |
Secret Access Key | Enter the secret access key. |
OVH activates the OVH Application Key, OVH Application Secret, OVH Consumer Key, and OVH Endpoint fields.
Setting | Description |
---|---|
OVH Application Key | Enter the application key. |
OVH Application Secret | Enter the application secret. |
OVH Consumer Key | Enter the consumer key. |
OVH Endpoint | Enter the endpoint. |
Enables users to pass an authenticator script, such as acme.sh, to shell and add an external DNS authenticator. shell activates the Authenticator script, Running user, Timeout, and Propagation delay fields.
The shell authenticator option is meant for advanced users. Improperly configured scripts can result in system instability or unexpected behavior.
Setting | Description |
---|---|
Authenticator script | Enter the path to an ACME DNS authenticator script on the system. |
Running user | Enter the username of the account that initiates the script, usually admin. |
Timeout | Enter a timeout length (in seconds) for generated certificates. |
Propagation delay | Enter a DNS propagation delay time (in seconds) for ISP domain caching. |
Two-factor authentication is time-based and requires a correct system time setting.
The Two-Factor Authentication screen has buttons to manage two-factor authentication (2FA) credentials, and it displays a different message depending on if you have 2FA enabled or disabled.
To configure 2FA settings go to the Advanced settings screen. For more information, see the Managing Global 2FA tutorial.
Renew Secret changes the system-generated Secret and Provisioning URI values.
Show QR opens a QR code dialog. Scan with an authenticator app on your mobile device. We recommend Google Authenticator.
The KMIP screen has two areas, KMIP Key Status that displays keys synced between a KMIP server and TrueNAS database and KMIP Server with the KMIP configuration settings.TrueNAS EnterpriseKMIP on TrueNAS SCALE Enterprise is used to integrate the system within an existing centralized key management infrastructure and use a single trusted source for creating, using, and destroying SED passwords and ZFS encryption keys.
The KMIP Key Status area of the KMIP screen lists ZFS/SED keys synced between a KMIP server and the TrueNAS database.
Sync Keys synchronizes keys issued by the KMIP server with the TrueNAS database. This button is active when a KMIP key sync is pending.
Clear Sync Keys cancels a pending synchronization. This button is active when a KMIP key sync is pending or in progress but not completed.
Setting | Description |
---|---|
Server | Enter the host name or IP address of the central key server. |
Port | Enter the connection port number on the central key server. Default value 5696 is the kmip.truenas.com port number. |
Certificate | Select an existing certificate or enter a new one to use for key server authentication. Requires a valid certificate to verify the key server connection. Warning: for security reasons, protect the certificate used for key server authentication. |
Certificate Authority | Select an certificate authority (CA) or enter a new one to use for connecting to the key server. Requires a valid CA public certificate to authenticate the connection. Warning: for security reasons, protect the certificate authority used for key server authentication. |
Manage SED Passwords | Select to manage self-encrypting drive (SED) passwords with KMIP. Enabling this option allows the key server to manage creating or updating the global SED password, creating or updating individual SED passwords, and retrieving SED passwords when SEDs are unlocked. Disabling this option leaves SED password management with the local system. |
Manage ZFS Keys | Select to use the KMIP server to manage ZFS encrypted dataset keys. The key server stores, applies, and destroys encryption keys whenever an encrypted dataset is created, when an existing key is modified, an encrypted dataset is unlocked, or an encrypted dataset is removed. Disabling this option leaves all encryption key management with the local system. |
Enabled | Select to activate KMIP configuration and begin syncing keys with the KMIP server. |
Change Server | Select to move existing keys from the current key server to a new key server. To switch to a different key server, enable key synchronization, then select this setting, update the key server connection configuration, and click Save. |
Validate Connection | Select to test the server connection and verify the chosen certificate chain. To test, configure the Server and Port values, select a Certificate and Certificate Authority, select this setting, and click Save. |
Force Clear | Select to cancel any pending key synchronization. |
The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) and VM devices. The No Virtual Machines screen displays if there are no VMs configured on the system or if you delete all VMs on the system.
Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.
The screen displays a list of VMs configured on the TrueNAS SCALE system. The State toggle displays and changes the state of the VM. Autostart, when selected, automatically starts the VM if the system reboots, otherwise you must manually start the VM.
Click on a VM to expand it and open the details screen with details on that VM and options for a VM. Click Start to start the VM and show additional options.
The Create Virtual Machine configuration wizard displays all settings to set up a new virtual machine.
Use Next and Back to advance to the next or return to the previous screen to change a setting. Use Save to close the wizard screens and add the new VM to the Virtual Machines screen.
The Operating System settings specify the VM operating system type, the time the VM system clock uses, the boot method, and display type.
The CPU and Memory settings specify the CPU mode, model, and memory size. They also let you specify the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.
The Disks settings allow specifying how virtual disks are added. Options are to create a new zvol on an existing dataset for a disk image or use an existing zvol or file for the VM. You also specify the disk type, zvol location, and size.
The Network Interface settings specify the network adapter type, mac address, and physical network interface card associated with the VM.
The Installation Media settings specify the operation system installation media image on a dataset or upload one from the local machine.
The GPU settings specify the graphic processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.
The Confirm Options screen displays a summary of settings for the VM. It shows the number of CPUs, cores, threads, memory, name of the VM, and the disk size.
Click Save to add the VM to the Virtual Machines screen. Click Back to return to the previous screens to make changes.
Expand any VM on the Virtual Machines screen to show the details and options for a VM. Details include the basic information on the number of virtual CPUs, cores, and threads, the amount of memory, boot load and system clock types, the display port number, and the shutdown timeout in seconds.
Starting the VM shows additional options for the VM.
Delete removes the VM configuration from your system.
The Clone dialog allows you to create an exact duplicate of the VM using the name entered.
Naming the clone VM is optional. The cloned VM displays on the Virtual Machines list with the extension _clone0. If you clone the same VM again the extension for the second clone is clone1.
Click Serial Shell to open the VM Serial Shell screen where you can enter commands for the selected virtual machine.
Click Virtual Machines in the header to return to the Virtual Machine screen.
The Edit VM screen settings are a subset of those found on the Create Virtual Machine screens. It only includes the general settings found on the wizard Operating System screen, CPU and Memory, and GPUs screen settings. To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.
The Edit screen General Settings specify the basic settings for the VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.
The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.
The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.
The Devices screen displays a list of VM devices configured on your system. By default, every VM displays three devices: Disks, NIC, and Display.
Add opens the Add Device screen. Settings change based on the various device types.
Each device listed on the Devices screen has the same three options, accessed by clicking the
at the right of the device row:Edit opens the Edit type Device screen where type is the device type selected. Settings vary based on the type of device selected in Device Type. See Add Device screen. Device Type only displays on the Add Device screens.
Delete opens a dialog. Delete Device confirms you want to delete the device.
Details opens an information dialog that lists the port, type, bind IP, and other details about the device. Click Close to close the dialog.
The Add Device screen displays different settings based on the Device Type selected.
The Apps option on the main feature panel opens the Installed Applications screen. The screen displays No Applications Installed before you install the first application.
The first time you open the Applications screen, it displays an Apps Service Not Configured status on the screen header.
Click Settings > Choose Pool to choose a storage pool for Apps.
After an Apps storage pool is configured, the status changes to Apps Service Running.
Use Check Available Apps or Discover Apps to open the Discover applications screen to see widgets for applications available in SCALE.
After installing an application, the Installed screen populates the Applications area with a table of applications. Each application listed shows the name, status, CPU, RAM, disk and update information for the application.
Use Search to enter the name and search for an installed application.
The Bulk Actions dropdown list displays if you select the Applications checkbox or the checkbox to the left of an individual installed application. The Applications checkbox selects all installed apps. The checkbox to the left of an individual application selects that application.
Settings only displays on the Installed Applications screen and displays the global options that apply to all applications.
The Choose a pool for Apps dialog includes the Pool dropdown list that shows the list of pools available on your system. Choose sets the selected pool for use by applications. Use the Settings > Choose Pool option to change the pool.
Migrate applications to the new pool starts moving application data from an existing pool to the new pool specified after you click Choose. Select Migrate applications to the new pool when changing the applications pool and migrating data from the existing pool to the new one.
Advanced Settings opens the Kubernetes Settings configuration screen.
The Unset Pool option under Settings displays a confirmation dialog. Click UNSET to unset the pool. When complete, a Success dialog displays.
This screen displays all container images currently downloaded on TrueNAS.
Entering characters in the Search filters the images list to only Image ID or Tags entries matching the entered characters.
Clicking checkboxes from the images list shows Bulk Operations to update or delete images. Click for a single image entry shows the same update or delete options.
The Pull Image button opens a side panel with options to download specific images to TrueNAS.
Setting | Description |
---|---|
Image Name | Enter the full path and name for the specific image to download. Use the format registry/repository/image. |
Image Tag | Enter the specific image tag string to download that specific version of the image. The default latest pulls whichever image version is most recent. |
Docker Registry Authentication | Optional. Only needed for private images. |
Username | User account name to access a private Docker image. |
Password | User account password to access a private Docker image. |
The Bulk Action dropdown list allows you to apply actions to one more applications installed and running on your system.
Options are Start All Selected, Stop All Selected, Upgrade All Selected, and Delete All Selected.
The Application Info widget shows for each application on the Installed application screen. The widget includes the name, version number, date last updated, source link for the application, developer, catalog and train name.
Web Portal opens the application login or sign-up web page.
Delete deletes the application deployment but does not remove it from the catalog or train in TrueNAS SCALE.
Edit opens an Edit Application configuration screen with the settings found on the install wizard screen for the application.
Update opens a window for the application showing the current version and the new version the upgrade installs.
The Delete dialog asks for confirmation to delete the selected application.
Confirm activates the Continue button. Continue initiates the delete operation.
Update on the Application Info widget displays after clicking the Update All button on the Installed applications header. Both buttons only display if TrueNAS SCALE detects an available update for an application. The application widget on the Discover screen also displays and update badge.
Update opens an upgrade window for the application that includes two selectable options, Images (to be updated) and Changelog. Click on the down arrow to see the options available for each.
Upgrade begins the process and opens a counter dialog that shows the upgrade progress. When complete, the update badge and buttons disappear and the application Update state on the Installed screen changes from Update Available to Up to date.
The Workloads widget shows the pod information for the selected installed application. Information includes number of pods, used ports, number of deployments, stateful sets, and container information. One icon links to the pod shell and another to pod logs.
The Shell Shell button opens the Choose Pod window. After selecting the options a Shell for the pod opens.
The Logs Logs button opens the Choose Pod window. After selecting the options, a window with logs for pod opens.
The Choose Pod window lets you choose the pod, active container, and shell commands to use when the Applications > Pod Shell screen displays.
Setting | Description |
---|---|
Pods | Required. Select the pod installed from the dropdown list. |
Containers | Required. Select the container from the dropdown list. |
Commands | Enter the shell commands. |
Choose opens the Pod Shell or Pod Log screen based on the Workloads widget icon clicked.
Click Installed on the breadcrumb to return to the Installed applications screen.
The Pod Logs screen opens a shell displaying logs for the selected installed application. Each Pod Log screen includes a banner with the Application Name, Pod Name and Container Name.
The History widget for each application displays Kubernetes related events. The refresh icon updates the information in this widget.
The Notes widget for each application displays any notes related to the application. If there are no notes, the widget does not display. Example content ranges from links to TrueNAS documentation on the application to a CLI command to get to the application URL in the Shell.
Each application has an installation wizard with settings that application uses or needs to deploy the application container. The edit screen opens the same installation wizard, but some settings might not be editable.
Install on the application widget on the Discover screen opens the application information screen for that application.
Each application information screen includes the catalog, version, train, home page link, and keywords to find the app in TrueNAS searches.
The screen includes three widgets:
The screen includes small screenshots of the application website that when clicked open larger versions of the image.
Install opens the installation wizard for the application.
The bottom of the screen includes widgets for similar applications found in the catalog.
Each application has the same or similarly named setting sections. The install and edit wizard screens include a navigation panel on the right of the screen that lists and links to the setting sections. A red triangle with an exclamation point marks the sections with required settings. An asterisk marks required fields in a section. You can enter a new setting in fields that include a preprogrammed default.
Not all applications include all of the following sections:
Setting Section | Description |
---|---|
Application Name | Includes the required Application Name and Version settings. SCALE provides the default application name and current version number of the application in the TRUENAS chart. After installing the application, the name is not editable. Version is not included on the Edit application screen. |
Application Configuration* | Includes certificates, credential or token authentication, timezone, host name, and environment variable settings that vary by application. Settings are editable. Some applications include network settings in this section. |
Networking | Includes container network settings such as the port number assigned for communication, and to set an option that the host network settings manually or to use the default option to use the preprogrammed settings defined in SCALE. |
Storage | Includes the option to enable and configure extra volumes such as a data and configuration volume, or other volumes the application might need. |
Scaling/Upgrade Policy | Includes the update strategy or policy setting. Another application might include Update strategy in the Workload Configuration section. |
Resource Reservation | Includes the GPU configuration setting. |
Advanced DNS Settings | Includes options to configure advanced DNS settings. |
Resource Limits | Includes the option to limit CPU and memory resources the Kubernetes pod uses in SCALE. |
CronJob Configuration | Includes options to enable, configure, and schedule cron jobs as part of the application deployment. |
The Discover screen displays New & Updated Apps application widgets for the official TrueNAS Chart, Community, and Enterprise train applications based on the Trains settings selected on the Edit Catalog screen. First time SCALE installation includes the Chart catalog train.
The breadcrumbs at the top of the header provide links to the previous or the main applications screen. Click a link to open that screen.
Custom App opens the Install Custom App screen.
The Discover screen includes a search field, links to other application management screens, and filters to sort the application widgets displayed.
The three application screen links are:
Filters shows a list of sort categories that alter how application widgets display. Filter information includes the Catalog, Sort options and the Categories dropdown field.
Catalog displays the default catalog TRUENAS.
Sort options are:
Categories allows selecting which application categories display. Options are New-And-Updated, Recommended, S3, File-Sharing, Financial, Games, Media, Monitoring, Networking, Productivity, Security, and Storage. Click in the field to see the list, then click on a category. Repeat to select multiple categories.
The Install Custom App screen displays the setting options needed to install a third-party application not included in the TRUENAS catalog. See Install Custom App Screens for more information.
The Catalog screen displays a list of application catalogs installed on TrueNAS SCALE, default catalog is TRUENAS.
The options at the top right of the screen include the Refresh All and Add Catalog options. Refresh All starts a catalog refresh operation. Add Catalog opens the Add Catalog screen after first displaying a warning confirmation dialog.
Click on a catalog row to expand it and show the options available for each catalog:
The default TRUENAS catalog does not show the Delete option.
Add Catalog at the top of the Catalogs screen opens a warning dialog before it opens the Add Catalog screen.
Click Continue to open the Add Catalog screen.
Field | Description |
---|---|
Catalog Name | enter the name the TrueNAS uses to look up the catalog. For example, mycatalog. |
Force Create | Select to add the catalog to the system even if some trains are unhealthy. |
Repository | Enter the valid git repository URL. For example, https://github.com/mycatalog/catalog. |
Preferred Trains | The trains TrueNAS uses to retrieve available applications for the catalog. The default is stable (and optionally: incubator). |
Branch | Specify the git repository branch TrueNAS should use for the catalog. The default is main. |
The Edit Catalog screen settings specify the name and train the UI should use to look up the catalog and retrieve applications for the catalog. The Catalog Name is not editable, but you can change the train.
Setting | Description |
---|---|
Catalog Name | Enter a name TrueNAS should use to look up the catalog. |
Preferred Train | Select the train(s) from which the UI retrieves available applications for the catalog. Dropdown list options are charts, test, enterprise, and community. |
Refresh initiates the catalog refresh operation for the selected catalog.
Opens a confirmation dialog before deleting the catalog. You cannot delete the TRUENAS catalog.
The Summary option for each catalog Name Catalog Summary window where Name is the name of the catalog displays the current catalog status (Healthy, Unhealthy), the train, and list of application information. The Trains dropdown options are All, charts, community, and enterprise. The Status dropdown list options are All, Healthy, and Unhealthy. Select options to alter the information included in the displayed summary. Close closes the window.
Setting | Description |
---|---|
Train | Select the trains you want to include in the catalog summary information. Options are All, charts, test, enterprise or community. |
Status | Select the statuses you want to include in the catalog summary information. Options are All, Healthy, or Unhealthy. This is useful to filter the summary to locate trains or applications with the Unhealthy status. |
The Install Custom App screen allows you to configure third-party applications using settings based on Kubernetes. Use the wizard to configure applications not included in the TRUENAS catalog. The Install Custom button on the Discover application screen opens the Install Custom App configuration wizard.
The breadcrumbs in the top header link to other screens. Discover closes the Install Custom App screen and opens the Discover screen. ix-chart closes the Install Custom App screen and opens the Installed screen. The panel on the right of the screen links to each setting area. Click on a heading or setting to jump to that area of the screen. Click in the Search Input Fields to see a list of setting links.
Settings are grouped into Application Name, Container Images, Container Entrypoint, Container Environment Variables, Networking, Port Forwarding, Storage, Workload Details, Scaling/Upgrade Policy, Resource Limits, and Portal Configuration sections.
Application Name has two required settings, Application Name and version. After completing the installation these settings are not editable.
Container Images settings specify the container image details. They define the image tag, when TrueNAS pulls the image from the remote repository, how the container updates, and when a container automatically restarts.
Container Entrypoint settings specify both commands and arguments to use for the image. These can override any existing commands stored in the image. Check the documentation for the application you want to install for entry point commands or arguments you need to enter.
Container Environment Variables settings define additional environment variables for the container. Check the documentation for the image and add any required variables here.
Networking settings specify network policy, addresses, and DNS services if the container needs a custom networking configuration.
See the Kubernetes documentation for more details on host networking. You can create additional network interfaces for the container or 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 Kubernetes DNS services documentation for more details.
Port Forwarding settings specify the container and node ports, and the transfer protocol. Choose the protocol and enter port numbers for both the container and node. You can define multiple port forwards.
The Storage settings specify persistent host paths and share data that separate from the lifecycle of the container. Create the storage volumes in SCALE and set the host path volume to a dataset and directory path. You can mount SCALE storage locations inside the container with host path volumes. Define the path to the system storage and the container internal path for the system storage location to appear. 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. To do this, name each new dataset and define a path where that dataset appears inside the container.
Workload Details settings specify how to deploy workloads in the container (pod). Kubernetes defines workloads as applications running in the pod. Workload Details settings specify if containers in a pod run with TTY or STDIN enabled, allow enabling any device on the host or configuring host capabilities, and if you run the container as a user or group.
Scaling/Upgrade Strategy settings configure how application upgrades replace pods.
Select Create new pods and then kill the old ones to recreate the container. This retains the existing configuration and container until the upgrade completes before removing it.
Select Kill existing pods before creating new ones to do rolling upgrades. This removes the existing pod and start with a newly updated pod. Killing existing pods is useful if your old pod is not functioning properly. For fewer issues, select Kill existing pods before creating new ones.
Resource Reservation settings configure GPU device allocation for application processes. Settings only display if the system detects available GPU device(s).
Select the number of devices to allocate from the Select GPU dropdown list of devices. See Allocating GPU for more information.
Resource Limits settings specify the CPU and memory limits to place on the Kubernetes pod.
The Portal Configuration settings configure the web UI portal for the container.
Select Enable WebUI Portal (only supported in TrueNAS SCALE Bluefin) to display the web portal configuration settings.
The Reporting screen displays graphs of system information for CPU, disk, memory, network, NFS, partition, target, UPS, ZFS, and system functions. Use the dropdown in the upper right corner to select between reporting graph display options. The CPU report displays by default.
To configure a third-party reporting integration, such as Graphite, click Exporters to open the Reporting Exporters screen.
The following sections provide examples of each report graph.
Displays the CPU Temperature, CPU Usage, and System Load graphs.
Displays graphs for each selected system disk and by report type.
Displays both the Physical memory utilization and Swap utilization graphs.
Displays an Interface Traffic graph for each interface in the system.
Displays both the Processes and Uptime graphs.
Displays the UPS Charging percentage, UPS Runtime, UPS Voltage - Battery, UPS Voltage - Input, UPS Voltage - Output, UPS Input Current, UPS Input Frequency, UPS Input Load, and UPS Temperature.
The UPS service must be configured with a compatible Uninterruptible Power Supply (UPS) device.
Displays the ARC Size, ARC Hit Ratio, ARC Requests demand_data, ARC Requests demand_metadata, ARC Requests prefetch_data, and ARC Requests prefetch_metadata graphs with the Arc and L2 gigabytes and hits (%), and the hits, misses and total number of requests.
Exporter on the Reporting screen opens the Reporting Exporter screen. The Reporting Exporters screen displays reporting exporters configured on the system. Exporting enables TrueNAS SCALE to send Netdata reporting metrics to another time-series database. Exporters send Netdata reporting records in the form of JSON objects to third party reporting collection cloud services or applications installed on servers. For more information, see the Netdata exporting reference guide.
Add opens the Add Reporting Exporter screen.
Use the Add Reporting Exporter screen to configure third party reporting integrations.
Setting | Description |
---|---|
Name | Enter a unique name for the exporter configuration. If configuring multiple instances, give each a distinct name. |
Type | Select the report object format. At present, GRAPHITE is the only current supported option. Selecting GRAPHITE displays the exporter configuration settings |
Enable | Select to enable sending reporting data to the configured exporter. Leave checkbox clear to disable the explorer without removing configuration. |
Additional settings populate based on the selected Type option.
See Adding a Reporting Exporter for guidance with configuring a Graphite exporter on TrueNAS.
The TrueNAS SCALE Update screen provides users with two different methods to update the system, automatic or manual. The screen can have up to four information panes:
The screen displays the Current Train and a link to more information on the current train. Check for Updates Daily and Download if Available sets SCALE to check the update server daily for updates on the specified train. When selected, the system automatically downloads an update if one is available. The refresh
button refreshes the information displayed on the screen.The upgrade operation pane only displays when the system detects an update. It includes the upgrade operation information with the current release and available update release versions.
If the current train is not a production release, the screen includes a notification.
Finally, the screen includes three buttons if an update is detected: Download Updates, Apply Pending Updates, and Install Manual Update File. If not detected, only the option to manually install an update file displays.
Download Updates downloads the update file detected by the system.
Apply Pending Update opens the Save configuration settings from this machine before updating? window before starting the automatic installation process for the downloaded update file.
Install Manual Update File also opens the Save configuration settings from this machine before updating? window, then opens the Manual Update window.
The Check Release Notes link under the update opens the release notes TrueNAS website page for the update.
The Save configuration settings from this machine before updating? window displays after clicking Apply Pending Update or Install Manual Update File.
Always select Include Password Secret Seed before you click Save Configuration. Save Configuration downloads the system configuration file to your system. Keep the configuration file in a safe place that is regularly backed up.
The Manual Update screen displays after you either click Save Configuration or Do Not Save on the save configuration settings window.
Current Version displays the SCALE release version running on your system.
Choose File opens a browse window where you can locate the downloaded update file.
The Update File Temporary Storage Location dropdown list includes two option, Memory Device or a mount location on your system. Select the temporary location option on the to designate where the system stores the upgrade file. Select Memory Device or select one of the mount locations on the dropdown list to keep a copy in the server.
Click Apply Update to start the installation.
The TrueNAS SCALE System Settings > General screen includes widgets for Support, GUI, Localization, NTP, and system Email functions. Each widget displays information about current settings and includes one or more buttons for related actions and configuration options.
The Manage Configuration dropdown provides three options to backup, restore, or reset system configuration settings.
TrueNAS SCALE allows users to manage the system configuration via uploading/downloading configurations, or resetting the system to the default configuration.
The Download File option opens the Save Configuration dialog, which allows users to download the current system configuration to the local machine.
The Export Password Secret Seed option includes encrypted passwords in the downloaded configuration file. This option allows you to restore the configuration file to a different operating system device where the decryption seed is not already present. Users must physically secure configuration backups containing the seed to prevent unauthorized access or password decryption.
The Upload File option opens the Upload Config dialog, which allows users to choose a previously saved TrueNAS SCALE configuration to replace the current system configuration.
Choose File opens a file browser window where you can locate the downloaded and saved configuration. After selecting the file, it displays in the Upload Config window. Upload uploads the selected configuration file.
All passwords reset if the uploaded configuration file saved without Export Password Secret Seed enabled.
The Reset to Defaults option opens the Reset Configuration dialog, which resets the system configuration to factory settings and restarts the system. Users must set a new login password.
Save the system current configuration with the Download File option before resetting the configuration to default settings.
If you do not save the system configuration before resetting it, you may lose data that you did not back up, and you will not be able to revert to the previous configuration.
The Support widget displays general hardware and software specs and contains links to the Documentation Hub, TrueNAS Forums, and offers TrueNAS Licensing information.
Add License opens the License screen.
File Ticket opens the Feedback Window.
The License screen allows you to copy your license into the box and save it.
The How would you rate this page? icon opens a feedback window. Alternately, go to System Settings > General, find the Support widget, and click File Ticket to see the feedback window.
The feedback window allows users to send page ratings, comments, and report issues or suggest improvements directly to the TrueNAS development team. Submitting a bug report or improvement suggestion requires a free Atlassian account.
Click between the different tabs at the top of the window to see different options for your specific feedback.
Silver/Gold Coverage Customers can enable iXsystems Proactive Support. This feature automatically emails iXsystems when certain conditions occur in a TrueNAS system.
Click Settings on the GUI widget to open the GUI Settings screen that allows users to configure the TrueNAS SCALE web interface address.
Click Settings on the Localization widget to open the Localization Settings screen that lets users localize their system to a specific region.
Click Add on the NTP Servers widget to open the Add NTP Server screen that allows users to configure Network Time Protocol (NTP) servers, which sync the local system time with an accurate external reference.
Click Settings on the Email widget to open the Email Options screen that allows users to configure the system email send method.
Advanced settings have reasonable defaults in place. A warning message displays for some settings advising of the dangers of making changes. Changing advanced settings can be dangerous when done incorrectly. Use caution before saving changes.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before making any changes.
The Advanced settings screen provides configuration options for the console, syslog, audit, kernel, sysctl, storage (system dataset pool), replication, WebSocket sessions, cron jobs, init/shutdown scripts, allowed IP addresses, isolated GPU device(s), self-encrypting drives, and global two-factor authentication.
Save Debug saves a system debug file to the local machine.
The Console widget displays the current console settings for TrueNAS.
Configure opens the Console configuration screen.
Console settings configure how the Console Setup menu displays, the serial port it uses and the port speed, and the banner users see when accessing it.
The Syslog widget displays the existing system logging settings that specify how and when the system sends log messages to the syslog server.
Configure opens the Syslog configuration screen.
The Syslog settings specify the logging level the system uses to record system events to the boot device. There are also options to configure a remote syslog server for recording system events.
The Audit widget displays the current audit settings configured on the system. The public-facing API allows querying audit records, exporting audit reports, and configuring audit dataset settings and retention periods.
Click Configure to open the Audit configuration screen.
The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.
The Kernel widget shows options for configuring the Linux kernel installed with TrueNAS SCALE.
The Cron Jobs widget displays No Cron Jobs configured until you add a cron job, then it shows the information on cron job(s) configured on the system.
Add opens the Add Cron Job configuration screen.
Click on any job listed in the widget 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.
Cron Jobs lets users configure jobs that run specific commands or scripts on a regular schedule using cron(8). Cron jobs help users run repetitive tasks.
The Init/Shutdown Scripts widget displays No Init/Shutdown Scripts configured until you add either a command or script, then the widget lists the scrips configured on the system.
Add opens the Add Init/Shutdown Script configuration screen. Any script listed is a link that opens the Edit Init/Shutdown Script configuration screen populated with the settings for that script.
Init/Shutdown Scripts lets users schedule commands or scripts to run at system startup or shutdown.
The Sysctl widget displays either No Sysctl configured or the existing sysctl settings on the system.
Add to add a tunable that configures a kernel module parameter at runtime.
The Add Sysctl or Edit Sysctl configuration screen settings let users set up tunables that configure kernel parameters at runtime.
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 perform simultaneously.
Click Configure to open the Replication configuration screen.
Enter a number for the maximum number of simultaneous replication tasks you want to allow the system to process and click Save.
The Access widget displays a list of all active sessions, including the user who initiated the session and what time it started. It also displays the Token Lifetime setting for your current session. It allows administrators to manage other active sessions and to configure the token lifetime for their account.
Terminate Other Sessions ends all sessions except for the one you are currently using. You can also end individual sessions by clicking the logout icon next to that session if it is not the admin user session. You must check a confirmation box before the system allows you to end sessions.
The logout button is inactive for your current session and active for all other current sessions. It cannot be used to terminate your current session.
Token Lifetime displays the configured token duration for your current session (default five minutes). TrueNAS SCALE logs out user sessions that are inactive for longer than that configured token setting. New activity resets the token counter.
If the configured token lifetime is exceeded, TrueNAS SCALE displays a Logout dialog with the exceeded ticket lifetime value and the time that the session is scheduled to terminate.
Configure opens the Token Settings screen.
The Token Settings screen allows users to configure the Token Lifetime for the current account.
Select a value that fits your needs and security requirements. Enter the value in seconds.
The default lifetime setting is 300 seconds or five minutes.
The maximum is 2147482 seconds, or 24 days, 20 hours, 31 minutes, and 22 seconds.
The Allowed IP Addresses widget displays IP addresses and networks added to the system that are allowed to use the API and UI. If this list is empty, then all IP addresses are allowed to use API and UI.
Configure opens the Allowed IP Addresses configuration screen.
Entering an IP address to the allowed IP address list denies access to the UI or API for all other IP addresses not listed.
Use only if you want to limit system access to a single or limited number of IP addresses. Leave the list blank to allow all IP addresses.
Click Add next to Allowed IP Addresses to add an entry to the allowed IP Addresses list. Ensure the first address and/or subnet includes your current client system.
You can enter a specific IP address, for example, 192.168.1.1, for individual access, or use an IP address with a subnet mask, like 192.168.1.0/24, to define a range of addresses.
You can add as many addresses as needed.
Click Save. A Restart Web Service dialog opens. Select Confirm and then Continue to restart the web UI and apply changes.
The Self-Encrypting Drive (SED) widget displays the system ATA security user and password.
Configure opens the Self-Encrypting Drive configuration screen.
The Self-Encrypting Drive configuration screen allows users to set the ATA security user and create a SED global password.
The Isolated GPU Device(s) widget displays any isolated graphics processing unit (GPU) device(s) configured on your system.
Configure opens the Isolated GPU PCI Ids screen, which allows users to isolate additional GPU devices.
The Isolate GPU PCI IDs configuration screen allows you to isolate GPU devices for a virtual machine (VM).
To isolate a GPU, you must have at least two in your system; one allocated to the host system for system functions and/or applications and the other available to isolate for use by a VM.
Select the GPU device ID from the dropdown list and click Save.
Isolated GPU devices are reserved for use by configured applications or a VM.
To allocate an isolated GPU device, select it while creating or editing the VM configuration. When allocated to a VM, the isolated GPU connects to the VM as if it were physically installed in that VM and becomes unavailable for any other allocations.
The Global Two Factor Authentication widget allows you to set up two-factor authentication (2FA) for your system.
Configure opens the Global Two Factor Authentication Settings configuration screen.
TrueNAS EnterpriseThe System Security widget allows administrators of Enterprise-licensed systems to enable or disable FIPS 140-2 compliant algorithms. This requires a system reboot to apply the settings. High Availability (HA) systems reboot the standby controller and then prompt to failover and reboot the primary controller.
Settings opens the System Security configuration screen.
Click the Enable FIPS toggle to enable or disable enforcement, then click Save. The system prompts to reboot (or failover for HA systems) to apply the settings.
The System Settings > Boot screen contains options for monitoring and maintaining the TrueNAS install pool and disks. This includes managing OS restore points, called boot environments, for the TrueNAS system.
The System Settings > Boot screen displays four options at the top right of the screen.
Setting | Description |
---|---|
Stats/Settings | Opens the Stats/Settings window with the Boot pool Condition, Size and Used, and Last Scrub Run statistics for the operating system device, and provides the option to change the default duration between the operating system device scrubs from every 7 days to a new duration in days. |
Boot Pool Status | Opens the Boot Pool Status screen that displays the status of each device in the operating system device (boot pool), options for managing boot-pool devices, and lists any read, write, or checksum errors. |
Scrub Boot Pool | Opens the Scrub dialog. Performs a manual data integrity check (scrub) of the operating system device. |
The System Settings > Boot > Boot Pool Status screen shows the status of the current boot-pool. It includes the current status, the path, and the number of read, write and checksum errors.
The vertical ellipsis next to a device displays two options, Attach or Replace.
The boot status Attach screen settings specify a device as the disk member and how much of the device is used.
Select a device from the Member Disk dropdown.
Select Use all disk space to use the entire capacity of the new device.
Replace settings specify a replacement device from the Member Disk dropdown.
Each time the system updates to a new software release, it creates a new boot environment. You can also clone an existing boot environment to create an operating system restore point.
Each boot environment on the list includes:
Select the checkbox(es) for each boot environment. Displays the Batch Operations that allows you to delete the selected environments at one time.
The vertical ellipsis displays a list of boot environment actions that change based on whether it is activated or not.
The vertical ellipsis for an environment displays actions available to that environment.
Action | Boot State | Description |
---|---|---|
ActivateActivate | Deactivated | Opens the Activate dialog. Changes the System Boot screen status to Reboot and changes the current Active entry from Now/Reboot to Now, indicating that it is the current boot environment but is not used on next boot. |
CloneClone | Both states | Opens the Clone Boot Environment window. Copies the selected boot environment into a new entry. Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters. |
RenameRename | Both states | Opens the Rename Boot Environment window. Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters. |
DeleteDelete | Deactivated | Opens the Delete dialog. Does not display if the boot environment is activated/ You cannot delete the default or activated boot environment. Removes the highlighted entry and also removes that entry from the boot menu. |
KeepKeep | If set to false | Opens the Keep dialog, and toggles the boot environment action to Unkeep. Use to prevent the TrueNAS updater from automatically deleting the environment to make more space for a new environment when there is insufficient space for it. |
UnkeepUnkeep | If Keep is set to True | Opens the Unkeep dialog, and toggles the boot environment action to Keep. Use to allow TrueNAS updater to automatically delete the environment to make space for a new boot environment when there is not enough space for it. |
TrueNAS EnterpriseThis article only applies to SCALE Enterprise (HA) systems.
The System Settings > Failover screen displays settings used on SCALE Enterprise (HA) systems to turn the failover function on or off, sync the primary and standby controllers, and allow administrator users to configure failover. The main menu option and screen only display on Enterprise (HA) systems with the correct license applied.
Setting | Description |
---|---|
Disable Failover | Select to turn failover off. Leave clear to enable failover. |
Default TrueNAS controller | Select to make the current active controller the default controller when both TrueNAS controllers are online and HA is enabled. To change the default TrueNAS controller, leave unselected on the default TrueNAS controller and allow the system to fail over. This process briefly interrupts system services. |
Network Timeout Before Initiating Failover | Enter a number in seconds to wait after a network failure before triggering a failover. Default is 0 which means failover occurs immediately, or after two seconds when the system is using a link aggregate. |
Sync To Peer | Initiates a sync operation that copies over the primary controller configuration to the standby controller. Opens the Sync To Peer dialog to confirm the operation. |
Sync From Peer | Initiates a sync operation that copies over the standby controller configuration to the primary controller. |
Sync To Peer and Sync From Peer buttons each open a confirmation dialog before SCALE performs the operation requested.
Setting | Description |
---|---|
Reboot standby TrueNAS controller | Select to cause the standby controller to reboot after the sync operation completes. |
Confirm | Select to confirm you want to perform the sync-to-peer operation. |
Proceed | Begins the sync operation. |
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.
The
Configure icon opens the service configuration screen.The NFS service row has one additional NFS Sessions icon that opens the NFS Sessions screen.
The SMB service row has two additional icons that link to other screens:
Select Start Automatically to set the service to start after the system reboots.
Click on the Running toggle to start the service or to stop it if it is running. Stop services before changing configuration settings.
The File Transfer Protocol (FTP) is a simple option for data transfers. The SSH options provide secure transfer methods for critical objects like configuration files, while the Trivial FTP options provide simple file transfer methods for non-critical files.
The FTP service has basic and advanced setting options. Click the edit for FTP to open the Basic Settings configuration screen.
To configure FTP, go to System Settings > Services and find FTP, then click edit.
Settings | Description |
---|---|
Port | Enter the port the FTP service listens on. |
Clients | Enter the maximum number of simultaneous clients. |
Connections | Enter the maximum number of connections per IP address. 0 is unlimited. |
Login Attempts | Enter the maximum attempts before the client disconnects. Increase if users are prone to misspellings or typos. |
Notransfer Timeout | Enter the maximum number of seconds a client is allowed to spend connected, after authentication, without issuing a command which results in creating an active or passive data connection (sending/receiving a file or receiving a directory listing). |
Timeout | Enter the maximum client idle time in seconds before disconnecting. The default value is 600 seconds. |
Advanced Settings include the General Options on the Basic Settings configuration screen and allow you to specify access permissions, TLS settings, bandwidth, and other settings to customize FTP access.
Access settings specify user login, file, and directory access permissions.
Settings | Description |
---|---|
Always Chroot | Only allows users to access their home directory if they are in the wheel group. This option increases security risk. To confine FTP sessions to a local user home directory, enable chroot and select Allow Local User Login. |
Allow Root Login | Select to allow root logins. This option increases security risk, so enabling this is discouraged. 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. | |
Allow Anonymous Login | Select to allow anonymous FTP logins with access to the directory specified in Path. Selecting this displays the Path field. Enter or browse the location to populate the field. |
Allow Local User Login | Select to allow any local user to log in. Only members of the ftp group may log in by default. |
Require IDENT Authentication | Select to require IDENT authentication. Setting this option results in timeouts when IDENT is not running on the client. |
File Permissions | Select the default permissions for newly created files. |
Directory Permissions | Select the default permissions for newly created directories. |
TLS settings specify the authentication methods, such as if you want to encrypt the data you transfer across the Internet.
Settings | Description |
---|---|
Enable TLS | Select to allow encrypted connections. Requires a certificate (created or imported using Credentials > Certificates). |
Certificate | Select the SSL certificate for TLS FTP connections from the dropdown list. Click Manage Certificates to go to Credentials > Certificates. |
TLS Policy | Select the policy from the dropdown list of options. Options are On, off, Data, !Data, Auth, Ctrl, Ctrl + Data, Ctrl +!Data, Auth + Data or Auth +!Data. Defines whether the control channel, data channel, both channels, or neither channel of an FTP session must occur over SSL/TLS. The policies are described here. |
TLS Allow Client Renegotiations | Select to allow client renegotiation. We do not recommend this option. Setting this option breaks several security measures. See mod_tls for details. |
TLS Allow Dot Login | TrueNAS checks the user home directory for a |
TLS Allow Per User | Select to allow sending a user password unencrypted. |
TLS Common Name Required | Select to require the common name in the certificate to match the FQDN of the host. |
TLS Enable Diagnostics | Select for more verbose logging, which is helpful when troubleshooting a connection. |
TLS Export Certificate Data | Select to export the certificate environment variables. |
TLS No Certificate Request | Select if the client cannot connect, likely because the client server is not correctly handling the server certificate request. |
TLS No Empty Fragments | Not recommended. This option bypasses a security mechanism. |
TLS No Session Reuse Required | This option reduces connection security. Only use it if the client does not understand reused SSL sessions. |
TLS Export Standard Vars | Select to set several environment variables. |
TLS DNS Name Required | Select to require the client DNS name to resolve to its IP address and the cert contain the same DNS name. |
TLS IP Address Required | Select to require the client certificate IP address to match the client IP address. |
Settings | Description |
---|---|
Minimum Passive Port | Enter a numeric value. Used by clients in PASV mode. A default of 0 means any port above 1023. |
Maximum Passive Port | Enter a numeric value. Used by clients in PASV mode. A default of 0 means any port above 1023. |
Enable FXP | Select to enable the File eXchange Protocol (FXP). We do not recommend FXP since it leaves the server vulnerable to FTP bounce attacks. |
Allow Transfer Resumption | Select to allow FTP clients to resume interrupted transfers. |
Perform Reverse DNS Lookups | Select to allow performing reverse DNS lookups on client IPs. This option causes long delays if you do not configure reverse DNS. |
Masquerade Address | Enter a public IP address or host name. Use when FTP clients cannot connect through a NAT device. |
Display Login | Enter a message that displays to local login users after authentication. Anonymous login users do not see this message. |
Auxiliary Parameters | Used to add additional proftpd(8) parameters. |
Bandwidth settings specify the space you want to allocate for local and anonymous user uploads and downloads.
When configuring FTP bandwidth settings, we recommend manually entering the units you want to use, e.g. KiB, MiB, GiB.
Settings | Description |
---|---|
Local User Upload Bandwidth: (Examples: 500 KiB, 500M, 2 TB) | Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited. |
Local User Download Bandwidth | Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited. |
Anonymous User Upload Bandwidth | Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited. |
Anonymous User Download Bandwidth | Enter a value in KiBs or greater. A default of 0 Kib means unlimited. If you do not specify a measurement, it defaults to KiB. This field accepts human-readable input in KiBs or greater (M, GiB, TB, etc.). The default 0 KiB is unlimited. |
The iSCSI screen displays settings to configure iSCSI block shares.
The iSCSI configuration screens display seven tabs, one for each of the share configuration areas.
The Add button at the top of the Sharing > iSCSI screen works with the currently selected tab or screen. For example, if Portals is the current tab/screen, the Add button opens the Add Portal screen.
The more_vert on configure tab screens with list views display the Edit and Delete options. Edit opens the Edit screen for the selected tab screen. For example, when on the Portals tab/screen, the Sharing > iSCSI > Portals > Edit screen opens.
The Delete option opens the delete dialog for the screen currently selected.
The Add and Edit screens display the same settings.
The Target Global Configuration displays configuration settings that apply to all iSCSI shares. There are no add, edit, or delete options for this screen. It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System Settings > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
Setting | Description |
---|---|
Base Name | Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721. |
ISNS Servers | Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter. |
Pool Available Space Threshold (%) | Enters a value for the threshold percentage that generates an alert when the pool has this percent space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents. |
iSCSI listen port | The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators. |
Asymmetric Logical Unit Access (ALUA) | Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server. |
The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
The more_vert next to the portal displays the Edit and Delete options. Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.
Setting | Description |
---|---|
Description | Enter an optional description. Portals are automatically assigned a numeric group. |
Setting | Description |
---|---|
Discovery Authentication Method | Select the discovery method you want to use for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None, you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP, you must enter or create a new group in Discovery Authentication Group. |
Discovery Authentication Group | Select the discovery authentication group you want to use from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is CHAP or Mutual CHAP. Select None or Create New. Create New displays additional setting options. |
Setting | Description |
---|---|
IP Address | Select the IP addresses the portal listens to. Click Add to add IP addresses with a different network port. 0.0.0.0 listens on all IPv4 addresses, and :: listens on all IPv6 addresses. |
Port | TCP port used to access the iSCSI target. The default is 3260. |
Add | Adds another IP address row. |
The Initiators Groups screen display settings to create new authorized access client groups or edit existing ones in the list.
The more_vert next to the initiator group displays the Edit and Delete options. Delete opens the Delete dialog for the selected group ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Sharing > iSCSI > Initiators > Add screen. Edit opens the Sharing > iSCSI > Initiators > Edit screen. Both screens have the same setting options.
Setting | Description |
---|---|
Allow All Initiators | Select to allows all initiators. |
Allowed Initiators (IQN) | Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local. |
Description | Enter any notes about the initiators. |
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Add opens the Add Authorized Access screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Authorized Access screen, and Delete opens a dialog to delete the authorized access for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Group ID | Enter a number. This allows configuring different groups with different authentication profiles. Example: all users with a group ID of 1 inherit the authentication profile associated with Group 1. |
Setting | Description |
---|---|
User | User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name. |
Secret | Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a “password does not match” error until you enter the same password in Secret (Confirm). |
Secret (Confirm) | Enter the same password to confirm the user password. |
Setting | Description |
---|---|
Peer User | Optional. Enter only when configuring mutual CHAP. Usually the same value as User. |
Peer Secret | Enter the mutual secret password. Required if entering a Peer User. Must be a different password than the password in Secret. |
Peer Secret (Confirm) | Enter the same password to confirm the mutual secret password. |
The Targets screen displays settings to create new TrueNAS storage resources or edit existing ones in the list.
Add opens the Add iSCSI Targets screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit iSCSI Targets screen, and Delete opens a dialog to delete the select target. The Add iSCSI Targets and Edit iSCSI Targets screens display the same settings.
The Add iSCSI Target and Edit iSCSI Target screens display the same settings, but the current settings populate the Edit iSCSI Target screen settings for the selected share.
To access the Add iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click Add at the top of the screen. To access the Edit iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click more_vert next to the share and then click Edit.
The Extents screen displays settings to create new shared storage units or edit existing ones in the list.
Add opens the Add Extent screen.
The more_vert next to each entry opens two options, Edit and Delete. Edit opens the Edit Extent screen, and Delete opens a dialog to delete the extents for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Name | Enter a name for the extent. An Extent where the size is not 0, cannot be an existing file within the pool or dataset. |
Description | Enter any notes about this extent. |
Enabled | Select to enable the iSCSI extent. |
Setting | Description |
---|---|
Extent Type | Select the extent (zvol) option from the dropdown list. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. |
Device | Required. Displays if Extent Type is set to Device. Select the unformatted disk, controller, or zvol snapshot. |
Path to the Extent | Displays when Extent Type is set to File. Click the | to browse an existing file. Create a new file by browsing to a dataset and appending /{filename.ext} to the path. Users cannot create extents inside a jail root directory.
Filesize | Only appears if File is selected. Entering 0 uses the actual file size and requires that the file already exists. Otherwise, specify the file size for the new file. |
Logical Block Size | Enter a new value or leave it at the default of 512 unless the initiator requires a different block size. |
Disable Physical Block Size Reporting | Select if the initiator does not support physical block size values over 4K (MS SQL). |
Setting | Description |
---|---|
Enable TPC | Select to allow an initiator to bypass normal access control and access any scannable target. This allows xcopy operations that are otherwise blocked by access control. |
Xen initiator compat mode | Select when using Xen as the iSCSI initiator. |
LUN RPM | Select the option from the dropdown list. Options are UNKNOWN, 5400, 7200, 10000 or 15000. Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics. |
Read-only | Select to prevent the initiator from initializing this LUN. |
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user. The Add and Edit screens display the same settings.
Setting | Description |
---|---|
Target | Required. Select an existing target. |
LUN ID | Select the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID. |
Extent | Required. Select an existing extent. |
The System Settings > Services screen includes two icons on the NFS service row:
The UDP protocol is deprecated and not supported with NFS. It is disabled by default in the Linux kernel. Using UDP over NFS on modern networks (1Gb+) can lead to data corruption caused by fragmentation during high loads.
The Services > NFS configuration screen displays settings to customize the TrueNAS NFS service.
You can access it from System Settings > Services screen. Locate NFS and click edit to open the screen, or use the Config Service option on the Unix (NFS) Share widget options menu found on the main Sharing screen.
Select Start Automatically to activate the NFS service when TrueNAS boots.
Setting | Description |
---|---|
Bind IP Addresses | Select IP addresses to listen to for NFS requests. Leave empty for NFS to listen to all available addresses. You must configure static IPs on the interface to appear on the dropdown list. |
Calculate number of threads dynamically | Automatically sets the number of threads used by the kernel NFS server. |
Specify number of threads manually | Becomes editable after selecting Calculate number of threads dynamically. Enter an optimal number of threads used by the kernel NFS server. |
Setting | Description |
---|---|
Enabled Protocols | Select NFSv3, NFSv4, or both. If NFSv4 is selected, NFSv3 ownership model for NFSv4 clears, allowing you to select or leave it clear. |
NFSv3 ownership model for NFSv4 | Becomes selectable after selecting NFSv4. Select when you need NFSv4 ACL support without requiring the client and the server to sync users and groups. |
Require Kerberos for NFSv4 | Select to force NFS shares to fail if the Kerberos ticket is unavailable. |
Setting | Description |
---|---|
mountd(8) bind port | Enter a port to bind mountd(8). |
rpc.statd(8) bind port | Enter a port to bind rpc.statd(8). |
rpc.lockd(8) bind port | Enter a port to bind rpc.lockd(8). |
Setting | Description |
---|---|
Serve UDP NFS clients | Select if NFS clients need to use the User Datagram Protocol (UDP). |
Allow non-root mount | Only select if required by the NFS client to allow serving non-root mount requests. |
Support >16 groups | Select when a user is a member of more than 16 groups. This setting assumes group membership is configured correctly on the NFS server. |
We recommend using the default NFS settings unless you require specific settings.
When TrueNAS is already connected to Active Directory, setting NFSv4 and Require Kerberos for NFSv4 also requires a Kerberos Keytab.
The Services > S.M.A.R.T. screen displays settings to configure when S.M.A.R.T. tests run and when to trigger alert warnings and send emails.
Name | Description |
---|---|
Check Interval | Enter the time in minutes for smartd to wake up and check if any tests are configured to run. |
Power Mode | Select the power mode from the dropdown list. Options are Never, Sleep, Standby or Idle. S.M.A.R.T. only tests when the Power Mode is Never. |
Difference | Enter a number of degrees in Celsius. S.M.A.R.T. reports if a drive temperature changes by N degrees Celsius since the last report. |
Informational | Enter a threshold temperature in Celsius. S.M.A.R.T. sends a message with a LOG_INFO log level if the temperature is above the threshold. |
Critical | Enter a threshold temperature in Celsius. S.M.A.R.T. sends a message with a LOG_CRIT log level and send an email if the temperature is above the threshold. |
Click Save after changing any settings.
The System Settings > Services screen includes three icons on the SMB service row:
The SMB service screen displays setting options to configure TrueNAS SMB service settings to fit your use case.
Click Save or Cancel to close the configuration screen and return to the Services screen.
Setting | Description |
---|---|
NetBIOS Name | Automatically populates with the original system host name. Enter a name that is limited to 15 characters and cannot be the same as the Workgroup name. |
NetBIOS Alias | Enter any alias name up to 15 characters in length. If entering multiple aliases, separate alias names with a space between them. |
Workgroup | Enter a name that matches the Windows workgroup name. If you do not configure a workgroup, and Active Directory or LDAP is active, TrueNAS detects and sets the correct workgroup from these services. |
Description | (Optional) Enter any notes or descriptive details about the service configuration. |
Enable SMB1 support | Select to allow legacy SMB1 clients to connect to the server (see caution below). SMB audit logging does not work when using SMB1. |
NTLMv1 Auth | Off by default. Select to allow smbd attempts to authenticate users with the insecure and vulnerable NTLMv1 encryption. This setting allows backward compatibility with older versions of Windows, but we do not recommend it. Do not use on untrusted networks. |
As of SCALE 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support. This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SCALE SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases. Administrators should work to phase out any clients using the SMB1 protocol from their environments.
Setting | Description |
---|---|
UNIX Charset | Select the character set to use internally from the dropdown list of options. UTF-8 is standard for most systems as it supports all characters in all languages. |
Log Level | Record SMB service messages up to the specified log level from the dropdown list. Options are None, Minimum, Normal, full and Debug. By default, TrueNAS logs error and warning-level messages. We do not recommend using a log level above Minimum for production servers. |
Use Syslog Only | Select to log authentication failures in |
Local Master | Selected by default and determines if the system participates in a browser election. Leave cleared when the network contains an Active Directory or LDAP server or when Vista or Windows 7 machines are present. |
Enable Apple SMB2/3 Protocol Extensions | Select to allow MacOS to use these protocol extensions to improve the performance and behavioral characteristics of SMB shares. TrueNAS requires Apple SMB2/3 protocol extensions for Time Machine support. |
Multichannel | SMB multichannel allows servers to use multiple network connections simultaneously by combining the bandwidth of several network interface cards (NICs) for better performance. SMB multichannel does not function if you combine NICs into a LAGG. |
Administrators Group | Enter or select members from the dropdown list. Members of this group are local administrators and automatically have privileges to take ownership of any file in an SMB share, reset permissions, and administer the SMB server through the Computer Management MMC snap-in. |
Setting | Description |
---|---|
Guest Account | Select the account for guest access from the dropdown list. The default is nobody. The selected account must have permission for the shared pool or dataset. To adjust permissions, edit the dataset Access Control List (ACL), add a new entry for the chosen guest account, and configure the permissions in that entry. If you delete the selected Guest Account, the field resets to nobody. |
File Mask | Overrides default 0666 file creation mask, which creates files with read and write access for everybody. |
Directory Mask | Overrides default directory creation mask of 0777, which grants everyone directory read, write, and execute access. |
Bind IP Addresses | Select static IP addresses that SMB listens on for connections from the dropdown list. Leaving all unselected defaults to listening on all active interfaces. |
Auxiliary Parameters | Enter additional smb.conf options. Refer to the Samba Guide for more information on these settings. You can use Auxiliary Parameters to override the default SMB server configuration, but such changes could adversely affect SMB server stability or behavior. To log more details when a client attempts to authenticate to the share, add log level = 1, auth_audit:5 . |
The Service > SNMP screen settings configure SNMP (Simple Network Management Protocol) that monitors network-attached devices for conditions that warrant administrative attention.
Click the edit to open the Services > SNMP configuration screen.
Setting | Description |
---|---|
Location | Enter the location of the system. |
Contact | Enter the email address to receive SNMP service messages. |
Community | Enter a community other than the default public to increase system security. Value can only contain alphanumeric characters, underscores (_), dashes (-), periods (.), and spaces. Not required and can leave this empty for SNMPv3 networks. |
Setting | Description |
---|---|
SNMP v3 Support | Select to to enable support for SNMP version 3 and display the SNMP v3 setting fields. See snmpd.conf(5) for configuration details. |
Username | Enter a user name to register with this service. |
Authentication Type | Select an authentication method: — for none, SHA, or MD5 from the dropdown list. |
Password | Enter a password of at least eight characters. |
Privacy Protocol | Select a privacy protocol: — for none, AES, or DES from the dropdown list. |
Privacy Passphrase | Enter a separate privacy passphrase. Password is used when this is left empty. |
Setting | Description |
---|---|
Auxiliary Parameters | Enter any additional snmpd.conf options. Add one option for each line. |
Expose zilstat via SNMP | Select to enable. If enabled this option might have performance implications on your pools. |
Log Level | Select how many log entries to create. Dropdown list options are Emergency, Alert, Critical, Error, Warning, Notice, Info and Debug. |
The System Settings > Services > SSH screen allows you to set up SSH service on TrueNAS SCALE.
Click edit to open the Services > SSH configuration screen.
Allowing external connections to TrueNAS is a security vulnerability! Do not enable SSH unless you require external connections. See Security Recommendations for more security considerations when using SSH.
You must also configure SSH backup credentials to allow SSH access. See SSH Screens for more information.
The Basic Settings options display by default when you edit the SSH service.
Setting | Description |
---|---|
TCP Port | Enter the port number for SSH connection requests. |
Password Login Groups | List of TrueNAS account groups allowed to use a password for logging in to the system with SSH. Click in the field to see a list of current account groups. Begin typing in the field to filter the groups list. Left click a list item to add it to the field. Click the for an entry to remove it from the field. |
Allow Password Authentication | Select to enable and allow using a password to authenticate the SSH login. If disabled (not selected), authentication changes to require SSH keys for all users. This requires additional setup for both the SSH client and server. Warning: when directory services are enabled, this setting grants access to all users the directory service imported. |
Allow Kerberos Authentication | Select to allow Kerberos authentication. Ensure valid entries exist in Directory Services > Kerberos Realms and Directory Services > Kerberos Keytabs and the system can communicate with the Kerberos domain controller before enabling this option. |
Allow TCP Port Forwarding | Select to allow users to bypass firewall restrictions using SSH port forwarding. For best security, leave disabled and deny shell access to users. |
Advanced Settings include the General Options settings. Advanced settings specify bind interfaces, SFTP settings, ciphers and any additional parameters you want to use.
Setting | Description |
---|---|
Bind Interfaces | Select the network interface configured on your system for SSH to listen on from the dropdown list. Leave all options unselected for SSH to listen on all interfaces. |
Compress Connections | Select to attempt to reduce latency over slow networks. |
SFTP Log Level | Select the syslog(3) level of the SFTP server from the dropdown list. Options are Quiet, Fatal, Error, Info, Verbose, Debug, Debug2 or Debug3. |
SFTP Log Facility | Select the syslog(3) facility of the SFTP server option from the dropdown list. Options are Daemon, User, Auth and Local 0 through Local7. |
Weak Ciphers | Select a cipher from the dropdown list. Options are None or AES128-CBC. To allow more ciphers for sshd(8) in addition to the defaults in sshd_config(5). Use None to allow unencrypted SSH connections. Use AES128-CBC to allow the 128-bit Advanced Encryption Standard. WARNING: These ciphers are security vulnerabilities. Only allow them in a secure network environment. |
Auxiliary Parameters | Enter any sshd_config(5) options not covered in this screen. Enter one option per line. Options added are case-sensitive. Misspellings can prevent the SSH service from starting. |
The Services > UPS screen settings specify connection, shutdown and other settings to configure UPS service for servers running TrueNAS SCALE.
TrueNAS uses NUT (Network UPS Tools) to provide UPS support. For supported device and driver information, see their hardware compatibility list.
Report UPS bugs and feature requests to the NUT project.
Click edit to open the Services > UPS configuration screen.
TrueNAS EnterpriseTrueNAS High Availability (HA) systems are not compatible with uninterruptible power supplies (UPS).
General Options setting specify required UPS mode and connection. These settings change based on the Master or Slave UPS mode setting.
Setting | Description |
---|---|
Identifier | Required. Type a description for the UPS device. You can use alphanumeric, period (.), comma (,), hyphen (-), and underscore (_) characters. |
UPS Mode | Select the either Master or Slave mode from the dropdown list. Select Master if the UPS is plugged directly into the system serial port, or Slave to shut down this system before the master system. Slave displays the Remote Hostname and Remote Port fields, and removes the Driver field. The UPS remains the last item to shut down. See the Network UPS Tools Overview. |
Remote Host | Required. Enter a valid IP address for the remote system with the UPS Mode set to Master. This field displays only when UPS Mode is set to Slave. |
Remote Port | Required. Enter the open network port number of the UPS master system. The default port is 3493. This field displays only when UPS Mode is set to Slave. |
Driver | Required. Enter or select the device driver from the dropdown list. See the Network UPS Tools compatibility list for a list of supported UPS devices. This field displays only when UPS Mode is set to Master. |
Port or Hostname | Required. Enter or select the serial or USB port connected to the UPS from the dropdown list. Options include a list of port on your system and auto. Select auto to automatically detect and manage the USB port settings. When selecting an SNMP driver, enter the IP address or host name of the SNMP UPS device. |
Monitor settings specify the primary username and password, other users that have administrative access to the UPS service, and whether the default configuration listens on all interfaces.
Setting | Description |
---|---|
Monitor User | Enter a user to associate with this service. Keeping the default is recommended. |
Monitor Password | Change the default password to improve system security. The new password cannot include a space or #. |
Extra Users | Enter accounts that have administrative access. See upsd.users(5) for examples. |
Remote Monitor | Select to have the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass. |
Shutdown settings specify the UPS shutdown mode, command, and timer for the UPS service.
Setting | Description |
---|---|
Shutdown Mode | Select the battery option to used when the UPS initiates shutdown from the dropdown list. Options are UPS reaches low battery or UPS goes on battery. |
Shutdown Timer | Enter a value in seconds for the UPS to wait before initiating shutdown. Shutdown does not occur if power is restored while the timer is counting down. This value only applies when Shutdown Mode is set to UPS goes on battery. |
Shutdown Command | Enter a command to shut down the system when either battery power is low or the shutdown timer ends. |
Power off UPS | Select to power off the UPS after shutting down the system. |
Other Options settings specify warning and host sync times, a description for the UPS, and any additional parameters you want to apply to the UPS service.
Setting | Description |
---|---|
No Communication Warning Time | Enter the number of seconds to wait before alerting that the service cannot reach any UPS. Warnings continue until the situation is fixed. |
Host Sync | Upsmon waits up to this many seconds in master mode for the slaves to disconnect during a shutdown situation. |
Description | Enter a description for this service. |
Auxiliary Parameters (ups.conf) | Enter any extra options from ups.conf. |
Auxiliary Parameters (upsd.conf) | Enter any extra options from upsd.conf. |
SCALE System Settings > Shell is convenient for running command lines tools, configuring different system settings, or finding log files and debug information. When the user Shell setting is set to TrueNAS CLI, the Shell screen opens at the TrueNAS CLI prompt.
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.
The Alert Settings screen displays options to create and edit alert services and to configure warning levels and frequencies. To access this screen, click the
icon, then click the icon and select Alert Settings on the dropdown list.Use Columns to change the information displayed in the list of alert services. Options are Unselect All, Type, Level, Enabled and Reset to Defaults.
The Add Alert Service and Edit Alert Service screens show the same settings.
Use Add to create a new alert service using the Add Alert Service screen. The Type settings for AWS SNS display by default. To add an alert service for another option, use the Type dropdown list. Only the Authentication Settings change for each option.
Use the Edit Alert Service screen to modify settings for a service. Select the
icon for the service, and then click Edit to display the Edit Alert Service screen.Setting | Description |
---|---|
Name | Enter a name for the new alert service. |
Enabled | Clear the checkmark to disable this service without deleting it. |
Type | Select an option from the dropdown list for an alert service to display options for that service. Options are AWS SNS which is the default type displayed, E-Mail, InfluxDB, Mattermost, OpsGenie, PagerDuty, Slack, SNMP Trap, Telegram or VictorOPS. |
Level | Select the severity from the dropdown list. Options are Info, Notice, Warning, Error, Critical, Alert or Emergency. |
Use SEND TEST ALERT to generate a test alert to confirm the alert service works.
Click Cancel to exit the Alert Services screen without saving.
Use Save to add the new service with the settings you specify to the list of alert services.
Use the Category dropdown list to display alert settings for each category.
Applications alert settings display by default. These alerts apply to the third-party applications you deploy on your TrueNAS system.
Certificates alert settings apply to certificates you add through the Credentials > Certificates screen.
Directory Service alert settings apply to the Active Directory and LDAP servers configured on your TrueNAS.
TrueNAS Enterprise
Hardware alert settings apply to the IPMI network connections, and S.M.A.R.T. and smartd that monitors the hard drives installed on your TrueNAS system.
Key Management Interoperability Protocol (KMIP) alert settings only apply to KMIP configured on a TrueNAS Enterprise system.
Plugins alert settings apply to plugins installed on your TrueNAS.
Network alert settings apply to network interfaces configured on your TrueNAS.
Reporting alert settings apply to netdata, database size threshold, and syslog processes on your TrueNAS.
Sharing alert settings apply to iSCSI, NFS, or SMB shares and connections configured on your TrueNAS.
Storage alert settings apply to quotas, pools, snapshots, and scrub processes on your TrueNAS.
System alert settings apply to system processes, the system dataset, TrueCommand API Key, SSH logins, system reboots, updates, and the web interface.
Tasks alert settings apply to cloud sync, VMWare snapshots, replication, rsync, scrub and snapshot tasks scheduled on your TrueNAS.
UPS alert settings apply to a UPS connected to your TrueNAS.
Use the Set Warning Level dropdown list to customize alert importance. Each warning level has an icon and color to express the level of urgency.
To make the system email you when alerts with a specific warning level trigger, set up an email alert service with that warning level.
Level | Icon | Alert Notification? |
---|---|---|
INFO | No | |
NOTICE | Yes | |
WARNING | Yes | |
ERROR | Yes | |
CRITICAL | Yes | |
ALERT | Yes | |
EMERGENCY | Yes |
Use the Set Frequency dropdown list to adjust how often the system sends or displays alert notifications.
Alert frequency options are Immediately (Default), Hourly, Daily or Never. Setting the Frequency to Never prevents that alert from displaying in the Alerts Notification dialog, but it still pops up in the web UI if triggered.
TrueNAS EnterpriseThe View Enclosure screen only displays on TrueNAS SCALE Enterprise systems with compatible hardware. The UI options to select System Settings > Enclosure is not present on incompatible non-Enterprise systems.
The System Information widget on the main Dashboard displays an image of the specific TrueNAS system. Hover the mouse over the image to see the View Enclosure label. Click anywhere on the system image to open the View Enclosure screen.
The View Enclosure screen displays an image of the TrueNAS platform. Additional information about storage pools, drives, and other hardware components is available through a variety of clickable elements and buttons.
The Elements button at the top right of the View Enclosure screen displays a dropdown list of options to view information about the system or expansion shelf. The options vary by TrueNAS platform, if the system is connected to expansion shelves, and if you have an expansion shelf image selected instead of the main system. All TrueNAS systems include the Disks option. TrueNAS systems with expansion shelves include the Temperature, Power Supply, and Voltage options. The expansion shelf includes the Disks, Cooling, Services, Power Supply, SAS, Temperature, and Voltage options. Each option displays a table with readings from the system’s internal components taken over a period of time.
System images display the front view of the server by default. If the system model includes a rear view, Rear changes the image to the rear view of the system hardware. Front switches to the front view of the system chassis. Edit Label displays for system models other than the Mini.
Edit Label opens the Change Enclosure Label window. Type a name or description for the system and click Save to apply the label. Reset to Default restores the default name for the system.
System image screen include two options to change the information on the screen:
Click on a drive image to display a screen with information for that drive. Disk drive information includes the system pool, disk status, hardware details, and stats for the drive.
Identify Drive on disk detail screens turns on the LED indicator located on a physical drive bay in the system server. This helps to identify the physical drive bay that corresponds to the SCALE identification number for that drive. Select the drive on the image and then click Identify Drive. Go to the location of the system server to locate the drive bay with the LED indication turned on then check the drive location on the View Enclosure screen.
TrueNAS Mini and R30 systems do not include the IDENTIFY DRIVE function.
TrueNAS Mini systems only display the front view of the system hardware.
Pool information displays at the top of the screen. The drive bay number and disk label displays to the left of the image and the status to the right of the image. A disk image screen shows details for the drive you click on. The Disk Overview section provides general details about the system drive hardware and capacity. Drive Temperatures displays current readings for each drive in the system.
Larger TrueNAS hardware system images include a front and rear view of the chassis to show all drive bays and installed disk drives.
Click on a drive to display details for that selected drive and to access the Identify Drive option.
The screen opens showing the front view of the main image by default. Both the system and expansion shelf images show the location installed disks.
The screen includes smaller images of both the main system and expansion shelves connected to the system, on the right side of the screen. A blue vertical line to the left of the small image on the right side of the screen indicates the selected system view.
The system and expansion shelf image screens include three options to change the information shown on the screen:
Click on a drive image in the system or expansion shelf image to display a drive information screen for that drive. Disk drive information includes the system pool, disk status, hardware details, and stats for the drive.
The expansion shelf image varies based on the type of expansion shelf installed, but the disk information displayed is the same as for disks in other system disks.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The SCALE Shell automatically opens in the SCALE CLI if the admin user Shell setting on the Credentials > Local User > Add User or Edit User screen is set to TrueNAS CLI.
If set to a different shell option such as bash or zsh, enter cli
at the prompt on the shell screen.
You can also access the TrueNAS CLI through either the Console Setup Menu.
You can access the Console Setup Menu when you SSH into the TrueNAS system, after you install SCALE from the
To open the TrueNAS CLI from the Console Setup Menu, enter 6
.
The Shell screen opens in the shell option selected in the Shell setting on the Credentials > Local User > Add User or Edit User screen. If set to zsh, bash, or the other options other than TrueNAS CLI or TrueNAS Console, the screen opens at a Linux prompt.
To access the TrueNAS CLI from the Linux shell, enter cli
at the prompt and press Enter.
To exit the TrueNAS CLI, enter quit
or exit
.
The SCALE CLI includes help text for some namespaces and commands through the both the man
, and ls
commands.
To see the basic commands from any namespace, enter help
.
Use the man
command to show the help text for a namespace or command with options.
Type man namespacename
or man commandname
to display the help text for that namespace or command.
Use the ls
command while in a child namespace to view a list of commands and the help text descriptions.
You can use the ls
command for some commands that show an autofill list of options to display a list of those options with help text descriptions.
Note, not all namespaces, commands, or commands with options include help text.
Using ls
with some commands with autofill options does not always display a list view or help text for the options.
The TrueNAS CLI includes basic commands available from the CLI prompt or while in any namespace in the CLI.
To access these basic options, enter ?
or help
, then press Enter. The list of basic commands displays.
Command | Description |
---|---|
.. | Moves up one level. For example, from a namespace like auth, enter .. to return to the CLI prompt. From a child namespace like interfaces, use .. to return to the network parent namespace. |
exit | Leave the TrueNAS CLI and return to the system prompt. |
ls | Lists the namespaces and commands from the active CLI level. For example, at the top level, ls displays the main namespaces in the TrueNAS CLI, or at a main namespace level, displays the additional namespaces or commands for that level. |
man | When in a namespace, displays the help text for the command that follows man . For example, while in the network namespace, enter man create to see the help text for the create command. |
menu | Displays the Console setup menu in the TrueNAS CLI. Type 6 to exit the menu and return to the CLI prompt. |
? | Displays the list of basic commands for the TrueNAS CLI. |
/ | Returns to the main TrueNAS CLI prompt from any namespace. |
.mode | Gets or sets the output mode. |
.stacks | Enables/disables printing stack traces for errors. |
The TrueNAS CLI provides eleven top level (parent) namespaces that correspond to SCALE UI functions but not all namespaces mirror the UI counterpart. For example, the system name space includes alerts and certificates in the CLI but in the UI the counterpart is System Settings, and neither Alerts or Certificates are found under System Settings. Each parent namespace has child namespaces and commands.
Use the ls
command to view the list of namespaces or commands.
Namespace | Description |
---|---|
account | Provides access to the user and group namespaces and commands. In the UI these are found on the **Credentials screen. |
app | Provides access to the catalog, chart_release, container, docker and kubernetes namespaces and commands. |
auth | Provides access to the authentication api_key, privilege, sessions, and two_factor namespaces and commands. |
directory_service | Provides access to directory services activedirectory, idmap, kerberos, and ldap namespaces and commands. |
filesystem | Provides access to the acltemplate namespace. |
network | Provides access to network configuration, dns, interface, ipmi, route, and static_route namespaces and commands. |
service | Provides access to service ftp, ipmi, nfs, smart, smb, snmp, ssh, and vm namespaces and commands. |
sharing | Provides access to sharing iscsi, nfs, and smb namespaces and commands. |
storage | Provides access to storage dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware namespaces and commands. |
system | Provides access system acme, advanced, alert, boot, bootenv, certificate, config, core, failover, general, keychain_credential, kmip, mail, ntp_server, reporting, support, system_dataset, truecommand, truenas, tunable, update, and version namespaces and commands. |
task | Provides access to task cloud_sync, cron_job, replication, rsync, smart_test, and snapshot namespaces and commands. |
CLI namespaces and commands are case sensitive. Enter commands in lower case unless the CLI autofill indicates otherwise.
To enter a namespace or command, begin typing the name. The CLI displays an autofill list that begins with the letter typed and is available in that part of the CLI. Press the down arrow to select the name of the command or namespace. For example, the autofill list at the main CLI prompt includes only the parent namespaces that begin with the letter typed.
To enter a basic command such as checking current configuration settings in a namespace, enter namespace childnamespace config
.
The system displays the configured settings for the namespaces preceding the config
command.
You can enter a namespace, child namespace, command, command properties (options) and arguments (property=value pairs) from the main CLI prompt using autofill options.
For example, parent namespace child namespace command property=value
.
You can enter a namespace, then enter the child namespace, command, then select the command property to enter the argument (property=value) from the namespace prompt.
A command without properties does not show an autofill list. Press space to see if the command has more properties or wants input, or press Enter to apply the command.
To go up one namespace or command level, enter ..
.
Enter /
to return to the main CLI prompt and to exit the namespace(s).
Use the up or down arrow keys to select an autofill option, then press space to apply it.
You can use Backspace to erase entered text to start over.
Use the left arrow to move the cursor to the left in a command string where you change the text or use Delete to remove anything to the right of the cursor.
Use the right arrow to move the cursor to the right to the end of the command string to either continue entering command options, or to press Enter to apply the command.
TrueNAS CLI command structure varies by namespace. CLI commands can include properties (options) and/or arguments (property=value pairs), and might include flags.
Command properties that require a single value automatically add the =
delimiter after the property on the autofill list and after reaching the end of the command property inputs.
Some commands allow entering multiple arguments enclosed in curly brackets. These curly brackets could enclose multiple arguments in square brackets separated by a comma and space.
Argument properties (options) and values might require double quotes around each, and are separated by a colon :
instead of the equal sign.
Each namespace article includes command syntax examples for each namespace.
Enter the --
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
There are eleven primary or parent namespaces. Some of the primary namespaces include commands as well as having child namespaces. Each child namespaces has commands to perform various actions.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The account namespace contains two child namespaces. It provides access to user and group creation, configuration, and management.
The following articles provide information on account child authentication namespaces:
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The user namespace has 14 commands and is based on Users functions found in the SCALE API and web UI. It provides access to user account creation, configuration, and attribute management. You can also set up a local administrator account using this namespace.
The following user namespace commands allow you to manage user accounts.
You can enter commands from the main CLI prompt or from the account namespace prompt.
The create
command configures a new user account.
create
has 19 available properties for account configuration.
They are uid, username, group, group_create, home, home_mode, home_create, shell, full_name, email, password, password_disabled, locked, smb, sudo_commands, sudo_commands_nopasswd, sshpubkey, groups, and attributes.
Property arguments use the =
delimiter to separate the property and value. For example, uid=3000
.
See the table below for details.
The delete
command erases an existing user account.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_instance
command retrieves information about a user such as their username, UID (User ID), group membership, permissions, and other relevant attributes.
The get_next_uid
command displays the next available user identification number (UID).
The get_user_obj
command returns dictionary containing information from struct passwd for the user and bypasses user cache.
The has_local_administrator_set_up
command returns whether a local administrator account with a valid password exists.
The has_root_password
command is a deprecated method. Use the has_local_administrator_set_up
command instead.
The provisioning_uri
command displays the provisioning URI for the Two-Factor Authentication One-Time Password (OTP).
Theprovisioning_uri
command only returns part of the provisioning URI.
The pop_attribute
command removes attributes, defined by a key, from a user dictionary. See also set_attribute
and Create Configuration Properties.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The query
command retrieves information about a user or users and can use various query-filters and query-options.
The renew_2fa_secret
command generates a new secret for 2FA.
The set_attribute
command sets a user’s general purpose attributes dictionary key to a specified value. See also pop_attribute
and Create Configuration Properties.
The set_root_password
command is a deprecated method. Use the setup_local_administrator
command instead.
The setup_local_administrator
command creates and configures an admin account. It can be used during initial configuration.
Thesetup_local_administrator
command only works if both a local administrator and root password have not been configured. This means that you have either performed a fresh install of SCALE, and chose to not configure an admin or root password in the TrueNAS Console installer, or you have reset configuration to defaults and have not yet logged in to the SCALE Web UI. If either a local administrator or a root password exist, this command returnsError: Local administrator is already set up.
The shell_choices
command returns the shell choices available to user accounts.
The update
command updates the attributes of an existing user. For available properties, see create
.
The verify_twofactor_token
command verifies whether or not a user password is authenticated.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The group namespace contains eight commands and is based on functions found in the SCALE API and web UI. It provides access to group account creation, configuration, and management functions.
The following group namespace commands allow you to manage group settings.
You can enter commands from the main CLI prompt or from the account namespace prompt.
The create
command creates a new group.
The delete
command erases an existing group.
The get_group_obj
command returns dictionary containing information from struct grp including group name, identification number, and group members.
The get_instance
command retrieves information about a group.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_next_gid
command displays the next available group identification (GID) number.
The has_password_enabled_user
command checks whether at least one local user with a password enabled is a member of one or more provided groups.
The query
command retrieves information about a group or groups or the query-options-get_instance value specified.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The update
command updates the attributes of an existing group.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The app namespace has five child namespaces and is based on functions found in the SCALE API and web UI. It provides access to application configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the app namespace prompts.
The following articles provide information on app child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
auth commands are based on authentiation functions found in the SCALE API and web UI. Use these commands to access to authentication methods for the currently logged-in user, to generate an access token for web UI session, to access websocket session information, terminate sessions, set up user two-factor authentication and view status for the user.
Enter commands from the main CLI prompt or from the auth
namespace prompt.
Enter auth ls
to view the list of available commands and namespaces.
Commands | Description |
---|---|
auth api_key | Provides access to API key creation and management methods. |
auth api_key create | Creates an API key. |
auth api_key delete | Deletes the API key matching the ID entered. |
auth api_key get_instance | Provides API key information for the ID entered. |
auth api_key query | Provides information on all API keys configured in the system. |
auth api_key update | Updates the API key matching the ID entered. |
auth generate_token | Generates a system-access authentication token. |
auth me | Lists password, and user and group information for the currently logged-in user. |
auth privilege | This command is a Work in Progress. Do not use! |
auth privilege create | Creates a privilege. |
auth privilege delete | Deletes the privilege matching the ID entered. |
auth privilege get_instance | Provides privilege information for the ID entered. |
auth privilege query | Provides information on all privilege in the system. |
auth privilege update | Updates privilege settings for the ID entered. |
auth sessions | Provides information on all system sessions. |
auth set_attribute | This command is a Work in Progress. Do not use! |
auth terminate_other_sessions | Terminates all websocket sessions except the currently-logged in SSH session. |
auth terminate_session | Terminates the websocket session matching the ID entered. |
auth two_factor | Provides access to user two-factor authentication methods. |
auth two_factor config | Displays current 2FA settings for the currently logged-in user. |
auth two_factor update | Updates two-factor authentication settings for the ID entered. |
auth two_factor_auth | Provides the current state of two-factor authentication for currently logged-in user. |
The
auth generate_token
command generates an authentication token to use for access. The token then determines when the current session expires.
auth generate_token
has three optional properties: ttl
, attrs
, and match_origin
.
See Optional generate_token Properties below for details on these properties.
Enter property arguments using the =
delimiter to separate property and value.
Enter the command string, then press Enter.
Command returns a authentication token.
Property | Description | Syntax Example |
---|---|---|
ttl | Set time to live (ttl) value in seconds to either:600 sets session to expire after 10 minutes before the token expires and the user must log back into the U. Equates to an idle authentication sessionI.null sets the session to not expire. Not recommended as a system security best practice. | ttl=600 or ttl=null |
attrs | attrs is a general purpose object/dictionary to hold information about the token. The default value {} , represents attribute options for the token. Entering attr properties inside the curly brackets is not required. | attrs={} |
match_origin | Enter true sets the token to only allow using it from the same IP address or with the same user UID. Default value is false . | match_origin=true or mathc_origin=false |
The auth me
command provides the currently logged-in user name, user and group IDs, home directory, and user shell.
auth me
does not require entering property arguments.
Enter the command, then press Enter.
The command returns a table with the following information:
Property | Description |
---|---|
pw_name | Logged-in user name. For example, admin. |
pw_uid | Logged-in user ID (UID) number. For example, 3000. |
pw_gid | Logged-in user group ID (GID) number. For example, 3000. |
pw_gecos | The record in the /etc/passwd file, which is general information about the account or user. For example, for the admin user. |
pw_dir | Logged-in user password or home directory. For example, mnt/tank/homedir. |
pw_shell | Logged-in user shell setting. For example, /usr/bin/bash displays when Shell on either the Add User or Edit User screen is set to bash. |
The auth sessions
command returns a table with session IDs, type, origin, credential type used, and the date and time the session started.
Use the auth sessions
to obtain session IDs to use in the auth terminate_session
command.
auth sessions
does not require entering a property argument but you can include one of six properties as a flag to limit the command output to just that information.
See sessions Property Flags below for details on the optional properties.
Enter the command then press Enter. The command returns a table populated with all system sessions, current and internal type, origin, credential type and creation date and time.
Property | Description |
---|---|
id | Displays a list of session IDs. |
current | Displays a list of current sessions. true indicates an active session. |
internal | Displays a list of internally-created sessions. true indicates an internally-created via the web UI, or `false for an externally-created via SSH connection. |
origin | Displays a list of login origin for all sessions. |
credentials | Displays a list of credentials used to authenticate each session. |
created_at | Displays a list of all session creation dates and times. |
The auth set_attribute
command changes the attributes dictionary key
to the value
entered for the currently logged-in user.
Do Not Use this command.
The auth terminate_other_sessions
ends all system websocket sessions except the currently logged-in user if it is an SSH session.
auth terminate_other_sessions
does not require entering a property argument.
Enter the command then press Enter.
The command terminates all websocket sessions, except if the current user is in an SSH session. When complete, the web UI sign-in splash screen displays.
The auth terminate_session
ends a system websocket session matching the ID entered.
Use auth sessions
to obtain session IDs, and again after terminating a session to verify the session ended.
auth terminate_session
has one required property, id
.
id
is the system-assigned identification for a websocket session found in the output of the auth sessions
command.
Enter the property argument using the =
delimiter to separate the property and double-quoted value.
Enter the command string then press Enter.
The command returns <null>
if successful.
The auth two-factor_auth
command validates if two-factor authentication is configured for the user entered.
auth two-factor_auth
has two required properties, username
and password
.
Enter property arguments using the =
delimiter to separate property and value. Double-quote values with spaces or special characters.
Enter the command string, then press Enter.
The command returns true
if two-factor authentication is enabled, false
if not enabled.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
api_key commands are based on API key creation and management functions found in the SCALE API and web UI. Use to create new API keys, delete or update existing keys, and locate information on one or all keys added to the system.
Enter auth api_key ls
to view the list of available commands.
Commands | Description |
---|---|
auth api_key create | Creates an API key. |
auth api_key delete | Deletes the API key matching the ID entered. |
auth api_key get_instance | Provides API key information for the ID entered. |
auth api_key query | Provides information on all API keys configured in the system. |
auth api_key update | Updates the API key matching the ID entered. |
The auth api_key create
command allows you create simple or complex API keys.
auth api_key create
has one required property, name
, and one optional property allowlist
.
See api_key create Properties below for details.
Enter the command string then press Enter. The command returns the API key when successful.
Always back up and secure keys. The key string displays only one time, at creation!
Property | Required | Description | Syntax Example |
---|---|---|---|
name | Yes | Enter a user-readable name for the API key using alphanumeric characters with or without the underscore _ . Enter the property argument using the = to separate property and value. Double-quote values with spaces or special characters. | name=mykey |
allowlist | No | Use to enter the HTTP method and WebSocket API authorized to use the API key. Enter the required resource permitted to use this key. Append /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources. Enter the HTTP method as a string using any of these values:GET to retrieve information about the API resource.POST to create an API resource.PUT to update an API resource.DELETE to delete the API resource.CALL ,orSUBSCRIBE {} within square brackets [] . Enter property aguments using the = to separate double-quoted property and values. Separate each propery argument with a comma and space. | allowlist=[{“method”="SUBSCRIBE", [“resource”="certificate.query"}] |
The auth api_key delete
command deletes the API key matching the key ID entered.
Use the auth api_key query
command to obtain a list of ID numbers for API keys on the system and again after deleting an API key to verify it is removed.
auth api_key delete
has one required property, id
.
id
is the system-assigned ID number for the API key found in the auth api_key query
command output.
Enter the property argument using the =
delimiter to separate the property and value.
Enter the command string then press Enter.
The command returns nothing when successful.
The auth api_key get_instance
command returns API key properties for the specified ID.
auth api_key get_instance
has one required property, id
.
id
is the system-assigned ID number for the API key found in the auth api_key query
command output.
Enter the property argument using the =
delimiter to separate the property and value.
Enter the command then press Enter.
The command returns a table with the ID, name, creation date and time, and an allow list for the specified API key.
The auth api_key query
command returns a table of properties for all API keys.
Use to locate the system-assigned ID number required in the auth api_key delete
, auth api_key get_instance
and auth api_key update
commands.
auth api_key query
does not require entering property arguments.
Enter the command then press Enter.
The command returns a table with the ID, name, creation date and time, and an allow list for all API keys.
The auth api_key update
command allows you to change or reset existing API keys.
Use the auth api_key query
command to obtain API key ID numbers, and after making changes to verify the changes are applied.
auth api_key update
has one required property, id
, and three configurable properties.
Enter the id
of the API key, then include at least one of the properties.
See api_key update Properties below for details.
Enter the command string then press Enter.
Or enter --
after id
to open the interactive argument editor.
The command returns an empty line.
Property | Description | Syntax Example |
---|---|---|
name | Enter a user-readable name for the API key using alphanumeric characters with or without the underscore _ . Enter the property argument using the = to separate property and value. Double-quote values with spaces or special characters. | name=mykey |
allowlist | Use to enter the HTTP method and WebSocket API authorized to use the API key. Enter the required resource permitted to use this key. Append /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources. Enter the HTTP method as a string using any of these values:GET to retrieve information about the API resource.POST to create an API resource.PUT to update an API resource.DELETE to delete the API resource.CALL ,orSUBSCRIBE {} within square brackets [] . Enter property aguments using the = to separate double-quoted property and values. Separate each propery argument with a comma and space. | allowlist=[{“method”="SUBSCRIBE", [“resource”="certificate.query"}] |
reset | Enter true to remove the existing key and generate a new one. | reset=true or reset=false |
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
auth two_factor commands are based on authentiation functions found in the SCALE API and web UI. Use to set up user two-factor authentication and view status for the user.
Enter auth ls
to view the list of available commands and namespaces.
Commands | Description |
---|---|
auth two_factor config | Displays current 2FA settings for the currently logged-in user. |
auth two_factor update | Updates two-factor authentication settings for the ID entered. |
The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.
Optional properties, indicated by the #
symbol, are disabled by default.
Required properties are enabled.
Do not disable properties that are enabled by default.
To configure required properties, enter a space after the colon then add the value.
To enable optional properties, delete #
from the corresponding line.
Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.
Press F2 or click Save to save the modified file.
Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.
The auth two_factor config
displays current 2FA settings for the currently logged-in user.
auth two_factor config
does not require entering properties or arguments.
Enter the command, then press Enter. The command returns a table with two-factor authentication properties for the currently logged-in user.
Property | Description |
---|---|
id | Displays the system-assigned ID number for the currently logged-in user. |
otp_digits | Displays the length (number of digits) allowed for a one-time password. |
secret | Displays <null> . |
window | Displays the number of passwords before and after the current remain valid for the currently logged-in user. |
interval | Displays the lifespan of a one-time password for the currently logged-in user. |
services | Displays <dict> . At present, viewing the contents of a dictionary is not available in the SCALE CLI. |
enabled | Displays true if two factor authentication is enabled for the currently logged-in user, or false if not configured or disabled. |
The auth two_factor update
command changes 2FA settings.
auth two_factor update
has five property arguments. Enter at least one property arguments.
See two_factor update Properties for details.
Enter the command string then press Enter. The command returns nothing when successful.
Property | Description | Syntax Example |
---|---|---|
enabled | Enter true to enable two_factor authentication for the currently logged-in user, or false to disable 2fa. | enabled=true or enabled=false |
otp_digits | Enter a number from six to eight to set the length of a one-time password. | otp_digits=6 |
window | Enter a number of passwords before and after the current remain valid. This extends the validity of one-time passwords. | window=2 |
interval | Enter a number to set the lifespan of a one-time password. | interval=30 |
services | Enter the true to enable or `false to disable 2FA for SSH logins. | services={“ssh”:true/false |
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The directory_service namespace has two commands and four child namespaces and is based on functions found in the SCALE API and web UI. It provides access to directory service methods. The four child namespaces have their own commands.
You can enter commands from the main CLI prompt or from the directory_service namespace prompt.
The cache_refresh
command refreshes the directory services cache for users and groups.
The user query
and group query
commands use this cache.
The first cache file in an Active Directory domain might take a significant amount of time to complete, so it is performed within a job.
Refresh the cache after adding new users or groups to a remote directory server to have the users or groups appear in the results.
A cache refresh is not required to use newly-added users and groups for permissions and ACL related methods.
It also does not resolve issues with users that cannot authenticate to shares.
The get_state
command displays the current status of the directory service.
The following articles provide information on directory_service child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The filesystem namespace has one child namespace and is based on functions found in the SCALE API and web UI. It provides access to ACL or permission methods through the child namespace and its command.
You can enter commands from the main CLI prompt or from the filesystem namespace prompts.
The following articles provide information on filesystem child namespace:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The acltemplate
namespace provides the ability to find existing ACL templates, create new or update exiting templates, or delete a template.
The web UI refers to ACL templates as presets.
This namesapce does not assign ACL permissions to a dataset.
The storage
namespace provides access to commands to assign dataset permissions.
The acltemplate namespace has six commands and is based on functions found in the SCALE API and web UI. It provides access to filesystem methods to list, create, edit, or delete ACL templates using the acltemplate commands.
You can enter commands from the main CLI prompt or from the filesystem acltemplate namespace prompt.
The by_path
command retrieves a list of available ACL templates for a given path.
The create
command creates a filesystem ACL template.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The delete
command deleted a filesystem acl template from the system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_instance
command returns the instance matching the value of the ID number of the ACL template or the query-options-get_instance value specified.
The query
command returns a list of filesystem ACL templates.
The update
command updates the filesystem ACL template for the id
included in the command.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
network commands are based on network functions found in the SCALE API and web UI. Use these commands to create and manage global network setting, interfaces, static routes, and IPMI connections.
Enter commands from the main CLI prompt or from the network
namespace prompt.
Enter
network ls
to view the list of available commands and namespaces.
The
network configuration config
command displays the current system configuration network settings.
network configuration config
does not require entering a property argument.
Enter the command then press Enter. The command returns a list of network configuration settings including the system-assigned id, hostname, domain, IPv4 and IPv6 gateways, nameservers 1-3, HTTP proxy, hosts, domains, service announcement, activity, local hostname and state.
Use the
network configuration update
command to change global network configuration settings.
network configuration update
has 14 properties you can change. See Update Properties below for details.
Enter the command string then press Enter or enter
--
to open the interactive command editor if changing multiple property values.
The command returns an empty line. Use
network configuration config
to verify any changes made.
Enter property arguments using the =
delimiter to separate property and value. Double-quote values that include special characters. For example:
Enter property arguments enclosed in curly brackets {}
with double-quoted properties and values separated by the :
delimiter. Separated multiple property arguments with a comma.
Property | Description | Syntax Example |
---|---|---|
hostname | Enter the hostname for the TrueNAS SCALE system. Default hostname is truenas . | hostname="hostName" |
domain | Enter the domain for the TrueNAS system. For example, mycompany.com. | domain="domainName" |
ipv4gateway | Enter the IP address to use instead of the DHCP-provided IP address, if DHCP is enabled. Entering an IP address overrides the default gateway provided by DHCP. | ipv4gateway="IPaddress" |
ipv6gateway | Enter the IP address to use instead of the DHCP-provided IP address, if DHCP is enabled on and IPV6 network. Entering an IP address overrides the default gateway provided by DHCP. | ipv6gateway="IPaddress" |
nameserver1 | Enter the IP address of the primary DNS server. | nameserver1="IPaddress" |
nameserver2 | Enter the IP address of the secondary DNS server. | nameserver2="IPaddress" |
nameserver3 | Enter the IP address for the third DNS server. | nameserver3="IPaddress" |
httpproxy | Required if using a proxy for network operations. | httpproxy="proxyName" |
hosts | Enter the host IP(s) as the value for the host property argument. Enter the property argument inside the [] , with each host IP address separated by a comma. | hosts="HostName" |
hostname_b | Used in HA-licensed systems to enter the IP address or host name for controller 2. | hostname_b="HostName" |
hostname_virtual | Used in HA-licensed systems as the virtual IP address or host name for access to the web UI regardless of which controller is active. | hostname_virtual="HostName" |
The
network dns query
command displays a table listing the current DNS nameserver IP addresses configured on the system.
network dns query
does not require entering a property argument.
Enter the commmand then press Enter. The command returns the current DNS nameserver IP addresses configured on the system.
The
network general summary
command lists network default routes and nameserver IP addresses.
network general summary
does not require entering property arguments.
Enter the command then press Enter. The command returns a table with default routes, nameserver IP addresses, and a dictionary for IPs configured on the system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The
network ipmi channels
command displays a list of available IPMI channels.
network ipmi channels
does not require entering property arguments.
Enter the command, then press Enter. The command returns the number of IPMI channels the system has available.
The
network ipmi get_instance
command displays the settings for the IPMI channel ID entered.
Use the
network ipmi query
command to obtain the channel ID.
network ipmi get_instance
has one required property, id
.
id
is the system-assinged number for an IPMI channel found in the output of the
network ipmi query
command.
Enter the command string, then press Enter. The command returns a table with the specified IPMI channel settings, including the IP address type, IP address, MAC address, subnet mask, gateway IP address, gateway MAC address, backup gateway IP, address, backup gateway MAC address, VLAN ID, VLAN ID status, and VLAN ID priority.
The
network ipmi query
command displays a table of all IPMI channels and their settings.
network ipmi query
does not require entering properties or arguments.
Enter the command, then press Enter. The command returns a table of all IPMI instances and their settings, including IP addresses type, IP addresses, MAC addresses, subnet masks, gateway IP addresses, gateway MAC addresses, backup gateway IP addresses, backup gateway MAC addresses, VLAN IDs, VLAN ID statuses, and VLAN ID priorities.
The
network ipmi update
command allows you to update the settings for a specified IPMI instance.
Use the
network ipmi query
command to obtain the system-assigned channel ID, and to verify changes made.
network ipmi update
has one required property, channel
, and six configuration properties. See Update Properties below for details.
channel
is the ID number assigned to a network channel found in output of the
network ipmi query
command.
Enter the command string then press Enter. The command returns a blank line.
Property | Description | Syntax Example |
---|---|---|
ipaddress | Enter the IPv4 address to assign to the channel. | ipaddress="ipaddress" |
netmask | Enter the subnet mask associated with the IP address. | netmask="expandednetmask"/i>" |
gateway | Enter the IPv4 address the IPMI ipaddress uses to reach outside the local subnet. | gateway="gateway" |
password | Enter a password to assign to the channel. The password must be between 8 and 16 characters and contain at least 3 of the following categories: lowercase character, uppercase character, digits 0-9, special characters (!, $, #, %, etc.) | password=password |
dhcp | Enter false to define ipaddress , netmask , and gateway . | dhcp=true/false |
vlan | Enter a numeric VLAN ID. | vlan=integer |
The
network route ipv4gw_reachable
verifies the ipv4 gateway is reachable by an interface.
Use the
network route static_routes
command to locate the gateway (ipv4 gateway) configured on the system.
network route ipv4gw_reachable
has one required property, ipv4_gateway
.
ipv4_gateway
is the IP address for the ipv4 gateway.
Enter the property argument using the =
delimiter to separate property and double-quoted value.
Enter the command string then press Enter.
The command returns true if the gateway is reachable, false if not.
The
network route system_routes
command lists network default routes and nameserver IP addresses.
network route system_routes
does not require entering property arguments.
Enter the command then press Enter. The command returns a table with network, netmask, gatewaty, and preferred source IP addresses, interface type, the table ID and scope. It returns a dictionary for flags configured on the system.
The
network static_route create
command adds a single static route IP address and gateway to the system.
network static_route create
has three required properties, destination
, gateway
, and description
.
See network static_route create Properties below for details.
Enter the property arguments using the =
delimiter to separate property and value. Double-quote values with special characters.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query
command to verify creation of the static route.
Property | Required | Description | Syntax Example |
---|---|---|---|
destination | Yes | Enter the IP address in the format a.b.c.d/e for the static route you want to create. | destination="a.b.c.d/e" |
gateway | Yes | Enter the IP address for the gateway for the destination IP address in the format a.b.c.d. | gateway="a.b.c.d" |
description | No | Enter optional text to describe the static route. | description="test" |
The
network static_route delete
command deletes the static route matching the ID entered.
network static_route delete
has one required property, id
.
id
is the system-assigned ID for the static route found in the output of the
network static_route query
command.
Enter the property argument using the =
delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query
command to verify deletion of the static route.
The
network static_route query
command lists details on static routes added to the system.
network static_route query
does not require entering a property argument, but you can enter any one of the three properties as a flag to narrow the information returned to list just that property for all static routes.
Properties are id
, destination
, gateway
, and description
.
Enter the command then press Enter. The command returns the values for all static routes configured on the system.
Use the
network static_route update
command to change the properties of the static route matching the ID entered.
network static_route update
has one required property, id
, and three optional properties.
id
is the system-assigned ID for the static route found in the output of the
network static_route query
command.
See Update Properties below for details.
Enter the property arguments using the =
delimiter to separate property and value. Double-quote values with special characters.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query
command to verify updates to the static route.
Property | Description | Syntax Example |
---|---|---|
destination | Enter the IP address in the format a.b.c.d/e for the static route you want to create. | destination="a.b.c.d/e" |
gateway | Enter the IP address for the gateway for the destination IP address in the format a.b.c.d. | gateway="a.b.c.d" |
description | Enter optional text to describe the static route. | description="test" |
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The service namespace has 10 commands and 12 child namespaces and is based on functions found in the SCALE API and web UI. It provides access to service configuration and validation methods for the 10 service commands. The 12 child namespaces have their own commands.
You can enter commands from the main CLI prompt or from the service namespace prompt.
The get_instance
command displays the id, name, and status of a service.
The query
command displays a simple overview of all services.
The reload
command reloads a specified service.
The restart
command restarts a specified service.
The start
command restarts a specified service.
The started
command verifies whether a start
command succeeded for a specified service.
The started_or_enabled
command displays whether a service starts automatically upon reboot or is running.
The stop
command stops a specified service.
The terminate_process
command forces a service to stop and disables it.
The update
command updates the service specified and lets you decide whether or not you want a service to start automatically upon system reboot.
The following articles provide information on service child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The ipmi namespace has four commands and is based on IPMI management functions found in the SCALE API and web UI. It provides access to ipmi service management methods through the ipmi commands.
The following ipmi commands allow you to view and edit ipmi service properties.
You can enter commands from the main CLI prompt or from the ipmi namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The chassis
command allows you to toggle IPMI identify light and view IPMI service settings.
The mc
command allows you to view information on your management controller (MC).
The sel
command manages the IPMI System Event Log (SEL).
The sensors
command allows you to view IPMI sensor data.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The ups namespace has three commands and is based on UPS service functions found in the SCALE API and web UI. It provides access to UPS management methods through the ups commands.
The following ups commands allow you to view and edit UPS properties.
You can enter commands from the main CLI prompt or from the UPS namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The config
command returns a table with current UPS settings.
The driver_choices
command returns choices of UPS drivers supported by the system.
The port_choices
command returns choices of UPS ports available on the system.
The update
command allows you to update UPS service settings.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The smart namespace has two commands and is based on S.M.A.R.T. service functions found in the SCALE API and web UI. It provides access to S.M.A.R.T. service management methods through the smart commands.
The following smart commands allow you to view and edit smart properties.
You can enter commands from the main CLI prompt or from the smart namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The config
command returns a table with current UPS settings.
The update
command allows you to update S.M.A.R.T. service settings.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The sharing namespace has three child namespaces and is based on functions found in the SCALE API and web UI. It provides access to configure shares through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the sharing namespace prompts.
The following articles provide information on sharing child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The nfs namespace has five command(s), and is based on share creation and management functions found in the SCALE API and web UI. It provides access to NFS share methods through the nfs commands.
The following nfs commands allow you to create new shares, manage existing shares, get information on NFS shares on the system
You can enter commands from the main CLI prompt or from the sharing namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The create
command adds a new NFS share.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
The delete
command deletes an NFS share.
The get_instance
command retrieves information for an NFS share matching the id
entered in the command string.
Use to verify properties for the configured share.
The query
command returns a table (dictionary) of all NFS shares on the system.
Use to locate the share ID number and other configuration information.
The update
command returns a table (dictionary) of all NFS shares on the system.
Use to locate the share ID number and other configuration information.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The storage namespace has nine child namespaces and is based on functions found in the SCALE API and web UI. It provides access to storage configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the storage namespace prompts.
The following articles provide information on storage child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The dataset namespace has one namespace, user_prop and 22 commands, and is based on dataset creation and management functions found in the SCALE API and web UI. It provides access to storage dataset methods through the dataset commands. Do not use the user_prop commands.
The following dataset commands allow you to create new and manage existing datasets.
You can enter commands from the main CLI prompt or from the dataset namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The attachments
command lists services dependent on the dataset matching the ID entered.
Use the storage dataset query
or storage dataset details
command to obtain dataset IDs.
Use the change_key
command to change the encryption key properties for the dataset matching the ID entered.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The checksum_choices
command lists checksums supported for the ZFS dataset.
The compression_choices
command lists compression alogrithms supported by ZFS.
Use the Create
command to create datasets or zvols.
Use the delete
command to delete a dataset or zvol matching the ID entered.
Use the destroy_snapshots
command to destroy snapshots for the dataset matching the ID entered.
Use the storage snapshot query
command to obtain a list of snapshots on the system.
If the system is performing a snapshot task for the dataset specified, the command returns an error stating the dataset is busy.
Use the details
command to list all datasets on the system and the services or tasks that might be consuming them.
Use the encryption_alogorithm_choices
command to list encryption alogrithms supported by ZFS.
Use the encryption_summary
command to retrieve a summary of all encrypted root datasets under the entered ID.
Use the export_key
command to export the encryption key for the dataset matching the ID entered.
Use with storage dataset encryption_summary
to identify dataset encryption types for datasets on the system.
Use the export_keys
command to export keys for the ID entered and all children of it stored in the system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the get_instance
command to list detials for the dataset matching the ID entered.
Use the get_quota
command to return a list of the specified quota_type of quotas on the ZFS dataset ds
.
The inherit_parent_encryption_properties
command allows inheriting parent dataset encryption root disregarding the current encryption settings.
Use only when the specified dataset ID is an encrypted parent and ID itself is an encryption root (parent to encrypted child datasets).
Use the lock
command to lock the dataset matching the ID entered.
Only works with datasets using passphrase encryption. Datasets with key encryption return an error.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the mountpoint
command to obtain the mountpoint for the dataset matching the ID entered.
Use the permission
command to set the owner and group, and other dataset permission options (i.e., recursive, traverse, etc.) for the dataset matching the ID entered.
The permissions
command is complex. Use either the UI Edit ACL screen or the the interactive arguments editor/text user interface (TUI) to configure ACL permissions.
Use the processes
command lists the processes using the dataset matching the ID entered.
Use the promote
command to promote a the cloned dataset matching the ID entered.
Use the storage snapshot query
command to list snapshots on the system.
Use the query
command to list all configured datasets, enter storage dataset query
.
Information provided includes id (name), type, name, pool encryption settings, child datasets, comments, ACL mode and type, checksum, compression settings, quota settings, and other settings found on the Dataset add and edit screens in the UI.
To include the services consuming the dataset use the storage dataset details
command.
The recommended_zvol_blocksize
command is a helper method to get recommended size for a new zvol (dataset of type VOLUME).
Use when creating a zvol using the storage dataset create
command volblocksize
property argument to enter a blocksize.
The recordsize_choices
command lists record size options to use with the
Use the set_quota
command to set quotas for the dataset matching the identifier specified.
There are three over-arching types of quotas for ZFS datasets:
DATASET
quota type, then the command acts as a wrapper for pool.dataset.update.This command allows users to set multiple quotas simultaneously by submitting a list of quotas. The list can contain all supported quota types.
Use the account user query
command or the UI to obtain the UID for the user entered into the command string.
The snapshot_count
command lists the snapshot count for the dataset matching the name entered.
Use the unlock
command to unlock the dataset or zvol matching the ID entered.
This command only works with datasets locked with a password.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the unlock_services_restart_choices
command to get mapping of services identifiers and labels that can be restarted on dataset unlock.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the update
command to update settings for the dataset or zvol matching the ID entered.
The disk namespace has 12 commands and is based on disk management functions found in the SCALE API and web UI. It provides access to disk management methods through the disk commands.
The following disk commands allow you to view and edit disk properties.
You can enter commands from the main CLI prompt or from the disk namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The get_instance
command returns all the settings for a specified disk.
Use the query
command to locate the identification number for system disks.
The get_unused
command returns disks that are not in use by any zpool. It also returns disks used by any exported zpool.
You can add the optional join_partitions
property argument to list disk partitions as well.
The query
command displays information about all disks on the system.
The resize
command allows you to resize disks to a specific size in gigabytes.
Use the query
command to locate the name for system disks.
The retaste
command forces the system to re-read specified disks and update their data.
Use the query
command to locate the identification number for system disks.
The smart_attributes
command returns S.M.A.R.T. attributes values for specified disk.
Use the query
command to locate the identification number for system disks.
Only devices with the ATA bus type support S.M.A.R.T. attributes.
The temperature
command returns the temperature of a specified disk.
Use the query
command to locate the identification number for system disks.
The temperature_agg
command returns min/max/avg temperature for specified disks for a set amount of previous days.
Use the query
command to locate the identification number for system disks.
The temperature_alerts
command returns existing temperature alerts for specified disks.
Use the query
command to locate the identification number for system disks.
The temperatures
command returns temperatures for a list of specified disks and allows you to set the S.M.A.R.T. powermode
.
Use the query
command to locate the identification number for system disks.
The update
command allows you to update settings for a specified disk.
The wipe
command wipes a specified disk using various wipe modes.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The enclosure namespace has four commands and is based on functions found in the SCALE API and web UI. It provides access to enclosure management methods through the four enclosure commands.
You can enter commands from the main CLI prompt or from the enclosure namespace prompt.
The get_instance
command displays the status of a specified enclosure.
The query
command lists all enclosures in the system.
The set_slot_status
command forces a drive slot into a specified state.
The update
command lets you change the label in a specified enclosure, use to set the drive slot status.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The pool namespace has 23 commands, and is based on pool creation and management functions found in the SCALE API and web UI. It provides access to storage pool methods through the pool commands.
The following pool commands allow you to create new pools and manage existing pools.
You can enter commands from the main CLI prompt or from the snapshot namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Use the attach
command to add disks to a VDev.
The target_vdev
is the GUID of the VDev (pool) where you need to attach the disk. A GUID is a random and unique 64-bit identifier for a pool, VDev, or disk.
If attaching to a stripe VDev (pool), this is the striped disk GUID that is converted to a mirror.
If attaching to a mirror VDev, the mirror is converted to an n-way mirror.
ZFS supports n-way mirroring. This means you can add disks into a mirror VDev. See TrueNAS ZFS Primer for more information.
Use theThis command only works with mirror and stripe VDevs. You cannot use this command if the pool is in a RAIDz configuration.
storage disk query
command to locate the zfs_guid number.
Use the disk ID with the storage disk get_instance
command to find the zfs_guid for a specific disk in a format easier to read.The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The attachments
command returns a list of services the pool matching the specified ID is using.
The create
command creates a new pool, specifies the type of VDev(s) and number of disks for each VDev in the pool.
This command performs the same functions as the Pool Creation Wizard in the UI.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The detach
command detaches a disk from the pool matching the ID entered. Removing a disk from a mirror pool changes the pool VDev to a stripe.
Use the storage disk query
command to locate the vdev_guid for the disk.
The expand
command increases the pool size to match all available disk space for the pool matching the ID specified. Pools using virtual disks use this option to resize the virtual disks apart from TrueNAS.
The export
command exports the pool/data for the pool matching the ID specified. Exporting a pool disables services, terminates any processes the pool uses, removes disks from the pool then cleans up after the export.
Use with the options
properties to completely destroy the pool and data, remove all attachments, and to restart any services associated with the pool.
Use without the options
property argument to just export the pool.
If using on an HA system with failover is enabled, and exporting/disconnecting the last zpool, then this raises an EOPNOTSUPP error. Failover must be disabled before exporting the last zpool on the system.
The filesystem_choices
command lists the dataset paths available on the system. Use the properties to modify the list to only include zvols (volumes) on the system.
The get_disks
command lists the disks found in the pool matching the ID entered, or if no ID is entered, all disks on the system.
The get_instance
command returns a table of properties for the pool matching the ID entered.
To view the same properties for all pools on the system use the query
command.
The get_instance_by_name
command returns a table of properties for the pool matching the name entered.
Use when you do not have the ID number required to use the get_instance
command.
To view properties for all pools on the system use the query
command.
The import_find
command returns a job id which can be used to retrieve a list of pools available for import. The command returns the name, guid, status, host name details.
The import
command uses information from the import_find
command output to import a pool.
The is_upgraded
command indicates if a pool is upgraded with new ZFS feature flags after upgrading SCALE to a new major release.
Use the storage pool query
command to obtain pool IDs.
Use the offline
command to take a disk in a pool, matching the ID entered, offline. This command uses the disk vdev_guid to identify the disk.
Use the storage disk query
command to locate the vdev_guid for the disk to offline.
Use the storage pool get_disks
command to identify the disks in the pool.
Use the online
command to bring a disk in a pool, matching the ID entered, online. This command uses the disk vdev_guid to identify the disk.
Use the storage disk query
command to locate the vdev_guid for the disk to offline.
Use the storage pool get_disks
command to identify the disks in the pool.
The processes
command lists processes used by the pool matching the ID entered.
The query
command returns a table (dictionary) of all pools on the system.
The remove
command removes the ZFS device from the pool matching the ID entered and wipes disks in the pool.
The replace
command removes a disk and replaces it with the disk matching the vdev_guid entered.
This command performs the same function as the disk replace UI function.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The scrub
command starts a scrub for the pool matching the ID entered.
This command performs the same function as running a pool data integrty check (scrub) operation.
The update
command updates properties for the pool matching the ID entered.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The upgrade
command upgrades the pool matching the ID entered with available ZFS feature flags. Use after updating SCALE to a new release or after importing a pool.
The validate_name
command validates the pool name entered.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The scrub namespace has 7 commands, and is based on data integrity check (scrub) functions found in the SCALE API and web UI. It provides access to scrub task management methods through the scrub namespace commands.
The following scrub namespace commands allow you to manage scheduled scrub task configuration and to start, pause, or stop a scrub.
You can enter commands from the main CLI prompt or from the storage namespace prompt.
The create
command configures a new scheduled scrub task.
The delete
command erases an existing scrub task.
The get_instance
command returns the current configuration for an existing scrub task.
The query
command returns information about all scheduled scrub tasks on the system.
The run
command activates a one-time scrub task for the selected pool.
The scrub
command allows you to start a one-time scrub task for the selected pool and to pause or stop an active scrub.
The update
command allows you to change the configuration of an existing scheduled scrub task.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The snapshot namespace has 10 commands, and is based on snapshot creation and management functions found in the SCALE API and web UI. It provides access to storage snapshot methods through the snapshot commands.
The following snapshot commands allow you to create new snapshots and manage existing snapshots.
You can enter commands from the main CLI prompt or from the snapshot namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The clone
command clones an existing snapshot to a new dataset.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The create
command takes a snapshot of a given dataset.
The delete
command deletes a snapshot matching the ID entered.
Use the query
command to locate the snapshot ID.
The get_instance
command retrieves information for a snapshot matching the id
entered in the command string.
Use to verify properties for the snapshot.
Use the query
command to find the list of snapshots and the ID for a snapshot.
The hold
command holds a snapshot matching the ID entered. Holding a snapshot prevents it from being deleted.
Use the query
command to locate the snapshot ID.
Use the release
command to unlock the snapshot to remove the hold on the snapshot.
The query
command returns a table (dictionary) of all snapshots on the system.
The release
command removes the hold on a snapshot allowing it to be deleted.
Use the query
command to locate the snapshot ID.
The remove
command removes a snapshot from a given dataset.
Use the query
command to locate the snapshot ID.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The rollback
command replaces data in the specified dataset with the information saved in the snapshot matching the ID entered.
Use the query
command to locate the snapshot ID.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The system namespace has 23 child namespaces and 19 commands, and is based on functions found in the SCALE API and web UI. It provides access to system configuration methods through the system namespace commands and the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The system namespace has 19 commands based on functions found in the SCALE API and web UI.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The boot_id
command returns a unique boot identifier consisting of lowercase aphanumeric characters and dashes.
The build_time
command returns the date and time of the software build installed and running on the system but not the release name and number.
Use the version
or version_short
commands to see the name and number assigned to the software build.
The debug
command downloads a system debug file to the home directory of the logged in admin user.
Specify the file name and extension for the debug file in the command string.
Debug files are usually .tgz files but you can use the extension of your choice.
Use a file transfer application such as WinSCP to connect to the system or a share (SMB, NFS, etc.) created on the system to access the file.
The environment
commands returns the environment in which the product is running.
The feature_enabled
command determines if the feature specified is running.
Use to determine if the deduplication, fibre channel or virtual machine (VM) feature is enabled or disabled.
The host_id
command retrieves a hex string that is generated based on the contents of the /etc/hostid file.
This is a permanent value that persists across reboots/upgrades and can be used as a unique identifier for the machine.
The info
command returns system information. Information includes:
The is_freenas
command is deprecated. Use product_type command. Applied to TrueNAS CORE systems.
The is_stable
command returns whether the system software version is stable.
This command is useful if upgrading from a nightly train of an unreleased version.
The license_update
command updates the license file.
This is the license added to the system on the System Settings > General screen on the Support widget.
The product_name
command returns the name of the product (TrueNAS) in use.
The product_type
command returns the name of the product (SCALE) in use.
The ready
command returns whether the system completed the boot process and is ready to use.
This command is similar to the state
command that provides the status of the system as READY or BOOTING.
The reboot
command reboots the system. It is the CLI equivalent to the UI power button option to restart the system.
The shutdown
command exits the UI and shuts down the system. It is the CLI equivalent to the UI power button option to shutdown the system.
The state
command returns the current system state as either booting, ready, or shutting down.
Use to determine the system state if uncertain of the current state. This command is similar to the ready
command that indicates if the system completed the boot process and is ready.
The version
command returns the system full software version name and number.
If uncertain of your SCALE release, enter this or the version_short
command to view the currently-installed version number.
The version_short
command returns the system software version number.
If uncertain of your SCALE release, enter this or the version
command to view the currently-installed version name.
The following articles provide information on system child namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The advanced namespace has six commands and is based on adding and managing system settings found in the SCALE API and web UI. It provides access to advanced system settings and functions through the advanced commands.
The following advanced commands allow you to add new and manage advanced system settings.
You can enter commands from the main CLI prompt or from the advanced namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The config
command lists current advanced settings for the system.
The sed_global_password
command provides the global password that applies for SED drives on the system.
The serial_port_choices
command lists current advanced settings for the system.
The syslog_certificate_authority_choices
command lists current certificate authority choices on the system.
The syslog_certificate_choices
command lists current certificate choices on the system.
Use the update
command to update advanced system settings.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use isolated_gpu_pci_ids
command to add the ID for a GPU PCI device.
Use the UI System > Advanced > Isolated GPU configuration screen to find and add the PCI ID detected by the system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The alert namespace has seven commands and is based on alert functions found in the SCALE API and web UI. It provides access to alert management methods through the alert commands.
The following alert commands allow you to view and manage alerts and policies.
You can enter commands from the main CLI prompt or from the alert namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The class
command allows you to view and update the default alert settings.
The dismiss
command dismisses alerts based on alert UUID.
The list
command lists all types of alerts including active and dismissed currently in the system.
The list_categories
command lists all types of alerts that the system can issue.
The list_policies
command lists all possible alert policies. Alert policies indicate the frequency of the alerts.
The restore
command dismisses alerts based on alert UUID.
The service
command allows you to view and modify alert services.
The service
command has seven options, but can only run one at a time. Alert service
command options are create
, delete
, get_instance
, list_types
, query
, test
, and update
.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The boot namespace has eight commands and is based on boot pool management functions found in the SCALE API and web UI. It provides access to system boot pool methods through the boot commands.
The following boot commands allow you to run jobs related to the boot pool and manage the boot pool.
You can enter commands from the main CLI prompt or from the boot namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The attach
command runs a job that attaches a device (disk) to the boot pool.
Before running this command, use these commands:
storage disk query
to locate the names and size of disks.storage disk get_unused
to locate unused disks on the system.system boot get_disks
to get the name of the boot pool disk.The detach
command runs a job that removes a device (disk) from the boot pool.
Use to remove additional boot devices.
Use system boot replace
to change the boot pool disk.
Before running this command, use system boot get_disks
to get the name(s) of the boot pool disk(s).
Use the get_disks
command to obtain the name(s) of the disk(s) in the boot pool.
Use the get_scrub_interval
command to obtain the number of days between boot pool scrubs.
The system advanced config
result also shows the boot_scrub
interval.
The get_state
command provides information on the boot pool.
Use the replace
command to remove a device (drive) from the boot pool and replace it with a device of at least the same size. This command resilvers the boot pool and installs the boot loader on the new device.
Before running this command, use these commands:
storage disk query
to locate the names and size of disks.storage disk get_unused
to locate unused disks on the system.system boot get_disks
to get the name of the boot pool disk.Use the scrub
command to initiate a manual boot pool scrub.
Use the set_scrub_interval
to set or change the interval (in days) between boot pool scrub operations.
You can also use the system advanced update boot_scrub=
command to set the boot pool scrub interval.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The bootenv namespace has 7 commands, and is based on boot environment functions found in the SCALE API and web UI. It provides access to environment management methods through the bootenv namespace commands.
The following bootenv namespace commands allow you to create or delete boot environments, manage existing environments, and activate an environment.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The activate
command sets a boot environment to activate on reboot.
The create
command adds a new boot environment.
The delete
command removes an existing boot environment from the system.
The get_instance
command returns configuration for an existing boot environment.
The query
command allows you to view all boot environments stored on the system.
It indicates the current active boot environment and which environment activates on system reboot.
The set_attribute
command is used to set the keep
flag, which determines whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.
The update
command allows you to change the name of an existing boot environment.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The config namespace has three commands and is based on configuration management functions found in the SCALE API and web UI. It provides access to configuration management methods through the config namespace commands.
The following config namespace commands allow you to save or upload system configuration files and to reset configuration to default. You can enter commands from the main CLI prompt or from the system namespace prompt.
The reset
command reverts the system database to default configuration values.
Download the current system configuration with save
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.
Thereset
command can result in unexpected behavior if entered via Shell in the web UI, especially ifreboot
is set to false. To avoid instability, only usereset
via a direct connection to the console or SSH.
TrueNAS Enterprise
The save
command creates a tar file of security-sensitive configuration information and saves it to the specified location.
The configuration file contains sensitive data like system passwords. Keep the configuration file safe and protect it from unauthorized access!
Do not use. Use the web UI to upload configuration files.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The device namespace has two commands. It provides access to device information through the device commands.
The following device commands allow you to view properties for devices in your system.
You can enter commands from the main CLI prompt or from the device namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The get_info
command returns details for a specified device type.
The gpu_pci_ids_choices
retrieves choices for GPU PCI IDs in the system.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
TrueNAS EnterpriseOn licensed systems, use the Failover namespace to manage HA system controllers and failover operations for Enterprise customer. Systems without an Enterprise license do not use this namespace.
The failover namespace has 14 commands and is based on failover functions found in the SCALE API and web UI. It provides access to Enterprise HA customer management methods through the failover namespace commands.
The following failover namespace commands allow you to perform failover operations for Enterprise customer systems.
You can enter commands from the main CLI prompt or from the failover namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The config
command displays failover configuration setting (ID, disabled status, timeout, and master/slave) information.
The control
command provides enabled/disabled status of failover control.
The disabled
command returns a list of reasons if the system failover is disabled.
The force_master
command forces the current controller to become master if it is the standby.
The get_ips
command returns a list of IP addresses configured for the failover service but not details on what they are assigned to.
The hardware
command returns the failover configuration information.
The in_progress
command provides verification of an in-progress failover event.
The licensed
command checks whether this system is licensed as an HA system.
The node
command returns the controller (node) status.
The status
command returns the current HA status as either master or slave.
The sync_from_peer
command sync failover configuration settings from the other controller.
This command is the same as the Sync From Peer function on the Failover Screen.
The sync_to_peer
command initiates a sync operation that copies over the primary controller configuration to the standby controller.
This command is the same as the Sync To Peer function on the Failover Screen.
The upgrade_pending
command verifies if HA upgrade is pending.
Use upgrade_finish
to finish the HA upgrade process if this command returns true.
The upgrade_finish
command perform the last stage of an HA upgrade and activates the new boot environment on the standby controller after it reboots.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The general namespace has 14 commands, and is based on general settings functions found in the SCALE API and web UI. It provides access to GUI and localization configuration settings through the general namespace commands.
The following general namespace commands allow you to configure time zone, language, HTTP protocol, UI address, and system certificate options. You can also restart the system through this namespace.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The checkin
command accepts pending settings.
The checkin_waiting
command determines whether the system is waiting for a checkin
to confirm pending changes.
The config
command returns current UI configuration.
The country_choices
command returns a list of available country options for use in creating certificates. See system certificate
for more information.
The kbdmap_choices
command returns a list of available keyboard map options.
The language_choices
command returns a list of available language translation options for the TrueNAS SCALE web UI.
The local_url
command returns the current local URL configuration for the TrueNAS SCALE web UI.
The timezone_choices
command returns a list of available timezone options for system localization.
The ui_address_choices
command returns IPv4 address options for the TrueNAS SCALE UI.
The ui_certificate_choices
command returns a list of certificates which can be used for configuring ui_certificate
(see update
properties).
The ui_httpsprotocols_choices
command returns a table of available HTTPS protocols for the TrueNAS SCALE web UI.
The ui_restart
command restarts the HTTP Server for the TrueNAS SCALE web UI.
This does not shut down and reboot the full system.
The ui_v6address_choices
command returns IPv6 address choices for the TrueNAS SCALE web UI.
The update
command allows users to configure UI and localization settings for the TrueNAS SCALE web UI.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The init_shutdown namespace has 5 commands, and is based on init/shutdown script functions found in the SCALE API and web UI. It provides access to init/shutdown script management methods through the init_shutdown namespace commands.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
Make sure you are comfortable with ZFS, Linux, and system configuration, backup, and restoration before creating and executing script tasks.
The following init_shutdown namespace commands allow you to create, view, update, and delete init/shutdown script tasks.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The create
command creates a new init/shutdown script task.
Init/shutdown scripts allow you to run scripted tasks before or after initialization (start-up), or at shutdown.
All init/shutdown scripts run using sh(1)
.
The delete
command removes an existing init/shutdown script task.
The get_instance
command returns configured settings for an existing init/shutdown script task.
The query
command returns information about all existing init/shutdown script tasks on the system.
The update
command modifies configured settings for an existing init/shutdown script task.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The keychain_credential namespace has nine commands and is based on SSH credential and keypair creation and management functions found in the SCALE API and web UI. It provides access to backup credential methods through the keychain_credential commands.
The following keychain_credential commands allow you to create new and manage existing SSH credentials and keypairs.
You can enter commands from the main CLI prompt or from the keychain_credential namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Use the create
command to create a keypair or SSH credential. This command is very complex. Use the UI or the interactive argument editor to create a new keypair or SSH connection.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The delete
command removes the keypair or SSH credential matching the ID entered.
Use the system keychain_credential query
to obtain ID numbers for keypairs or SSH credentials on the system and to verify the command is successful.
The generate_ssh_key_pair
command generates a new private and public key to use when creating SSH keypairs.
Use the UI to download public and private key values.
The get_instance
command lists the properties for the keypair or SSH connection ID entered.
The query
command lists all keypairs and connections configured on the system.
Use the remote_ssh_host_key_scan
to discover a remote system host key.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the remote_ssh_semiautomatic_setup
to perform a semi-automatic SSH connection setup with another system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the setup_ssh_connection
to create an SSH connection.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
Use the update
command to update properties for the credential matching the ID entered.
Use system keychain_credential query
to get a list of all credentials on the system and the assigned ID numbers.
The used_by
command lists the objects using this credential for the ID entered. For example, a replication task to a remote system.
The kmip namespace has six commands and is based on system KMIP server creation and management functions found in the SCALE API and web UI. It provides access to KMIP server methods through the kmip commands.
The following kmip commands allow you to create new and manage existing KMIP server connections.
You can enter commands from the main CLI prompt or from the kmip namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Use the clear_sync_pending_keys
command to clear any pending sync.
Use the config
command to retrieve the KMIP server settings if one is configured.
Use the kmip_sync_pending
command to verify if there is a pending sync.
Use the ssl_version_choices
command to retrieve valid SSL version choices you can use when configuring KMIP service.
Use the sync_keys
command to sync ZFS/SED keys between the KMIP server and TrueNAS SCALE database.
Use the update
command to update the KMIP server settings.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The mail namespace has three commands and is based on configuration management functions found in the SCALE API and web UI. It provides access to email configuration methods through the system namespace commands.
The following mail commands allow you to view or edit mail settings and to send an email using configured settings. You can enter commands from the main CLI prompt or from the system namespace prompt.
The config
command displays the current system email configuration.
The send
command sends an email from the system. A valid email send method must be configured before sending an email.
The update
command configures the system email send method using either SMTP or OAuth.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The ntp_server namespace has five commands and is based on NTP server management functions found in the SCALE API and web UI. It provides access to system ntp server methods through the ntp_server commands.
The following ntp-server commands allow you to run jobs related to adding and managing NTP servers.
You can enter commands from the main CLI prompt or from the ntp_server namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Use the create
command to add an NTP time server to the system and configure server properties.
The delete
command removes the NTP server matching the system-assigned id
.
Use the system ntp_server query
command to get the ID numbers for all NTP servers configured on the system.
The get_instance
command returns the system-assigned ID number, address, and settings for the id
entered.
Use the system ntp_server query
command to obtain the NTP server ID numbers.
The query
command lists the system-assigned ID number, address, and settings for all NTP servers configured on the system.
Use the update
command to change the settings for an existing NTP server.
Use the system ntp_server query
command to get the server ID.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The reporting namespace has 3 commands, and is based on system reporting functions found in the SCALE API and web UI. It provides access to reporting database configuration methods through the reporting namespace commands and the child namespaces and their commands.
To view reporting graphs, go to Reporting in the TrueNAS SCALE web UI.
The following reporting namespace commands allow you to configure the system reporting database.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The clear
command erases all existing data from the system reporting database.
The config
command returns the current system reporting configuration.
The update
command allows you to change system reporting configuration settings.
The support namespace has nine commands and is based on Proactive Support management functions found in the SCALE API and web UI. It provides access to system proactive support account settings and methods through the support commands.
The following support commands allow you to configure Proactive support account settings, create a new support ticket and attach files to an existing ticket.
You can enter commands from the main CLI prompt or from the support namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Use the attach_ticket
command to attach a file (debug, core, etc.) to an existing ticket.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The attach_ticket_max_size
command returns the maximum size of a file you can upload to a support ticket.
The config
command returns the current proactive support settings configured on the system. Use to locate the system-assigned ID, user name and title, contact information, and any secondary user name and contact information.
The fetch_categories
command provides the available support ticket categories (types).
The fields
command lists the proactive setting names.
The is_available
command returns whether proactive support is available for this system type and current license.
Use the is_available_and_enabled
command returns whether proactive support is available and enabled.
Use the new_ticket
command to create a new support ticket with or without a debug attached.
Use the update
command to change the settings for an existing proactive account.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The system_dataset namespace has 3 commands, and is based on system dataset storage functions found in the SCALE API and web UI. It provides access to storage configuration methods through the system_dataset namespace commands.
The following system_dataset namespace commands allow you to review and update the configured 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.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The config
command returns the current system dataset configuration.
The pool_choices
command allows you to view all available pools that can host the system dataset.
The update
command allows you to select a pool for the system dataset.
You can also use it to exclude a pool from being automatically selected, if a pool is not defined.
The truecommand namespace has three commands and is based on TrueCommand management functions found in the SCALE API and web UI. It provides access to system TrueCommand setting methods through the truecommand commands.
The following truecommand commands allow you to update or view current TrueCommand configuration settings, add an API key, or enable/disable the TrueCommand connection in SCALE.
You can enter commands from the main CLI prompt or from the truecommand namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The config
command returns a table with SCALE TrueCommand configuration settings.
The connected
command returns a table with SCALE TrueCommand connection settings and status.
The update
command allows you to update TrueCommand configuration.
Use auth api_key create
to obtain a new API key.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
TrueNAS EnterpriseOn licensed systems, use the truenas namespace for viewing or modifying Enterprise customer service details. Systems without an Enterprise license do not use this namespace.
The truenas namespace has five commands and is based on TrueNAS Enterprise functions found in the SCALE API and web UI. It provides access to Enterprise customer management methods through the truenas namespace commands.
The following truenas namespace commands allow you to accept the TrueNAS EULA, modify Enterprise customer information, and control system production status.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The accept_eula
command records agreement with the TrueNAS SCALE End User License Agreement (EULA).
Review the EULA before accepting it.
The get_customer_information
command returns a table of stored customer information.
The is_production
command returns if the system is marked as a production system.
The set_production
command adds or removes in-production status from the system and creates a ticket to notify iXsystems Support that the system is ready for use in production.
The update_customer_information
command modifies stored customer information.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The tunable namespace has six commands, and is based on tuned settings functions found in the SCALE API and web UI. It provides access to tunable configuration methods through the tunable namespace commands.
The following tunable namespace commands allow you to create and manage tuned settings. Tunables configure kernel parameters while the system is running. Configured settings generally take effect immediately.
You can enter commands from the main CLI prompt or from the system namespace prompt.
The create
command allows you to configure a new tunable.
The delete
command removes a configured tunable from the system.
The get_instance
command allows you to inspect the configuration of an existing tunable.
The query
command allows you to inspect all tuned settings on the system.
The tunable_type_choices
command allows you to view the available tunable types.
The update
command allows you to reconfigure an existing tuned setting.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The update
namespace allows users to locate pending updates or available trains and to update the TrueNAS SCALE release using the CLI.
The update namespace has 10 commands and is based on functions found in the SCALE API and web UI.
You can enter commands from the main CLI prompt or from the update namespace prompt.
Use the check_available
command to see if updates are available for the release train specified.
Use the get_trains
command to see the current and selected train dictionary for the system.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The download
command downloads the updates for the selected train.
The file
command updates the system using an uploaded file.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_auto_download
command returns the status of the auto download function is enabled.
The get_pending
command returns a table with a list of packages already downloaded and ready to apply.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_trains
command shows the available trains dictionary, the currently configured train and the train of the current boot environment on the system.
Use before entering the check_available
and set_train
commands.
The manual
command updates the system using a manual update file downloaded from the SCALE release train and uploaded to the system using a file transfer program.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
To perform a manual update via the TrueNAS CLI, you must first upload a manual update file onto the system.
Connect to your system with your choice of FTP program (such as WinSCP) and place the manual update file in /var/tmp/firmware.
After it finishes uploading, go to System Settings > Shell and enter cli
at the prompt if the system shell is set to a shell other than TrueNAS CLI for the admin user.
From the SCALE CLI, enter:
system update manual path=/var/tmp/firmware/updatefilename
Where updatefilename is the name of the update file.
The set_auto_download
command sets the update to auto-download update files.
The set_train
command sets an update train to use by default for updates. Use to change the current train to another available train.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The update
command downloads an update, if not already in the cache, and then applies it.
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The task namespace has six child namespaces and is based on functions found in the SCALE API and web UI. It provides access to task configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the task namespace prompts.
The following articles provide information on task child authentication namespaces:
The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
The cloud_sync namespace has one child namespace and is based on functions found in the SCALE API and web UI. It provides access to cloud_sync task configuration methods through the child namespace and commands.
You can enter commands from the main CLI prompt or from the cloud_sync namespace prompts.
The following articles provide information on cloud_sync child authentication namespaces:
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The snapshot namespace has 11 commands and is based on snapshot creation and management functions found in the SCALE API and web UI. It provides access to periodic snapshot task methods through the snapshot commands.
The following snapshot commands allow you to create new and manage existing periodic snapshot tasks.
You can enter commands from the main CLI prompt or from the task snapshot namespace prompt.
Enter the
--
flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
The create
command creates a periodic snapshot task for a given dataset at the specified schedule.
The delete
command deletes a snapshot task matching the ID entered.
Use the query
command to locate the snapshot task ID.
To disable a task but not delete it, use the update
command enable=false
property argument.
The delete_will_change_retention_for
command returns a list of snapshots that have their retention influenced by deleting a given snapshot.
Use this command before the delete
command to verify other snapshot tasks on the system that might be adversely affected.
The forseen_count
command returns a list of snapshots that change the retention of the periodic snapshot task for the ID specified.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The get_instance
command retrieves information for a snapshot task matching the id
entered in the command string.
Use to verify properties for the snapshot.
Use the query
command to find the list of snapshots and the ID for a snapshot task.
The max_count
command returns the maximum number of snapshots per dataset the system can sustain.
The max_total_count
command returns the maximum number of snapshots the system can sustain.
The query
command returns a table (dictionary) of all snapshot tasks on the system.
The run
command starts the snapshot task for the task ID entered.
Use the query
command to locate the snapshot task ID.
The update
command updates the task matching the task ID entered.
Use the query
command to find the list of snapshot tasks and the task ID.
Use the get_instance
command to list the properties of the task ID before and after making changes to verify the task configuration.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
The update_will_change_retention_for
command returns a list of snapshots that have their retention influenced by deleting a given snapshot.
The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.
You can access TrueNAS SCALE API documentation in the web interface by clicking account_circle > API Keys > API Docs.
Alternatively, append /api/docs/
to your TrueNAS host name or IP address in a browser to access the API documentation.
For convenience, we store static builds of the current 2.0 API documentation on the Docs Hub:
See the TrueNAS Security Hub to get the latest responses to TrueNAS SCALE-related security advisories.
Security Best Practices are available for both TrueNAS CORE and SCALE.