This section guides you through installing and accessing TrueNAS SCALE, storing, backing up, and sharing data, and expanding TrueNAS with different applications solutions.
For more detailed interface reference articles, configuration instructions, and tuning recommendations, see the remaining sections in this topic.
TrueNAS SCALE documentation is divided into several sections or books:
The Getting Started Guide provides the first steps for your experience with TrueNAS SCALE:
Software Licensing information.
Recommendations and considerations when selecting hardware.
Installation tutorials.
First-time software configuration instructions.
Configuration Tutorials have many community and iXsystems -provided procedural how-tos for specific software use-cases.
The UI Reference Guide describes each section of the SCALE web interface, including descriptions for each configuration option.
API Reference describes how to access the API documentation on a live system and includes a static copy of the API documentation.
SCALE Security Reports links to the TrueNAS Security Hub and also contains any additional security-related notices.
Ready to get started? Choose a topic or article from the left-side Navigation pane.
Click the < symbol to expand the menu to show the topics under this section.
1 - User Agreements
1.1 - TrueNAS SCALE EULA
TrueNAS SCALE End User License Agreement
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.0 Definitions
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.
2.0 License
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.
3.0 License Restrictions
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.0 General
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.
5.0 Export Control Regulations
“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).”
6.0 Data Collection and Privacy
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.
7.0 Limitation of Liability and Disclaimer of Warranty
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.
1.2 - Software Development Life Cycle
The TrueNAS Software Development Life Cycle (SDLC) is the process of planning, creating, testing, deploying, and maintaining TrueNAS releases.
Determine the objectives, nature, and scope of future versions of the software.
Requirement Analysis involves gathering feedback and interpreting customer needs and requirements, diagnosing existing problems, and weighing the pros and cons of potential solutions.
The end result is a list of recommended improvements to be integrated into future versions of TrueNAS.
Required and planned changes are investigated in detail and development steps are determined.
Proposed alterations are reviewed by peers for completeness, correctness, and proper coding style.
TrueNAS developers then begin altering the software to include new features, resolve software bugs, or implement security improvements.
Code is integrated into the existing TrueNAS source tree, then built and tested by the Release Engineering (RE) department.
RE verifies that all requirements and objectives are properly met and the updated software is reliable and fault-tolerant according to the determined requirements.
If issues are found, code is reworked to meet the development requirements.
Simultaneously, a security evaluation of the TrueNAS code is completed, with any discovered issues sent to the engineering team for resolution.
The Validation and Documentation Team audits all development changes to the software and resolves any inconsistencies with the current software documentation.
This is to verify that end user documentation is as accurate as possible.
Any security notices, errata, or best practices are also drafted for inclusion on the TrueNAS Security website.
The new release of TrueNAS is evaluated to determine further feature development, bug fixes, or security vulnerability patches.
During this stage, security patches and software erratum are corrected, updated versions of existing branches are pushed, and feedback is solicited for future versions of the software.
SDLC Application
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 Quality Lifecycle
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-case
Description
NIGHTLY
0
Developers
Incomplete
ALPHA
1
Testers
Not much field testing
BETA
2
Enthusiasts
Major Feature Complete, but expect some bugs
RC
3
Home Users
Suitable for non-critical deployments
RELEASE
4
General Use
Suitable for less complex deployments
U1
5
Business Use
Suitable for more complex deployments
U2+
6+
Mission Critical
Suitable for critical uptime deployments
1.3 - TrueNAS Data Collection Statement
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
2 - SCALE Hardware Guide
This article provides information on system hardware and system minimum requirements. Included information covers CPUs, storage considerations and solutions, media and controllers, device sizing and cooling, SAS expanders, and system memory.
From repurposed systems to highly-custom builds, the fundamental freedom of TrueNAS is the ability to run it on almost any x86 computer.
Minimum Hardware Requirements
The recommended system requirements to install TrueNAS:
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, operates jails, 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 for obvious reasons.
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 device, 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, read on!
Storage Considerations
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 very 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. It is highly configurable to achieve the perfect balance of redundancy and performance to meet any storage goal.
A properly-configured TrueNAS system can tolerate the failure of multiple storage devices and even recreate its boot media with a copy of the configuration file.
Storage Device Quantities
TrueNAS is capable of managing large quantities of storage devices as part of a single storage array.
The community-focused TrueNAS SCALE Angelfish release can manage as many as 400 drives in a single storage array; a significant level of flexibility for home users to larger business deployments.
With more Enterprise-level tuning in the mature 13.0 release and similar tuning in the upcoming SCALE Bluefin release, TrueNAS can expand even further and manage as many as 1,250 drives in a single storage array!
Storage Media
Choosing storage media is the first step in designing the storage system to meet immediate objectives and prepare for future capacity expansion.
Until the next scientific breakthrough in storage media, spinning hard disks are here to stay thanks to their balance of capacity and cost.
The arrival of double-digit terabyte consumer and enterprise drives provides more choices to TrueNAS users than ever.
TrueNAS Mini systems ship with Western Digital NAS and NL-SAS for good reason. Understanding the alternatives explains this decision.
Serial Advanced Technology Attachment (SATA) is still the de facto standard disk interface found in many desktop/laptop computers, servers, and some non-enterprise storage arrays.
SATA disks first arrived offering double-digit gigabyte capacities and are now produced to meet many capacity, reliability, and performance goals.
While consumer desktop SATA disks do not have the problematic overall reliability issues they once had, they are still not designed or warrantied for continuous operation or use in RAID groups.
Enterprise SATA disks address the always-on factor, vibration tolerance, and drive error handling required in storage systems. However, the price gap between desktop and enterprise SATA drives is vast enough that it forces users to push their consumer drives into 24/7 service to pursue cost savings.
Drive vendors, likely tired of honoring warranties for failed desktop drives used in incorrect applications, responded to this gap in the market by producing NAS drives. NAS drives achieved fame from the original Western Digital (WD) Red™ drives with CMR/PMR technology (now called WD Red Plus).
Western Digital Designed the WD Red™ Plus NAS drives (non-SMR) for systems with up to 8 hard drives, the WD Red™ Pro for systems with up to 16 drives, and the WD UltraStar™ for systems beyond 16 drives.
The iXsystems Community Forum regards WD drives as the preferred hard drives for TrueNAS builds due to their exceptional quality and reliability.
All TrueNAS Minis ship with WD Red™ Plus drives unless requested otherwise.
Nearline SAS (NL-SAS) disks are 7200 RPM enterprise SATA disks with the industry-standard SAS interface found in most enterprise storage systems.
SAS stands for Serial Attached SCSI, with the traditional SCSI disk interface in serial form.
SAS systems, designed for data center storage applications, have accurate, verbose error handling, predictable failure behavior, reliable hot swapping, and the added feature of multipath support.
Multipath access means that each drive has two interfaces and can connect to two storage controllers or one controller over two cables.
This redundancy protects against cable, controller card, or complete system failure in the case of the TrueNAS high-availability architecture in which each controller is an independent server that accesses the same set of NL-SAS drives.
NL-SAS drives are also robust enough to handle the rigors of systems with more than 16 disks.
So, capacity-oriented TrueNAS systems ship with Western Digital UltraStar NL-SAS disks thanks to the all-around perfect balance of capacity, reliability, performance, and flexibility that NL-SAS drives offer.
Enterprise SAS disks, built for the maximum performance and reliability that a spinning platter can provide, are the traditional heavy-lifters of the enterprise storage industry.
SAS disk capacities are low compared to NL-SAS or NAS drives due to the speed at which the platters spin, reaching as high as 15,000 RPMs.
While SAS drives may sound like the ultimate answer for high-performance storage, many consumer and enterprise flash-based options have come onto the market and significantly reduced the competitiveness of SAS drives.
For example, enterprise SAS drives discontinued from the TrueNAS product lines were almost completely replaced by flash drives (SSDs or NVMe) in 2016 due to their superior performance/cost ratio.
Flash storage technology has progressed significantly in recent years, leading to a revolution in mobile devices and the rise of flash storage in general-purpose PCs and servers.
Unlike hard disks, flash storage is not sensitive to vibration and can be much faster with comparable reliability.
Flash storage remains more expensive per gigabyte, but is becoming more common in TrueNAS systems as the price gap narrows.
The shortest path for introducing flash storage into the mainstream market was for vendors to use standard SATA/SAS hard disk interfaces and form factors that emulate standard hard disks but without moving parts.
For this reason, flash storage Solid State Disks (SSDs) have SATA interfaces and are the size of 2.5" laptop hard disks, allowing them to be drop-in replacements for traditional hard disks.
Flash storage SSDs can replace HDDs for primary storage on a TrueNAS system, resulting in a faster, though either a smaller or more expensive storage solution.
If you plan to go all-flash, buy the highest-quality flash storage SSDs your budget allows with a focus on power, safety, and write endurance that matches your expected write workload.
While SSDs pretending to be HDDs made sense for rapid adoption, the Non-Volatile Memory Express (NVMe) standard is a native flash protocol that takes full advantage of the flash storage non-linear, parallel nature.
The main advantage of NVMe is generally its low-latency performance, and it is becoming a mainstream option for boot and other tasks. At first, NVMe was limited to expansion-card form factors such as PCIe and M.2. The new U.2 interface offers a universal solution that includes the 2.5" drive form factor and an externally accessible (but generally not hot-swappable) NVMe interface.
Note: NVMe devices can run quite hot and may need dedicated heat sinks.
Manual S.M.A.R.T. tests on NVMe devices is currently not supported.
Avoid using USB-connected hard disks for primary storage with TrueNAS. You can use USB Hard Disks for very basic backups in a pinch.
While TrueNAS does not automate this process, you can connect a USB HDD, replicate at the command line, and then take it off-site for safekeeping.
Warning: USB-connected media (including SSDs) may report their serial numbers inaccurately, making them indistinguishable from each other.
These storage device media arrange together to create powerful storage solutions.
Storage Solutions
With hard disks providing double-digit terabyte capacities and flash-based options providing even higher performance, a best of both worlds option is available.
With TrueNAS and OpenZFS, you can merge both flash and disk to create hybrid storage that makes the most of both storage types.
Hybrid setups use high-capacity spinning disks to store data while DRAM and flash perform hyper-fast read and write caching.
The technologies work together with a flash-based separate write log (SLOG). Think of it as a write cache keeping the ZFS-intent log (ZIL) used to speed up writes.
On the read side, flash is a level two adaptive replacement (read) cache (L2ARC) to keep the hottest data sets on the faster flash media.
Workloads with synchronous writes such as NFS and databases benefit from SLOG devices, while workloads with frequently-accessed data might benefit from an L2ARC device.
An L2ARC device is not always the best choice because the level one ARC in RAM always provide a faster cache, and the L2ARC table uses some RAM.
SLOG devices do not need to be large, since they only need to service five seconds of data writes delivered by the network or a local application.
A high-endurance, low-latency device between 8 GB and 32 GB in size is adequate for most modern networks, and you can strip or mirror several devices for either performance or redundancy.
Pay attention to the published endurance claims for the device since a SLOG acts as the funnel point for most of the writes made to the system.
SLOG devices also need power protection.
The purpose of the ZFS intent log (ZIL), and thus the SLOG, is to keep sync writes safe during a crash or power failure.
If the SLOG is not power-protected and loses data after a power failure, it defeats the purpose of using a SLOG in the first place.
Check the manufacturer specifications for the device to ensure the SLOG device is power-safe or has power loss/failure protection.
The most important quality to look for in an L2ARC device is random read performance.
The device needs to support more IOPS than the primary storage media it caches.
For example, using a single SSD as an L2ARC is ineffective in front of a pool of 40 SSDs, as the 40 SSDs can handle far more IOPS than the single L2ARC drive.
As for capacity, 5x to 20x larger than RAM size is a good guideline.
High-end TrueNAS systems can have NVMe-based L2ARC in double-digit terabyte sizes.
Keep in mind that for every data block in the L2ARC, the primary ARC needs an 88-byte entry.
Poorly-designed systems can cause an unexpected fill-up in the ARC and reduce performance in a p.
For example, a 480 GB L2ARC filled with 4KiB blocks needs more than 10GiB of metadata storage in the primary ARC.
TrueNAS supports two forms of data encryption at rest to achieve privacy and compliance objectives: Native ZFS encryption and Self Encrypting Drives (SEDs).
SEDs do not experience the performance overhead introduced by software partition encryption but are not as readily available as non-SED drives (and thus can cost a little more).
Booting legacy FreeNAS systems from 8 GB or larger USB flash drives was once very popular.
We recommend looking at other options since USB drive quality varies widely and modern TrueNAS versions perform increased drive writes to the boot pool.
For this reason, all pre-built TrueNAS Systems ship with either M.2 drives or SATA DOMs.
SATA DOMs, or disk-on-modules, offer reliability close to that of consumer 2.5" SSDs with a smaller form factor that mounts to an internal SATA port and does not use a drive bay.
Because SATA DOMs and motherboards with m.2 slots are not as common as the other storage devices mentioned here, users often boot TrueNAS systems from 2.5" SSDs and HDDs (often mirrored for added redundancy).
The recommended size for the TrueNAS boot volume is 8 GB, but using 16 or 32 GB (or a 120 GB 2.5" SATA SSD) provides room for more boot environments.
TrueNAS systems come in all shapes and sizes.
Many users want to have external access to all storage devices for efficient replacement if issues occur.
Most hot-swap drive bays need a proprietary drive tray into which you install each drive.
These bay and tray combinations often include convenient features like activity and identification lights to visualize activity and illuminate a failed drive with sesutil(8) (https://www.freebsd.org/cgi/man.cgi?query=sesutil&sektion=8 for CORE, https://manpages.debian.org/testing/sg3-utils/sg3_utils.8.en.html for SCALE).
TrueNAS Mini systems ship with four or more hot-swap bays.
TrueNAS R-Series systems can support dozens of drives in their head units and external expansion shelves.
Pre-owned or repurposed hardware is popular among TrueNAS users.
Pay attention to the maximum performance offered by the hot-swap backplanes of a given system.
Aim for at least 6 Gbps SATA III support.
Note that hot-swapping PCIe NVMe devices is not currently supported.
Storage Device Sizing
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 drives should I use to achieve my desired capacity?
You can mirror two 16TB drives to achieve 16TB 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, at most, is that of a single drive.
By contrast, an array of eight 4TB 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.
Storage Device Burn-In
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, paying attention to:
Start a long HDD self-test (smartctl -t long /dev/), and after the test completes (could take 12+ hrs)
Check the results (smartctl -a /dev/)
Check pending sector reallocations (smartctl -a /dev/ | grep Current_Pending_Sector)
Check reallocated sector count (smartctl -a /dev/ | grep Reallocated_Sector_Ct)
Check the UDMA CRC errors (smartctl -a /dev/ | grep UDMA_CRC_Error_Count)
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 may not be honest or informed about their age and health.
Check the number of hours on all new drives using smartctl(8) to verify they are not recertified.
A drive vendor could also zero the hours of a drive during recertification, masking its true age.
iXsystems tests all storage devices it sells for at least 48 hours before shipment.
Storage Controllers
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 its rebranded siblings that also use 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 single 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:
Could mask disk serial number and S.M.A.R.T. health information
Could perform slower than their HBA equivalents
Could cause data loss if using a write cache with a dead battery backup unit (BBU))
SAS Expanders
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 would 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).
Note that the opposite is not true: you cannot use a SAS drive in a port designed for SATA drives.
Storage Device Cooling
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 the drives were tested 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 set to 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 8TB drives to run hotter than other drive capacities.
In general, try to keep drive temperatures below the drive specification provided by vendor.
Memory, CPU, and Network Considerations
Memory Sizing
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 key to maintaining peak performance.
You should have at least 8 GB of RAM for basic TrueNAS operations with up to eight drives. Other use cases each have distinct RAM requirements:
Add 1 GB for each drive added after eight to benefit most use cases.
Add extra RAM (in general) if more clients will connect to the TrueNAS system. A 20 TB pool backing lots of high-performance VMs over iSCSI might need more RAM than a 200 TB pool storing archival data. If using iSCSI to back VMs, plan to use at least 16 GB of RAM for reasonable performance and 32 GB or more for optimal performance.
Add 2 GB of RAM for directory services for the winbind internal cache.
Add more RAM as required for plugins and jails as each has specific application RAM requirements.
Add more RAM for virtual machines with a guest operating system and application RAM requirements.
Add the suggested 5 GB per TB of storage for deduplication that depends on an in-RAM deduplication table.
Add approximately 1 GB of RAM (conservative estimate) for every 50 GB of L2ARC in your pool. Attaching an L2ARC drive to a pool uses some RAM, too. ZFS needs metadata in ARC to know what data is in L2ARC.
Error Correcting Code Memory
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.
The lengthy, Internet-wide debate on whether to use error-correcting code (ECC) system memory with OpenZFS and TrueNAS summarizes as:
ECC RAM is strongly recommended as another data integrity defense
However:
Some CPUs or motherboards support ECC RAM but not all
Many TrueNAS systems operate every day without ECC RAM
RAM of any type or grade can fail and cause data loss
RAM is most likely to fail in the first three months so test all RAM before deployment.
Central Processing Unit (CPU) Selection
Choosing ECC RAM limits your CPU and motherboard options, but that can be a good thing.
Intel® makes a point of limiting ECC RAM support to their lowest and highest-end CPUs, cutting out the mid-range i5 and i7 models.
Which CPU to choose can come down to a short list of factors:
An underpowered CPU can create a performance bottleneck because of how OpenZFS does checksums, and compresses and (optional) encrypts data.
A higher-frequency CPU with fewer cores usually performs best for SMB only workloads because of Samba, the lightly-threaded TrueNAS SMB daemon.
A higher-core-count CPU is better suited for parallel encryption and virtualization.
A CPU with AES-NI encryption acceleration support improves the speed of the file system and network encryption.
A server-class CPU is recommended for its power and ECC memory support.
A Xeon E5 CPU (or similar) is recommended for software-encrypted pools.
An Intel Ivy Bridge CPU or later recommended for virtual machine use.
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 making a comeback 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 significant support, and TrueNAS SCALE should work with AMD CPUs without issue.
Remote Management: IPMI
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:
Remote power control and monitoring of remote systems
Remote console shell access for configuration or data recovery
Remote virtual media for TrueNAS installation or reinstallation
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 default to a single network interface, which can be challenging when you need to 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 even for system recovery.
The latest TrueNAS Mini and R-Series systems ship with full-featured, HTML5-based IPMI support on a dedicated gigabit network interface.
Power Supply Units
The top criteria to consider for a power supply unit (or PSU) on a TrueNAS system are its:
Power capacity (in watts) for the motherboard and number of drives it must support
Reliability
Efficiency rating
Relative noise
Optional redundancy to keep important systems running if one power supply fails
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 completely 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 power drawn from the wall is lost as heat, noise, and vibration, instead of doing useful work like 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 is operating 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.
Uninterruptible Power Supplies
TrueNAS provides the ability 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 UPSs, 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.
Ethernet Networking
The network in Network Attached Storage is as important as storage, but the topic reduces to a few key points:
Simplicity - Simplicity is often the secret to reliability with network configurations.
Individual interfaces - Faster individual interfaces such as 10/25/40/100GbE are preferable to aggregating slower interfaces.
Interface support - Intel and Chelsio interfaces are the best-supported options.
Packet fragmentation - Only consider a jumbo framesMTU with dedicated connections such as between servers or video editors and TrueNAS that are unlikely to experience packet fragmentation.
LRO/LSO offload features - Interfaces with LRO and LSO offload features generally alleviates the need for jumbo frames and their use can result in lower CPU overhead.
High-Speed Interconnects
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:
10Gb NICs: SFP+ connectors
25Gb NICs: SFP28 connectors
40Gb NICs: QSFP+ connectors
100Gb NICs: QSFP28 connectors
200Gb NICs: QSFP56 connectors
400Gb NICs: QSFP-DD connectors
iXsystems also recommends using optical fiber for any transceiver form factors mentioned when using fiber channels.
Direct attached copper (DAC) cables could create interoperability issues between the NIC, cable, and switch.
Virtualized TrueNAS CORE
Finally, the ultimate TrueNAS hardware question is whether to use actual hardware or choose a virtualization solution.
TrueNAS developers virtualize TrueNAS every day as part of their work, and cloud services are popular among users of all sizes.
At the heart of the TrueNAS design is OpenZFS. The design from day one works with physical storage devices. It is aware of their strengths and compensates for their weaknesses.
When the need arises to virtualize TrueNAS:
Pass hardware disks or the entire storage controller to the TrueNAS VM if possible (requires VT-d/AMD-Vi support).
Disable automatic scrub pools on virtualized storage such as VMFS, and never scrub a pool while also running storage repair tasks on another layer.
Use a least three vdevs to provide adequate metadata redundancy, even with a striped pool.
Provide one or more 8 GB or larger boot devices.
Provide the TrueNAS VM with adequate RAM per its usual requirements.
Consider jumbo frame networking if all devices support it.
Understand that the guest tools in FreeBSD might lack features found in other guest operating systems.
Enable MAC address spoofing on virtual interfaces and enable promiscuous mode to use VNET jail and plugins.
3 - Installation Instructions
This section provides instructions for users that are installing TrueNAS SCALE for the first time on their own system hardware and for users that need to do a clean install of SCALE.
The installation process covers installing SCALE using an iso, and then using the Console setup menu to configure their primary network interface. TrueNAS SCALE uses DHCP to provide the system IP address.
It also describes configuring the rest of the network settings, storage pools, data sharing and data storage backup solutions in the web UI. Finally, it covers backing up the system configuration to a file.
If you plan to use this TrueNAS SCALE system as part of a cluster, complete the configuration process and then save the system configuration file.
This article provides SCALE installation instructions for both physical hardware and virtual machines using an iso file. It also describes the iso verification process using and OpenPGP encryption application.
This article provides general information and instructions on setting up storage data backup solutions and saving the system configuration file in TrueNAS SCALE.
3.1 - Installing SCALE
This article provides SCALE installation instructions for both physical hardware and virtual machines using an iso file. It also describes the iso verification process using and OpenPGP encryption application.
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).
ISO Verification
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.
PGP ISO Verification
You need an OpenPGP encryption application for this method of ISO verification.
Obtain an OpenPGP encryption application to used.
There are many different free applications available, but the OpenPGP group provides a list of available software for different operating systems at https://www.openpgp.org/software/.
The examples in this section show verifying the TrueNAS .iso using gnupg2 in a command prompt, but Gpg4win is also a good option for Windows users.
To verify the .iso source, go to https://www.truenas.com/download-tn-scale/, expand the Security option,
and click PGP Signature to download the Gnu Privacy Guard signature file. This file may be a (.gpg) or a (.sig) file.
Open the PGP Public key link and note the address in your browser and Search results for string.
Use one of the OpenPGP encryption tools mentioned above to import the public key and verify the PGP signature.
Go to the .iso and the .iso.gpg or .iso.sig download location and import the public key using the keyserver address and search results string:
user@ubuntu /tmp> gpg --keyserver keys.gnupg.net --recv-keys 0xc8d62def767c1db0dff4e6ec358eaa9112cf7946
gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
gpg: key 358EAA9112CF7946: public key "IX SecTeam <security-officer@ixsystems.com>" imported
gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
gpg: Total number processed: 1
gpg: imported: 1
user@ubuntu /tmp>
Use gpg --verify to compare the .iso and the .iso.gpg or .iso.sig files:
user@ubuntu /tmp> gpg --verify TrueNAS-SCALE-21.04-ALPHA.1.iso
gpg: Signature made Thu May 27 10:49:02 2021 EDT using RSA key ID 12CF7946
gpg: Good signature from "IX SecTeam <security-officer@ixsystems.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: C8D6 2DEF 767C 1DB0 DFF4 E6EC 358E AA91 12CF 7946
user@ubuntu /tmp>
This response means the signature is correct but still untrusted.
Go back to the browser page that has the PGP Public key.
Open and manually confirm that the key is issued for IX SecTeam <security-officer@ixsystems.com> (iX Security Team) on October 15, 2019 and is signed by an iXsystems account.
SHA256 Verification
SHA256 verification uses the checksum to validate/verify the file.
The command to verify the checksum varies by operating system:
BSD use command sha256 isofile
Linux use command sha256sum isofile
Mac use command shasum -a 256 isofile
Windows or Mac users can install additional utilities like HashCalc or HashTab.
The value produced by running the command must match the value shown in the sha256.txt file.
Different checksum values indicate a corrupted installer file that you should not use.
Installing SCALE
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 for it to finish.
Installing on Physical Hardware
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.
Preparing the Install File
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.
To write the TrueNAS installer to a USB stick on Linux, plug the USB stick into the system and open a terminal.
Start by making sure the USB stick connection path is correct.
There are many ways to do this in Linux, but a quick option is to enter the command lsblk -po +vendor,model and note the path to the USB stick.
This shows in the NAME column of the lsblk output.
Next, use command dd to write the installer to the USB stick.
Be very careful when using dd, as choosing the wrong of= device path can result in irretrievable data loss!
Enter command dd status=progress if=path/to/.iso of=path/to/USB in the CLI.
If this results in a permission denied error, use command sudo dd with the same parameters and enter the administrator password.
Installing From the Device Media
Before you begin:
Locate the hotkey defined by the manufacturer of your motherboard to uses in this process.
Disable SecureBoot if your system supports it so or set it to Other OS so you can boot to the install media.
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 haven’t disable 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.
Which slots are available for boot differs by hardware.
Using the TrueNAS Installer Console Setup
After the system boots into the installer, follow these steps.
Select Install/Upgrade.
Select the desired install drive.
Select Yes.
Select Fresh Install to do a clean install of the downloaded version of TrueNAS SCALE.
This erases the contents of the selected drive!
When the operating system device has enough additional space, you can choose to allocate some space for a swap partition to improve performance.
Next, set a password for the TrueNAS administrative account.
SCALE has implemented rootless login. Create an admin account and password. The system retains root as a fallback but it is no longer the default.
This account has full control over TrueNAS and is used to log in to the web interface.
Set a strong password and protect it.
Next, enter a password for the new admin user.
After following the steps to install, reboot the system and remove the install media.
If the system does not boot into TrueNAS SCALE, there are several things you can check to resolve the situation:
Check the system BIOS and see if there is an option to change the USB emulation from CD/DVD/floppy to hard drive.
If it still does not boot, check to see if the card/drive is UDMA compliant.
Check to see if the system BIOS supports EFI with BIOS emulation, if not, see if it has an option to boot using legacy BIOS mode.
If the system starts to boot but hangs with this repeated error message: run_interrupt_driven_hooks: still waiting after 60 seconds for xpt_config,
go into the system BIOS and look for an onboard device configuration for a 1394 Controller. If present, disable that device and try booting again.
If the burned image fails to boot and the image was burned using a Windows system, wipe the USB stick before trying a second burn using a utility such as Active@ KillDisk.
Otherwise, the second burn attempt fails as Windows does not understand the partition that was written from the image file.
Be very careful to specify the correct USB stick when using a wipe utility!
Installing on a Virtual Machine
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.
Minimum Virtual Machine Settings
Regardless of virtualization application, use these minimum settings:
RAM: at least 8192MB (8GB)
DISKS: two virtual disks with at least 16GB, one for the operating system and boot environments and at least one additional virtual disk to use as data storage.
NETWORK: Use NAT, bridged, or host-only depending on your host network configuration.
Networking Checks for VMWare
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 plugins or jails 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.
Installing on a Generic Virtual Machine
For most hypervisors, the procedure for creating a TrueNAS VM is the same.
Create a new virtual machine as usual, taking note of the following settings.
The virtual hardware has a bootable CD/DVD device pointed to the TrueNAS SCALE installer image (this is usually an .iso).
The virtual network card configuration allows your network to reach it.
bridged mode is optimal as this treats the network card as one plugged into a simple switch on the existing network.
Some products require you identify the OS you plan to install on the VM. The ideal option is Debian 11 64 bit.
If this is not available, try options like Debian 11, Debian 64 bit, 64 bit OS, or Other. Do not choose a Windows, Mac or BSD related OS type!
For VMWare hypervisors, install in BIOS mode.
Ensure the VM has sufficient memory and disk space. For TrueNAS set to at least 8 GB RAM and 20 GB disk space.
Not all hypervisors allocate enough memory by default.
Boot the VM and install TrueNAS as usual.
When installation completes, shut down the VM instead of rebooting, and disconnect the CD/DVD from the VM before rebooting the VM.
After rebooting into TrueNAS, install VM tools if applicable for your VM, and if they exist for Debian 11, or ensure they loaded on boot.
Example VMWare Player 15.5 Installation
This example describes installing TrueNAS SCALE using VMWare Player 15.5.
Open VMware Player and click Create a New Virtual Machine to enter the New Virtual Machine Wizard.
Install disk image file.
Select the Installer disk image file (.iso) option, click Browse…, and upload the TrueNAS SCALE .iso downloaded earlier.
Name the virtual machine.
In this step, you can change the virtual machine name and location.
Specify the disk capacity.
Specify the maximum disk size for the initial disk.
The default 20GB is enough for TrueNAS.
Next, select Store virtual disk as a single file.
Review the virtual machine.
Review the virtual machine configuration before proceeding.
By default, VMware Player does not set enough RAM for the virtual machine.
Click Customize Hardware… > Memory.
Drag the slider up to 8GB and click Ok.
Power on the machine after creation if desired. Select Power on this virtual machine after creation.
Adding Virtual Disks
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.
After creating the virtual machine, select it from the virtual machine list and click Edit virtual machine settings.
Click Add… and select Hard Disk. Select SCSI as the virtual disk type.
Select Create a new virtual disk. Specify the maximum size of this additional virtual disk. This disk stores data in TrueNAS.
If desired, allocate the disk space immediately by setting Allocate all disk space now.
Select Store virtual disk as single file.
Name and chose a location for the new virtual disk.
Repeat this process until enough disks are available for TrueNAS to create ideal storage pools. This depends on your specific TrueNAS use case.
See Pool Creation for descriptions of the various pool (“vdev”) types and layouts.
Using the TrueNAS Installer
Just as with installing SCALE on physical hardware, you complete the install in the VM by booting into the TrueNAS installer.
Select the virtual machine from the list and click Play virtual machine.
The machine starts and boots into the TrueNAS installer.
Select Install/Upgrade.
Select the desired disk for the boot environments.
Select Yes. This erases all contents on the disk!
Next, set a password for the TrueNAS administrative account, named root by default.
This account has full control over TrueNAS and is used to log in to the web interface.
Set a strong password and protect it.
Next, enter a password for the new admin user.
Select Boot via BIOS.
After the TrueNAS SCALE installation completes, reboot the system.
The Console Setup Menu displays when the system boots successfully.
Congratulations, TrueNAS SCALE is now installed!
The next step is to boot up the system and configure SCALE network and general settings with the [Console Setup Menu]](/scale/gettingstarted/install/consolesetupmenuscale/) so you can log into the web UI.
This article provides instructions on configuration network settings using the Console setup menu after you install TrueNAS SCALE from the iso file.
The Console setup menu (CSM) displays at the end of the boot process.
If the TrueNAS system has a keyboard and monitor, you can use this menu to administer the system.
By default, TrueNAS does not display the Console setup menu when you connect via SSH or the web shell.
The root user or another user with root permissions can start the Console setup menu by entering the /etc/netcli command.
The menu provides these options:
1) Configure network interfaces which provides options to set up network interfaces. These display in the Global Configuration widget on the Network screen in the web UI.
2) Configure network settings which provides options to set up the network default gateway, host name, domain, IPv4 gateway and the DNS name servers.
3) Configure static routes which provides options to setup static routes. Not required as part of the initial configuration setup.
4) Reset root password which resets the root user password. This is the password for the root user in the CLI and the root user login password for the web UI.
5) Reset configuration to defaults which resets the system configuration settings back to defaults.
6) Open TrueNAS CLI shell which starts a shell for running TrueNAS commands. Type exit to leave the shell.
7) Open Linux shell which starts a shell window for running Linux CLI commands. Type exit to leave the shell.
8) Reboot which reboots the system.
9) Shut down which shuts down the system.
Console setup menu options can change with software updates, service agreements, etc.
During 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 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:
Does not have a monitor.
Is on a network that supports Multicast DNS (mDNS).
Configuring Network Settings
You can use the Console setup menu to configure your primary network interface and any other interfaces you want to uses such as a link aggregate (LAGG) or virtual LAN (VLAN).
You can also use the Console setup menu to configure other network settings such as the default gateway, host name, domain, and the DNS name servers, or add static routes.
Enter 1 to display the Configure Network Interfaces screen where you can select the interface settings. If you want to use commands, enter 7 to open a Linux shell and then enter commands.
Enter 2 to display the Network Settings screen where you set up the host name, domain, default gateway and name servers.
Enter 3 to display the Static Route Settings screen where you can set up any static routes. You can also add static routes in the web UI.
Configuring Required Network Settings
First, configure your primary network interface. The IP address assigned by DHCP displays in the Console setup menu screen. You can configure the default gateway, host name, domain and DNS name severs using the Console setup menu but you should use the web UI to configure these settings. Go the Network screen.
To use the CSM, type 1 to display the Configure Network Interfaces screen. Select the interface to use as your primary network interface and the settings to use. Use Tab to select Save and then press Enter.
Next, open a browser window and enter the IP address DHCP assigned to your TrueNAS. The web UI should display, verifying you can access it. If it does not, return to the Console setup menu and re-enter the correct IP address as the primary interface address.
Log into the web UI as root with the default password set up during step 4 of the TrueNAS Installer process in Installing Scale.
After configuring the interface, you can use the CSM to configure the rest of your network settings, but this procedure describes using the web UI to configure the rest of the network settings.
To enter the remaining network settings in the web UI, go to Network > Global Configuration and click Settings. Enter the values in the appropriate fields and click Save.
For home users, use 8.8.8.8 as the DNS nameserver address. This allows you to access the internet using TrueNAS SCALE.
Changing the Root Password
SCALE has implemented rootless login, making the admin user the default account. Change the admin user password in the UI.
The Reset root password option in the console menu is useless if the admin password is enabled and the root user password is disabled in the Edit User screen.
Disabling a password in the UI prevents the user from logging in with it.
Changing the root password disables 2FA (Two-Factor Authentication).
Resetting the System Configuration
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 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.
Completing your System Setup
After setting up network requirements in the web UI, complete your system setup by:
This article provides basic instructions for setting up your first storage pool, and also provides storage requirement information.
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 one disk is for storage and the other for data protection.
However, there are a vast number of configuration possibilities for your storage environment!
You can read more about these options in the in-depth Creating Storage Pools.
Minimum Storage Requirements
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 limit.
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.
Setting Up Storage
Go to Storage > Pools and click Add.
Select Create a new pool and click Create Pool
Enter a name for your first storage pool in Name. For example, tank or any other preferred name.
Select two disks listed under the Available Disks section and then click the east to move them to the Data VDevs area.
If the disks used have non-unique serial numbers a warning message displays. To populate the Available Disks section with these disk, select the Show disk with non-unique serial numbers checkbox.
TrueNAS automatically suggests Mirror as the ideal layout for maximized data storage and protection.
Review the Estimated raw capacity to the right of the Data Vdev type dropdown list to make sure you have the storage capacity you need, and then click Create.
A warning dialog displays. Click Confirm to activate the CREATE POOL button.
After you click CREATE POOL the system displays a fetching-data dialog and then a status dialog.
TrueNAS wipes the disks and adds your pool (tank is the example used) to the Storage > Pools list.
Adding Datasets or Zvols
New pools have a root dataset that allows further division into new datasets or zvols.
A dataset is a file system that stores data and has specific permissions.
A zvol is a virtual block device that has a predefined storage size.
To create either one, go to Storage > Pools, click , and select Add Dataset or Add Zvol.
The two fields that you cannot change after you click Save are the dataset Name and Share Type.
Name is a required field but Share Type is optional.
The default setting for Share Type is Generic which works for any share type you create or you can select SMB if you know you want to create an SMB share.
A dataset with a Share Type set to SMB optimizes that dataset for the Windows sharing protocol.
Organize the pool with as many datasets or zvols you need according to your access and data sharing requirements before moving any data into the pool.
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.
When you finish building and organizing your TrueNAS pools, move on to configuring how the system shares data
This article provides general information on setting up basci data sharing on TrueNAS SCALE.
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.
As of SCALE 22.12 (Bluefin), TrueNAS SCALE SMB no longer supports End of Life (EoL) Windows clients, including MS-DOS.
The Samba project, which TrueNAS SCALE integrates to provide SMB sharing features, had previously deprecated the SMB1 protocol for security concerns. TrueNAS SCALE 22.12 (Bluefin) updated Samba to version 4.17, which eliminated SMB1 support entirely. Client systems that can only use the SMB1 protocol for SMB shares are no longer capable of connecting to SMB shares created in TrueNAS SCALE 22.12 or later. Refer to the Samba release notes for more information.
Sharing Data Methods
TrueNAS SCALE provides four types of sharing methods, but this article only discusses three:
SMB for Windows
NFS for Unix-like sharing
ISCSi block shares
Setting UP SMB for Windows
To set up SMB sharing:
Create a dataset with Share Type set to SMB: Go to Datasets and click on the Add Dataset button.
The Add Dataset menu displays on the right side of the screen.
Enter a Parent path and Name for the SMB share.
Select the Share Type as SMB from the dropdown list.
Click Save.
Create the TrueNAS user accounts with Samba Authentication set.
a. Go to Credentials > Local Users and click Add to create users.
b. Enter the values in each required field, and then verify the checkmark for Samba Authentication exists.
c. Click Save.
Edit the dataset permissions to set the Select an ACL Preset to Open.
a. Go to Datasets. Select the name of the SMB share you created. Scroll down to the Permissions widget on the right side of the screen.
Click the Edit button to edit the permissions.
b. Select Use ACL Preset. The Select a preset ACL dialog displays. Select NFS4_OPEN from the dropdown list.
c. Click Continue.
d. Click Save Access Control List.
Create the new SMB share. Go to Shares > Windows (SMB) Shares and click Add.
a. Select the dataset you created for the share in the Path field.
You can click on the to the left of mnt, and then at the pool to expand the options, and then click on the dataset to populate the field with the full path.
b. Enter a name for the share.
c. Click Save.
Turn the SMB service on.
Click the for the share and select Turn On Service from the Sharing screen.
Connect to the share. On a Windows 10 system, open the File Browsers and then:
a. In the navigation bar, enter \\ and the TruNAS system name or IP address. A login or credentials dialog displays.
b. Enter the TrueNAS user account credentials you created on the TrueNAS system.
c. Begin browsing the dataset.
Setting UP NFS for Unix-Like Share
To set up NFS sharing:
Create a dataset with Share Type set to Generic:
a. Go to Datasets and click on the Add Dataset button.
b. Enter a name and select Generic in the Share Type field.
c. Click Save.
Add additional packages like nfs-common to any client systems that require them.
Create the NFS share. Go to Shares > UNIX (NFS) Share Targets and click Add. The Add NFS configuration form displays.
a. Select the dataset you created for the share in the Path field.
You can click on the to the left of mnt, and then at the pool to expand the options, and then click on the dataset to populate the field with the full path.
b. 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 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.a. 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 an ISCSi Block Share
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 scop of this getting started guide, but detailed articles are available in the UI Reference section under Shares.
With simple sharing now set up, you can back up your configuration and set up data backup.
This article provides general information and instructions on setting up storage data backup solutions and saving the system configuration file in TrueNAS SCALE.
After configuration your TrueNAS storage and data sharing, it is time to ensure effective back up of your data using the backup options TrueNAS provides. You should also download and save your system configuration file to protect your system configuration information.
Backing Up TrueNAS Storage Data
TrueNAS provides for data backup through cloud sync or replication.
Using Cloud Sync for Data Backup
Cloud sync requires an account with a cloud storage provider and a storage location created with that provider, like Amazon S3 bucket.
SCALE support major providers like 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 polices of your cloud storage provider before transferring your data.
You can configure TrueNAS to send, receive, or synchronize data with a cloud storage provider. To set up cloud sync:
Add your cloud storage credentials to TrueNAS.
Go to Credentials > Backup Credentials and click Add. The Cloud Credentials configuration panel displays.
Some cloud storage providers, like Amazon S3, require you log into your cloud account to generate additional information like an access key. TrueNAS requires you to enter the Amazon S3 credentials you generate on their Security Credentials > Access Keys page before you can save and add the cloud credentials.
Check with your cloud storage provider to see what credentials they require TrueNAS to provide to complete data transfers.
Some cloud storage providers, like Box, can automatically populate the required Authentication fields if you log into your account.
To automatically configure this credential, click Log In To Provider. An Authorization screen displays where you click Proceed to continue to the login screen for that service.
After you enter your cloud account login and password, the TrueNAS Cloud Credential authentication fields auto-populate with the required information. Click Save to complete the process of adding your cloud credentials.
We recommend you verify the credential before saving it if you do not log into your cloud storage provider as part of the process.
Create a data transfer task.
Go to Data Protection > Cloud Sync Tasks and click Add. The Add Cloud Sync Task configuration panel displays.
Type a memorable name for this in Name, select the Direction as either Push to send data to the cloud service or Pull to get data from the cloud service. You can set up a cloud sync task to send data to and another task to get data from the cloud storage provider. Select the Transfer Mode as Copy, Move or Sync.
Click in the Credential dropdown field to select Add a backup credential. This displays a new form where you select and configure your cloud storage provider credentials. Amazon S3 is the default provider when the form opens. The example shown uses box send data as the name and Box as the Provider.
Box provides a way to auto-populate the authentication credentials when you click Log In To Provider. An Authorization window displays. Click Proceed and then the Box login window displays. Enter your Box cloud credentials. After the TrueNAS cloud storage provider authentication details populate the form, click Verify Credential and after verified, click Save. This form closes and returns you to the Add Cloud Sync Task configuration panel to complete the set up.
Either type the path into the Directory/Files field or click on the to the left of mnt, and then at the pool to expand the dataset options, and then click on the dataset, and then file if you want to narrow backup down that far, to populate the field with the full path.
Next when you want this task to run using the Schedule dropdown list to select the frequency.
Clear the Enable checkmark to make the configuration available without allowing the specified schedule to run the task.
To test the sync task, click Dry Run.
To manually activate a saved task, go to Data Protection > Cloud Synch Tasks click the for the cloud sync task you want to run. Select Run Now to start the cloud sync operation.
Using Replication for Data Backup
Replication is the process of taking a moment-in-time snapshot of the data and copying that snapshot to another location. Snapshots typically use less storage than full file backups and have more management options. This instruction shows using the TrueNAS replication wizard to create a simple replication task.
Create the replication task.
Go to Data Protection > Replication and click Add. The Replication Task Wizard displays the What and Where configuration screen. Select both the Source Location and Destination Location using the dropdown list options. You can back up your data on the same system or a different system. If you select A different system you must have SSH connection, destination and source information ready.
Next enter the Source and Destination paths. You can either type the full path to the data you want to back up or click on the to the left of mnt, and then at the pool to expand the dataset options, and then click on the dataset, and then file if you want to narrow backup down that far, to populate the field with the full path.
The task a name populates from the values in Source and Destination. Click Next.
Define when you want this task to occur.
Select the radio button for Run On a Schedule and select the schedule you want to use. Or select Run Once to run the task manually.
Select the radio button to specify how long the destination snapshot lifetime.
Click START REPLICATION
To confirm replication created your snapshot, go to Storage > Snapshots.
Backing Up the System Configuration
Now that you configured your system network, storage and any data shares you wanted, and you have set up your data back up solution it is time to back up your system configuration.
If you plan to set up a cluster that includes this TrueNAS scale, wait to download your system configuration file until the cluster is set up and working.
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.
This section provides information for CORE users migrating to SCALE.
Linux treats device names differently than FreeBSD so please read Component Naming for more information.
The ZFS flag feature merged into the TrueNAS fork of OpenZFS for developers to test and integrage with other parts of the system on June 29,2021 is also removed. Please read ZFS Feature Flags Removed for details on this change.
This article provides information on disk and interface naming changes related to the change from FreeBSD storage and sharing in CORE to Linux in TrueNAS SCALE.
This article provides information on the removal of the ZFS feature flag merged into OpenZFS in June 29, 2021.
4.1 - Migrating from TrueNAS CORE
This article provides instructions on migrating from TrueNAS CORE to SCALE. Migration methods include using an ISO file or a manual update file.
Migration Notes
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.
You cannot upgrade CORE systems with High Availability enabled (HA) to SCALE HA.
TrueNAS systems on 12.0x or lower should update to the latest CORE 13.0 release (e.g 13.0-U2) prior to migrating to SCALE.
TrueNAS SCALE is Linux based, so it does not support FreeBSD GELI encryption.
If you have GELI-encrypted pools on your system that you plan to import into SCALE, you must migrate your data from the GELI pool to a non-GELI encrypted pool before migrating to SCALE.
TrueNAS SCALE validates the system certificates when a CORE system migrates to SCALE. When a malformed certificate is found, SCALE generates a new self-signed certificate to ensure system accessibility.
Migration Methods
You can migrate from CORE to SCALE using an iso file or a manual update file.
ISO File Method
Start by saving the SCALE ISO file to a USB drive (see the Physical Hardware tab in Installing SCALE). Plug the USB drive into the CORE system that you want to sidegrade and boot or reboot the system.
At the motherboard splash screen, use the hotkey defined by your motherboard manufacturer to select a boot device, then select the USB drive with the SCALE .iso.
When the SCALE console setup screen appears, select Install/Upgrade.
Select your TrueNAS boot disk
The installer asks if you want to preserve your existing configuration or start with a fresh installation. We recommend selecting Upgrade Install when migrating from CORE to SCALE to keep your configuration data. Then select Install in new boot environment.
Although TrueNAS attempts to keep most of your CORE configuration data when upgrading to SCALE, some CORE-specific items do not transfer.
GELI encrypted pools, NIS data, jails, tunables, and boot environments do not migrate from CORE to SCALE.
VM storage and its basic configuration is transferred over during a migration. You need to double-check the VM configuration and the network interface settings specifically before starting the VM.
AFP shares also do not transfer, but you can migrate them into an SMB share with AFP compatibility enabled.
Init/shutdown scripts transfer, but can break. Review them before use.
The CORE netcli utility is also swapped for a new CLI utility to use for the Console Setup Menu and other commands issued in a CLI.
After choosing to install in new boot environment, the installer warns that SCALE installs into the boot pool previously used for CORE. Select Yes.
Once the installation completes, reboot the system and remove the USB with the SCALE .iso file.
Start by downloading the SCALE manual update file.
Confirm that the TrueNAS system is on the latest public release, 13.0-U2 or better.
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.
This is recommended but it not required.
Select a Temporary Storage Location (either Memory Device or a Pool) for the manual update file.
Click Choose File and select the TrueNAS-SCALE.update file you downloaded.
Then click APPLY UPDATE.
After the update completes, reboot the system.
Parallel SCALE CLI Commands
The following CLI commands are available after migrating from CORE to SCALE. The CORE equivalent CLI commands are for reference. These commands are for diagnostic use. Making configuration changes using the SCALE OS CLI is not recommended.
Use lshw -class disk -short sfdisk -l to get detailed information on hardware (disk) configuration that includes memory, mainboard and cache cofiguration, firmware version, CPU version and speed.
Use ip addr to show or manipulate routing, devices, or policy routing and tunnels. Use ifconfig -s cofigure a network interface. Use lshw -class network -short to display a network device tree showing hardware paths. Use ethtool *devnam* to query or control network driver and hardware settings.
Use iftop to display interface bandwidth usage by host and netstat to print network connections, routing tables, interface statistics, masquerade connections, and multicast memberships.
This article provides information on disk and interface naming changes related to the change from FreeBSD storage and sharing in CORE to Linux in TrueNAS SCALE.
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.
Disks
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.
Interfaces
TrueNAS CORE utilizes driver information and enumeration to assign an interface name.
TrueNAS SCALE uses PCI location to assign an interface name.
See the TrueNAS Systems section for lists of the default port names for each platform.
Related Content
4.3 - ZFS Feature Flags Removed
This article provides information on the removal of the ZFS feature flag merged into OpenZFS in June 29, 2021.
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.
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.
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.
Related Content
5 - First Time Login
Now that you have installed and configured TrueNAS SCALE, you can log in to the web interface and begin managing data!
After installing TrueNAS, you can configure and use the system through the web interface.
Important! Use only the web interface to make configuration changes to the system.
By default, using the command-line interface (CLI) to modify the system does not modify the settings database.
The system reverts to the original database settings when it restarts and wipes any user-made command line changes.
TrueNAS automatically creates several ways to access the web interface, but you might need to adjust the default settings for your network environment.
Web Interface Access
By default, fresh installs of TrueNAS SCALE provide a default address for logging in to the web interface.
To view the web interface IP address or reconfigure web interface access, 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 in the Global Configuration card.
To access the web interface using an IP address, use the one that the Console Setup Menu generated after installing SCALE, or use the one you configured in the Post-install Configuration article if you upgraded from CORE.
Logging In
On a computer with access to the same network as the TrueNAS system, enter the host name and domain or IP address in a web browser to connect to the web interface.
The quality of your user experience can be impacted by the browser that you use. We generally recommend using Firefox, Edge, or Chrome.
Use the administrative account credentials to log in.
The default administrator username is root and the password is created when installing TrueNAS.
If the user interface is not accessible by IP address from a browser, check these things:
If the browser configuration has proxy settings enabled, disable them and try connecting again.
If the page does not load, ensure a ping reaches the TrueNAS system IP address. If the IP address is in a private range, you must access it from within that private network.
If the web interface displays but seems unresponsive or incomplete:
Make sure the browser allows cookies, Javascript, and custom fonts from the TrueNAS system.
Try a different browser. We recommend Firefox.
If the UI becomes unresponsive after an upgrade or other system operation, clear the site data and refresh the browser (Shift+F5).
If I 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 root account password.
Dashboard
Video Player is loading.
Current Time 0:00
/
Duration 1:20
Loaded: 0.61%
0:00
Stream Type LIVE
Remaining Time -1:20
1x
Chapters
descriptions off, selected
captions settings, opens captions settings dialog
captions off, selected
This is a modal window.
Beginning of dialog window. Escape will cancel and close the window.
After logging in, you see the system Dashboard screen.
Dashboard displays basic information about the installed version, systems component usage, and network traffic. For users with compatible TrueNAS
hardware, clicking the system image takes you to the System Settings > Enclosure page.
The Dashboard provides access to all TrueNAS management options.
The top row has links to outside resources and buttons to control the system.
The left-hand column lets users navigate to the various TrueNAS Configuration screens.
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.
Top Bar Menu
The icon buttons in the top toolbar menu link to the iXsystems site, display the status of TrueCommand and directory servers, and show system processes, and configuration menus. You can also collapse and expand the main function menu on the left side of the screen.
Top Toolbar Icons
The iXsystems logo opens the iXsystems home page. There, 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.
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.
See Connecting TrueNAS for more information on configuring a TrueCommand cloud account and getting an API key.
The Directory Services Monitorinfo icon button displays the status of Active Directory and LDAP services.
Clicking on either takes you to their respective configuration screens.
The Jobsassignment icon button displays all running and failed jobs/processes. Access minimized jobs/processes here.
Users can minimize a job/process by clicking the - in any dialogue or pop-up window.
Click on a running task to display a dialog for that running task.
You can abort active jobs (like a disk wipe for example) by clicking the white circled X next to the active job.
Click the History button to open the Tasks screen. Tasks lists all successful, active, and failed jobs. Users can also click View next to a task to view its log information and error message.
For more information see the Tasks Screens article.
The Alertsnotifications icon button displays a list of current alerts for your TrueNAS system. Users can dismiss them one at a time or all at once.
It also provides an Alerts menu you access by clicking the settings icon. From this menu users can configure Alert Settings, Alert Services, and Email.
The Alert Settings screen has options for setting the warning level and frequency for alerts specific to application actions.
Use the Set Warning Level dropdown list options to customize alert importance. Each warning level has an icon and color to express the level of urgency.
Use the Set Frequency dropdown list options adjust how often the system sends alert notifications. Setting the Frequency to NEVER prevents that alert from appearing in the Alerts list, but it still pops up in the UI if triggered.
Each warning level has a different icon and color to express its 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.
The Alert Services screen has options to create and edit alert services. It also displays existing services in a list that users can filter by Type, Level, and Enabled.
To create a new alert service, click Add and fill out the form, then click Save.
Click SEND TEST ALERT to generate a test alert to confirm the alert service works.
The Email screen lets you set up a system email address.
Click on Send Test Mail to generate a test email to confirm the system email works.
See Email Screens for information on email settings.
The Settingsaccount_circle icon button has options for passwords, API Keys, and TrueNAS information.
Click on the Change Passworddialpad icon button to display the change password dialog where you can change the currently logged-in user password.
Click on the visibility_off icon to display entered passwords.
To stop displaying the password, click on the visibility icon.
Click on API Keyslaptop to add API keys that identify outside resources and applications without a principal.
Users can also click DOCS to access their system API documentation.
See API Keys for more information on adding or managing API keys.
Click on Guidelibrary_books to open the TrueNAS Documentation Hub in a new tab.
Click on About to display the information window with links to the TrueNAS Documentation Hub, TrueNAS Community Forums, FreeNAS Open Source Storage Appliance GitHub repository, and iXsystems home page.
Click the Powerpower_settings_new icon button to either log out of, restart, or shut down the system.
Storing Data
Now that you can access the TrueNAS web interface and see all the management options, you can begin storing data!
Initial setup procedures to prepare a system for clustering
One unique capability of TrueNAS SCALE is it can cluster groups of systems together.
These clusters can then create new volumes within the existing SCALE storage pools.
Data stored in a clustered volume is shared between the clustered systems and can add additional redundancy or performance to the environment.
Currently, data stored in a clustered volume is shareable using Active Directory (AD) and the SMB protocol.
Clustering is considered experimental and should not be used in a production environment or for handling critical data!
Warnings and Restrictions
Clustering is a back-end feature in TrueNAS SCALE. You should only configure clustering using the TrueCommand web interface.
Attempting to configure or manage clustering from within the TrueNAS SCALE UI or Shell can result in cluster failures and permanent data loss.
Using the clustering feature on a SCALE system adds some restrictions to that system:
Any existing non-clustered SMB shares no longer function.
You cannot create new SMB shares separately from the clustering settings.
You cannot add the system to a different cluster.
Removing single systems from one cluster and migrating to another is currently unsupported. Removing a system from a cluster requires deleting the entire cluster.
Requirements
To set up clustering with TrueNAS SCALE, you need:
3-20 TrueNAS SCALE systems (version 22.02.2 or later) on the same network. Each SCALE system must have:
Two network interfaces and subnets.
The primary network interface and subnet are for client access to the SCALE system.
The secondary interface and subnet are only for cluster traffic. This interface must use static IP addresses.
Disks available or Storage pools already created and available for use.
A TrueCommand 2.2 or later environment on the same network as the SCALE systems.
A Microsoft Active Directory environment must be available and connected to the same network as the SCALE systems and TrueCommand environment.
You must configure Reverse DNS to allow the SCALE cluster systems to communicate back and forth with the AD environment.
Setting up the Environment
TrueNAS SCALE Systems
Follow this procedure for each TrueNAS SCALE system that is to be connected to TrueCommand and used in the cluster.
Log in to the SCALE UI and go to the Storage page.
Ensure a storage pool is available for use in the cluster.
If not, click Create Pool and make a new pool using any of the available disks.
Go to the Network page and look at the Interfaces card.
a. Ensure two interfaces are available and note which is the primary interface that allows SCALE web interface access and access between SCALE systems, TrueCommand, and Active Directory environments.
Having two interfaces allows connecting the SCALE systems to Active Directory and using TrueCommand to create and manage the cluster.
b. Ensure the second interface has a static IP address on a different network/subnet that connects all the SCALE systems.
This interface securely handles all the data-sharing traffic between the clustered systems.
TrueNAS automatically adds entries to AD DNS for CTDB public IP addresses. Administrators should add the addresses before joining AD to prevent significant configuration errors.
Go to the Shares page and look at the Windows (SMB) Shares section. Note if there are any critical shares and take steps to ensure that disabling those shares isn’t disruptive.
Repeat this procedure for each SCALE system to be clustered.
Microsoft Active Directory
Verify that the Active Directory (AD) environment to pair with the cluster is available and administratively accessible on the same network as the TrueCommand and TrueNAS SCALE systems.
Log in to the Windows Server system and open the Server Manager.
Click Tools > DNS to open the DNS Manager.
In the left side menu, expand Reverse Lookup Zones and select the Active Directory-Integrated Primary zone to use for the cluster.
In a browser, enter the TrueCommand IP address and create the first user. Log in with these user credentials to see the Dashboard.
Click New System and add the credentials for the first SCALE system. Use the SCALE root account password. When ready, click ADD AND CONTINUE and repeat the process for each SCALE system intended for the cluster.
When complete, each SCALE system has a card on the TrueCommand Dashboard and is actively displaying system statistics.
A good practice is to back up the SCALE system configuration before creating the cluster.
In the TrueCommand Dashboard, click on the name of a connected system to open a detailed view of that system.
Click Config Backups and CREATE BACKUP to store the SCALE configuration file with TrueCommand.
Backups allow users to quickly restore the system configuration to the initial working state if something goes wrong.
Then click APPLY UPDATE.
icon lets users sign up with and connect to 
If no zone exists, see Microsoft’s guide for 
