This guide provides step-by-step tutorials to install and configure SCALE. An additional guide shows how to apply and configure SCALE Enterprise licensed systems.
This section guides you through installing TrueNAS SCALE or migrating from CORE to SCALE, and using the UI to access and configure TrueNAS SCALE.
Configuration includes setting up initial storage, backup, and data sharing, and expanding TrueNAS with different applications solutions.
The SCALE Evaluation Guide also provides video tutorials for installing and exploring the full potential of TrueNAS SCALE.
TrueNAS SCALE Getting Started Contents
This is a listing of all the primary content sections in this Getting Started Guide.
⎙ Download or Print: View all SCALE Getting Started articles as a single page for download or print.
SCALE 23.10 Release Notes: Highlights, change log, and known issues for each SCALE 23.10 (Cobia) release.
SCALE Hardware Guide: 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.
Highlights, change log, and known issues for each SCALE 23.10 (Cobia) release.
SCALE 23.10 (Cobia) Primary Features
There are many new features and continued improvements to the TrueNAS SCALE experience:
Apps redesigned: an overhaul of apps screens and backend improvements provides a more complete experience.
Storage Pool creation redesign: provides more details about pool configuration and supports larger SCALE deployments.
Drive count optimizations: SCALE 23.10 allows up to 1255 disks, or more than 25PB under management on a single system.
Samba update and speed improvements.
SMB/NFSv4 multiprotocol dataset sharing.
Simplified feedback and bug reporting.
Linux Kernel 6.1 and improved Hardware Support.
OpenZFS 2.2 with many iXsystems contributions.
NVIDIA 535.54.03 Driver Updates.
SCALE Enterprise: iSCSI ALUA support is added to TrueNAS SCALE Enterprise.
System service replacements: many system services that were built in to SCALE Bluefin are rebuilt as optional TrueNAS SCALE applications.
System reporting has been overhauled and now uses Netdata as the backend to provide system statistics to the Reporting screens.
Pause / Unpause ZFS Scrub Controls.
ZFS Block Cloning (Deduplication) for SMB & NFS file copies (requires a pool upgrade for pools created in previous major versions before 23.10).
ZFS dRAID Pool Layouts.
Importing of SMB shares from other systems (Coming Soon!).
Simplified SMB cluster expansion via TrueCommand is planned with the release of TrueCommand 3.0.
Service Deprecations
Several built-in services from SCALE 22.12 (Bluefin) in System Settings > Services are replaced by community applications.
You must disable these built-in services and begin using the equivalent application before upgrading to SCALE 23.10 (Cobia).
TrueNAS Enterprise
TrueNAS SCALE Enterprise customers with TrueNAS SCALE 22.12.3 (Bluefin) or later deployed are warned when a deprecated service is in use.
To prevent any loss of service, customers with Silver or Gold level support contracts with iXsystems are prevented from upgrading to TrueNAS SCALE 23.10 (Cobia) until the deprecated services are addressed.
Due to the MinIO filesystem mode deprecation and update methodology, older versions of MinIO are not updatable to newer versions and require additional update steps.
This impacts moving from the built-in S3 service to the Minio application.
See Migrating from MinIO S3 in the TrueNAS SCALE 22.12 (Bluefin) documentation for a detailed, TrueNAS-specific, tutorial for moving configuration and storage data from the built-in S3 service to the latest Minio version, available from the Community App Catalog.
Obtaining a Release
Log in to the web interface and go to System Settings > Update to check for available updates from the TrueNAS-SCALE-Cobia - TrueNAS SCALE Cobia [release] update train and begin downloading the latest stable release.
Alternately, to download an .iso file or .update for installing or upgrading to SCALE 23.10.2 (Cobia), go to https://www.truenas.com/truenas-scale/ and click Download.
See Software Releases for the latest development updates and timelines.
Upgrade Notes
The only install option supported by the 23.10 (Cobia) ISO installer is a clean installation.
The ISO installer Upgrade Install and Fresh Install options are removed.
Continue to use the TrueNAS SCALE update process to seamlessly upgrade from one SCALE major version to another.
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
TrueNAS SCALE is an appliance built from specific Linux packages.
Attempting to update SCALE with apt or methods other than the SCALE web interface can result in a nonfunctional system.
All auxiliary parameters can change between TrueNAS major versions due to security and development changes.
We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
Systems with large numbers of attached disks are recommended to use the new Pool Creation wizard when creating or modifying a pool.
New OpenZFS feature flags are available in this release.
Storage pools created in previous TrueNAS SCALE versions can upgrade to enable the new feature flags.
Storage pool upgrades are typically not required unless the new OpenZFS feature flags are deemed necessary for required or improved system operation.
Do not do a pool-wide ZFS upgrade until you are ready to commit to this SCALE major version and lose the ability to roll back to an earlier major version!
Consider these factors before upgrading a storage pool to the latest OpenZFS feature flags.
Upgrading can affect data.
Before performing any operation that affects data on a storage disk, always back up data first and verify the backup integrity.
New OpenZFS feature flags are permanently applied to the upgraded pool.
An upgraded pool cannot be reverted or downgraded to an earlier OpenZFS version.
A storage pool with the latest feature flags cannot import into another operating system that does not support those feature flags.
Upgrading a ZFS pool is optional.
Do not upgrade the pool when reverting to an earlier TrueNAS version or repurposing the disks in another operating system that supports ZFS is a requirement.
TrueCommand support for TrueNAS SCALE 23.10 (Cobia) system connections is anticipated in the TrueCommand 3.0 release.
Systems using TrueCommand clustering should not upgrade to 23.10 (Cobia) and remain on 22.12 (Bluefin) until compatible TrueCommand and SCALE versions are released at a later date.
Use caution when upgrading a system that has a storage pool that is both encrypted and is used for TrueNAS SCALE application storage.
When this is a critical use case, remain on TrueNAS SCALE Bluefin until a later SCALE Cobia maintenance release addresses any issues with encrypted pools used for application storage and management.
TrueNAS SCALE 23.10 (Cobia) changed from using ntpd to chronyd for system time management.
Use chronyc commands instead of ntpq or similar ntp commands.
Systems with physical NICs upgrading from TrueNAS SCALE 22.12 (Bluefin) to 23.10 (Cobia) might encounter an issue relating to NIC names being updated and written to the database.
If the Dashboard doesn’t fully load when logging in to 23.10 (Cobia), go to Network and re-apply the interface settings to the named physical interfaces.
Upgrade Paths
There are a variety of options for upgrading to SCALE 23.10.
See the TrueNAS Software Status page for recommendations about which software version to use based on your user type.
Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new TrueNAS SCALE major version.
System configuration files generated from releases before 22.12.4 (Bluefin) are not compatible with 23.10 (Cobia).
When available, update the system to 22.12.4 (Bluefin), resolve any migrations from deprecated services to replacement apps, and download a fresh system configuration file before attempting to upgrade.
If attempting to migrate from TrueNAS CORE, see the Migration section for cautions and notes about differences between each software and the CORE to SCALE migration process.
TrueNAS Enterprise
Migrations from TrueNAS CORE for Enterprise High Availability (HA) systems are not recommended at this time.
TrueNAS SCALE
flowchart LR
A["22.02.4 (Angelfish)"] --> C
B[CORE 13.0-U6] --> C
C["22.12.4.2 (Bluefin)"] --> D
D["23.10.2 (Cobia)"]
iXsystems is pleased to release TrueNAS SCALE 23.10.2!
This is a maintenance release to address community reported bugs in SCALE 23.10.1 and improve stability.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
Known Issues
TrueNAS Enterprise
Some TrueNAS Enterprise HA systems can experience a panic if the admin configures iSCSI extents while the passive controller is in the process of setting up ALUA configuration.
When setting up new deployments with many targets, fully configure all iSCSI extents and targets before enabling ALUA.
Some users find SATA SSD drive temperatures are not visible on the Reporting screen (NAS-127524). If you experience this issue, go to System Settings > Services, locate the S.M.A.R.T. service row and click edit to open the S.M.A.R.T. General Options screen. Set Check Interval to 30 or less.
iXsystems is pleased to release TrueNAS SCALE 23.10.1.3!
This is a small hotpatch with fixes for network interfaces, including related fixes for TrueNAS Enterprise High-Availability (HA) platforms.
Notable Changes
NAS-125862 - bond (link aggregation) physical interface constraint failure during database migration.
TrueNAS Enterprise
These changes and known issue only impact TrueNAS SCALE Enterprise platforms with the High Availability (HA) feature.
Community users are not impacted.
NAS-126722 - Treat interface FAULT event messages as BACKUP.
NAS-126922 - Fix HA Virtual IP (VIP) error when interfaces have a null vrrp_config key.
Known Issues
The failover feature on TrueNAS SCALE Enterprise platforms with High Availability (HA) is currently incompatible with the network Spanning Tree Protocol (STP).
Please validate that STP is disabled on the network switch ports connected to the TrueNAS SCALE HA platform before enabling the failover feature.
23.10.1.2
This hotpatch was not released in favor of making and releasing a new build versioned as 23.10.1.3.
23.10.1.1
January 16, 2024
iXsystems is pleased to release TrueNAS SCALE 23.10.1.1!
This is a small hotpatch with fixes for web interface issues discovered after the 23.10.1 release.
The full 23.10.2 maintenance release is anticipated later in February.
Notable Changes
Fix non-physical interface (Link Aggregation, VLAN, Bridge) link address writing into the database when it is updated (NAS-125932).
A rare edge case with iSCSI ALUA that can cause server instability was discovered in SCALE 23.10 releases.
The upcoming SCALE 23.10.2 release fixes this issue and includes more bugfixes for servers with a large number of iSCSI targets.
SCALE 23.10 Enterprise-licensed systems should keep the iSCSI ALUA feature disabled.
After updating to 23.10.2, ALUA can be re-enabled.
See the 23.10.1 Ongoing Issues list below for any additional details about issues discovered after the 23.10.1 release.
23.10.1
December 19, 2023
iXsystems is pleased to release TrueNAS SCALE 23.10.1!
This is a maintenance release to address community reported bugs in SCALE 23.10 (Cobia) and improve stability.
Notable Changes
Reported issues involving cached Web UI artifacts are addressed in 23.10.1 (NAS-124602).
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
OpenZFS is updated to version 2.2.2 to fix a data integrity issue discovered in that project (NAS-125541).
While this bug has been present in OpenZFS for many years, this issue has not been found to impact any TrueNAS systems to date.
See this TrueNAS Community announcement for more details.
The ZFS block cloning feature is temporarily disabled in 23.10.1. This is being done out of an abundance of caution while the OpenZFS project conducts additional testing. While re-enabling this feature is anticipated in a future 23.10 release, SCALE nightly builds continue to have ZFS block cloning enabled for experimentation and testing.
Exporting Netdata reporting metrics to a third party database (Graphite) is now supported (NAS-123668).
All network interface hardware addresses persist at upgrade to address a name change some TrueNAS Enterprise system NICs experience when upgrading from TrueNAS SCALE Bluefin to TrueNAS SCALE Cobia (NAS-124679).
The deprecated Use System Dataset option in System Settings > Advanced > Syslog is removed (WebUI PR #9026).
Improved sorting and filtering of replace disk search results (NAS-124732).
Fix issue with immutable fields preventing additional storage configuration for applications (NAS-125196).
The only install option supported by the 23.10.1 (Cobia) ISO installer is a clean installation.
The ISO installer Upgrade Install and Fresh Install options are removed.
Only the Fresh Install behavior is supported by the SCALE 23.10.1 (and later versions) ISO file.
Continue to use the TrueNAS SCALE update process to seamlessly upgrade from one SCALE major version to another.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
Known Issues
Non-physical network interface addresses (Link Aggregation, VLAN, Bridge) improperly write into the database during interface configuration changes and cause these interfaces to stop functioning.
Users with critical virtualized network interfaces on 23.10.0 should wait to update until the 23.10.1.1 release is available.
If the system encounters this issue after updating to 23.10.1, first update to 23.10.1.1.
Then go to the Network screen, remove any saved bond, br, or vlan interface configurations, and recreate them.
See NAS-125932 and the related Jira tickets for more details.
TrueNAS Enterprise High Availability customers with iSCSI and ALUA enabled can experience intermittent iSCSI management issues due to operation timeout. A fix is forthcoming in the 23.10.2 release.
Adding a large custom applications catalog before a storage pool is selected for app use can result in system instability.
Work around the issue by selecting a pool for TrueNAS SCALE app usage and rebooting the system.
See NAS-125877 for more details.
Importing a designated ix-applications pool does not automatically start the installed applications.
This is targeted for resolution in the SCALE 23.10.2 maintenance release.
The Email Options screen accessed from Alertsnotifications > Email does not open if accessed a second time.
If you encounter this issue, simply refresh your browser or go to another screen in the TrueNAS UI and click Email again.
There is a known issue with the DashboardNetwork widget tooltip reporting incorrect values for network speed.
The main data presented in the Network widget is correct.
iXsystems is pleased to release TrueNAS SCALE 23.10.0.1!
This is a small hotpatch to address issues reported by the community after the 23.10.0 release.
Notable Changes
Fix for TrueNAS SCALE application deployment being stuck when the pool used for application management is encrypted (NAS-124776).
Fix issue where system logs stop sending to a remote logging server (NAS-124845).
See the 23.10.0 Ongoing Issues list below for any additional details about issues discovered after the 23.10.0 release.
23.10.0
October 24, 2023
iXsystems is pleased to release TrueNAS SCALE 23.10.0!
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
Known Issues
Some TrueNAS Enterprise system NICs experience a name change when upgrading from TrueNAS SCALE Bluefin to TrueNAS SCALE Cobia, preventing the NIC configuration from functioning (NAS-124679). Workaround: If this occurs when upgrading to SCALE 23.10 (Cobia), use the SCALE web interface to manually port the configuration from the nonfunctional NIC to the entry for the newly named NIC.
When the system has a single NIC that is affected and web interface access is unavailable, connect to the system serial console and manually port the previous configuration to the newly named NIC.
Early releases are intended for testing and early feedback purposes only.
Do not use early release software for critical tasks.
September 19, 2023
Notable Changes
The legacy pool creation screens are removed and the new pool creation wizard is the primary UI screen for creating new storage pools NAS-123697
Apps > Settings adds the Manager Container Images option for downloading, updating, or deleting specific container images from TrueNAS.
Web interface feedback buttons are visible for community feedback on early releases.
As part of the netdata implementation and overhaul of the reporting features, Graphite support is no longer built-in with TrueNAS SCALE 23.10 (Cobia) NAS-123862.
Fix for the UPS service to allow device detection NAS-123625
Click here for the full changelog of completed tickets that are included in the 23.10-RC.1 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
Known Issues
Notes:
VMs created in previous SCALE versions with a legacy BIOS enabled can lose the Display button in 23.10-RC.1.
When encountered, reconfigure the VM to use a UEFI BIOS to re-enable the Display button (NAS-124296).
Early releases are intended for testing and early feedback purposes only.
Do not use early release software for critical tasks.
August 15, 2023
There are many new features and continued improvements to the TrueNAS SCALE experience:
Apps redesigned: an overhaul of apps screens and backend improvements provides a more complete experience.
Storage Pool creation redesign: provides more details about pool configuration and supports larger SCALE deployments.
Drive count optimizations: SCALE 23.10 allows up to 1255 disks, or more than 25PB under management on a single system.
Samba update and speed improvements.
SMB/NFSv4 multiprotocol dataset sharing.
Simplified feedback and bug reporting.
Linux Kernel 6.1 and improved Hardware Support.
OpenZFS 2.2 with many iXsystems contributions.
NVIDIA 535.54.03 Driver Updates.
SCALE Enterprise: iSCSI ALUA support is added to TrueNAS SCALE Enterprise.
System service replacements: many system services that were built in to SCALE Bluefin are rebuilt as optional TrueNAS SCALE applications.
System reporting has been overhauled and now uses Netdata as the backend to provide system statistics to the Reporting screens.
Pause / Unpause ZFS Scrub Controls.
ZFS Block Cloning (Deduplication) for SMB & NFS file copies (requires a pool upgrade for pools created in previous major versions before 23.10).
ZFS dRAID Pool Layouts.
Importing of SMB shares from other systems (Coming Soon!).
Simplified SMB cluster expansion via TrueCommand is planned with the release of TrueCommand 3.0.
Notable Changes
The advanced Auxiliary Parameters field is removed from both Shares > SMB > Add and System Settings > Services > SMB screens (NAS-120530). Previously configured auxiliary parameters do remain on upgrade, but further changes must be done through CLI or API.
As part of the system reporting and debug improvements, system logs now exclusively write to the TrueNAS boot device.
Click here for the full changelog of completed tickets that are included in the 23.10-BETA.1 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
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
Our 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, and operates jails. It also hosts SMB shares and replicates TBs of data with less. iXsystems recommends the above for better performance and fewer issues.
You do not need an SSD boot device, but we discourage using a spinner or a USB stick.
We do not recommend installing TrueNAS on a single disk or striped pool unless you have a good reason to do so. You can install and run TrueNAS without any data devices, but we strongly discourage it.
TrueNAS does not require two cores, as most halfway-modern 64-bit CPUs likely already have at least two.
For help building a system according to your unique performance, storage, and networking requirements, keep reading.
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 effective use of both spinning-disk and all-flash storage or a mix of the two.
ZFS is prepared for the eventual failure of storage devices, and is highly configurable to achieve the perfect balance of redundancy and performance to meet any storage goal.
A properly-configured TrueNAS system can tolerate multiple storage device failures and recreate its boot media with a copy of the configuration file.
Storage Device Quantities
TrueNAS can manage many storage devices as part of a single storage array. With more Enterprise-level tuning in the mature 13.0 release and similar tuning in the upcoming SCALE Cobia release, TrueNAS can manage as many as 1,250 drives in a single storage array!
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 by default. Understanding the alternatives explains why.
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.
The first SATA disks offered double-digit gigabyte capacities. Newer SATA disks meet many size, reliability, and performance goals.
While consumer desktop SATA disks do not have the 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 so vast that many users push their consumer drives into 24/7 service pursuing 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 prefers WD 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 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, we almost completely replaced enterprise SAS drives discontinued from the TrueNAS product lines with 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 GB, 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 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, albiet smaller or more expensive storage solution.
If you plan to go all-flash, buy the highest-quality flash storage SSDs your budget allows, focusing 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 its low-latency performance. NVMe is becoming a mainstream option for boot and other tasks. At first, NVMe only came in 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.
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.
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 flash and disk to create hybrid storage that makes the most of both 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) that speeds 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 provides a faster cache, and the L2ARC table uses some RAM.
SLOG devices do not need a large capacity 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 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 must 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 more than the RAM size is a good guideline.
High-end TrueNAS systems can have NVMe-based L2ARC in double-digit terabyte sizes.
Remember 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.
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 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 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 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.
Zpool layout (the organization of LUNs and volumes, in TrueNAS/ZFS parlance) is outside of the scope of this guide.
The availability of double-digit terabyte drives raises a question TrueNAS users now have the luxury of asking: How many should I use to achieve my desired capacity?
You can mirror two 16 TB drives to achieve 16 TB of available capacity, but that does not mean you should.
Mirroring two large drives offers the advantage of redundancy and balancing reads between the two devices, which could lower power draw, but little else.
The write performance of two large drives is similar to that of a single drive.
By contrast, an array of eight 4 TB drives offers a wide range of configurations to optimize performance and redundancy at a lower cost.
If configured as striped mirrors, eight drives could yield four times greater write performance with a similar total capacity.
You might also consider adding a hot-spare drive with any zpool configuration, which lets the zpool automatically rebuild itself if one of its primary drives fails.
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, especially:
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 might not be honest or informed about their age and health.
Verify vendors have not recertified all new drives by checking the hours using smartctl(8).
A drive vendor could also zero the hours of a drive during recertification, masking the drive age.
iXsystems tests all storage devices it sells for at least 48 hours before shipment.
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 rebranded siblings with the LSI SAS2008 chip, such as the IBM M1015 and Dell H200, are legendary among TrueNAS users who build systems using parts from the second-hand market.
Flash using the latest IT or Target Mode firmware to disable the optional RAID functionality found in the IR firmware on Broadcom controllers.
For those with the budget, newer models like the Broadcom 9300/9400 series give 12 Gbps SAS capabilities and even NVMe to SAS translation abilities with the 9400 series.
TrueNAS includes the sas2flash, sas3flash, and storcli commands to flash or perform re-flashing operations on 9200, 9300, and 9400 series cards.
Onboard SATA controllers are popular with smaller builds, but motherboard vendors are better at catering to the needs of NAS users by including more than the traditional four SATA interfaces.
Be aware that many motherboards ship with a mix of 3 Gbps and 6 Gbps onboard SATA interfaces and that choosing the wrong one could impact performance.
If a motherboard includes hardware RAID functionality, do not use or configure it, but note that disabling it in the BIOS might remove some SATA functionality, depending on the motherboard.
Most SATA compatibility-related issues are immediately apparent.
There are countless warnings against using hardware RAID cards with TrueNAS.
ZFS and TrueNAS provide a built-in RAID that protects your data better than any hardware RAID card.
You can use a hardware RAID card if it is all you have, but there are limitations.
First and most importantly, do not use their RAID facility if your hardware RAID card supports HBA mode, also known as passthrough or JBOD mode (there is one caveat in the bullets below). When used, it allows it to perform indistinguishably from a standard HBA.
If your RAID card does not have this mode, you can configure a RAID0 for every disk in your system.
While not the ideal setup, it works in a pinch.
If repurposing hardware RAID cards with TrueNAS, be aware that some hardware RAID cards:
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 need to access 90 drives without SAS expanders.
While SAS expanders, designed for SAS disks, can often support SATA disks via the SATA Tunneling Protocol or STP, we still prefer SAS disks for reasons mentioned in the NL-SAS section above (SATA disks function on a SAS-based backplane).
Remember that you cannot use a SAS drive in a port designed for SATA drives.
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 they tested the drives under optimal environmental conditions.
The average temperature that a well-cooled spinning hard disk reaches in production is around 28 °C, and one study found that disks experience twice the number of failures for every 12 °C increase in temperature.
Before adding drive cooling that often comes with added noise (especially on older systems), know that you risk throwing money away by running a server in a data center or closet without noticing that the internal cooling fans are at their lowest setting.
Pay close attention to drive temperature in any chassis that supports 16 or more drives, especially if they are exotic, high-density designs.
Every chassis has certain areas that are warmer for whatever reason. Watch for fan failures and the tendency for some models of 8 TB drives to run hotter than other drive capacities.
In general, try to keep drive temperatures below the drive specification provided by the vendor.
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 vital to maintaining peak performance.
You should have 8 GB of RAM for basic TrueNAS operations with up to eight drives. Other use cases each have distinct RAM requirements:
Add 1 GB for each drive added after eight to benefit most use cases.
Add extra RAM (in general) if more clients connect to the TrueNAS system. A 20 TB pool backing many high-performance VMs over iSCSI might need more RAM than a 200 TB pool storing archival data. If using iSCSI to back up VMs, plan to use at least 16 GB of RAM for good 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 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.
To summarize the lengthy, Internet-wide debate on whether to use error-correcting code (ECC) system memory with OpenZFS and TrueNAS:
Most users strongly recommend ECC RAM as another data integrity defense.
However:
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 failures usually occur 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 beneficial.
Intel® limits 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 compresses and encrypts (optional) data and performs checksums.
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 power and ECC memory support.
A Xeon E5 CPU (or similar) is recommended for software-encrypted pools.
An Intel Ivy Bridge CPU or later is 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 becoming more popular thanks to the Ryzen and EPYC (Naples/Rome) lines. Support for these platforms is limited on FreeBSD and, by extension, TrueNAS CORE. However, Linux has more support, and TrueNAS SCALE should work with AMD CPUs without issue.
SHA Extensions in the x86 instruction set architecture support Secure Hash Algorithm family hardware acceleration.
Intel Goldmont (and later), Ice Lake (and later), and Rocket Lake (and later), as well as AMD Zen (and later) processors support the SHA instruction set.
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 use a single network interface by default, which can be challenging when you upgrade features like LACP aggregated networking.
The ideal solution is to have a dedicated subnet to access the TrueNAS web UI, but not all users have this luxury. The occasional visit to the hardware console is necessary for global configuration and system recovery.
The latest TrueNAS Mini and R-Series systems ship with full-featured, HTML5-based IPMI support on a dedicated gigabit network interface.
Power Supply Units
The top criteria to consider for a power supply unit (or PSU) on a TrueNAS system are:
Power capacity (in watts) for the motherboard and the number of drives it must support
Reliability
Efficiency rating
Relative noise
Optional redundancy to keep critical 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 integrates into the IPMI management system to provide real-time fan, temperature, and load information.
Most power supplies carry a certified efficiency rating known as an 80 Plus rating.
The 80 plus rating indicates the PSU loses the power drawn from the wall as heat, noise, and vibration instead of powering your components.
If a power supply needs to draw 600 watts from the wall to provide 500 watts of power to your components, it operates at 500/600 = ~83% efficiency.
The other 100 watts get lost as heat, noise, and vibration.
Power supplies with higher ratings are more efficient but also far more expensive.
Do some return-on-investment calculations if you are unsure what efficiency to buy.
For example, if an 80 Plus Platinum PSU costs $50 more than the comparable 80 Plus Gold, it should save you at least $10 per year on your power bill for that investment to pay off over five years.
You can read more about 80 Plus ratings in this post.
Uninterruptible Power Supplies
TrueNAS allows the system to comunicate with a battery-backed, uninterruptible power supply (UPS) over a traditional serial or USB connection to coordinate a graceful shutdown in the case of power loss.
TrueNAS works well with APC brand UPS, followed by CyberPower. Consider budgeting for a UPS with pure sine wave output.
Some models of SSD can experience data corruption on power loss.
If several SSDs experience simultaneous power loss, it could cause total pool failure, making a UPS a critical investment.
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 can create interoperability issues between the NIC, cable, and switch.
Virtualized TrueNAS
Finally, the ultimate TrueNAS hardware question is whether to use actual hardware or choose a virtualization solution.
At the heart of the TrueNAS design is OpenZFS. OpenZFS works best with physical storage devices. It is aware of their strengths and compensates for their weaknesses.
TrueNAS developers virtualize TrueNAS every day as part of their work, and it is intended only for use as a development environment.
While possible to deploy TrueNAS in a virtual environment, we do not recommend doing so for regular deployment of TrueNAS when storing production or critical data.
Virtualizing TrueNAS and using virtual disks for your zpool is fine for ad hoc proof-of-concept, but it is not a supported configuration and might result in data corruption.
When the need arises to virtualize TrueNAS (for ad hoc proof-of-concept):
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 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 other guest operating systems have.
Enable MAC address spoofing on virtual interfaces and enable promiscuous mode to use VNET jail and plugins.
3 - Installation Instructions
Guides users (including Enterprise customers) with first-time TrueNAS SCALE installations.
This section provides instructions for users that are installing TrueNAS SCALE the first time on their own system hardware, and for users that need to do a clean install of SCALE.
TrueNAS SCALE Enterprise customers should contact iXsystem Support for assistance with the initial set up and configuration of their systems.
The installation process covers installing SCALE using an iso. TrueNAS SCALE uses DHCP to provide the system IP address. After that, either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the SCALE UI to make network changes and complete the initial configuration.
Finally, it covers backing up your system configuration to a file and saving an initial system debug file.
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.
Then set up TrueCommand to manage your TrueSCALE systems.
To set up clusters of TrueNAS SCALE systems use TrueCommand to create and manage the cluster and nodes.
Installing SCALE: 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.
Installing SCALE Enterprise (HA): Provides a sequential process to complete the installation of a SCALE Enterprise (HA) dual controller system using an iso file and the SCALE UI.
Using the Console Setup Menu: Provides information on using the Console setup menu after installing TrueNAS SCALE from the iso file to configure network settings.
3.1 - Preparing for SCALE UI Configuration
Provides information you need to complete the SCALE configuration using the SCALE UI.
SCALE users installing and configuring SCALE on their own servers should use the information in this article to prepare for their SCALE system deployments.
Support options available to assist you include the TrueNAS community forums, blog, Discord, and tutorials documented in the TrueNAS Documentation Hub.
If you are not the administrator responsible for network access in your company, contact your network administrator for assistance.
If your company obtains network hardware and support from an Internet or cable service provider, contact them for assistance with where to obtain this information.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from .iso file.
IPMI Access
Intelligent Platform Management Interface (IPMI) servers provide access to servers and allow remote users to install software and configure or admninister systems at the console level, or as though you are in the room with the server when you are working remotely.
Not all companies have or use IPMI servers but companies with multiple server deployments and remote data centers likely do.
To provide for remote administration of your TrueNAS SCALE system, assign access through your IPMI server to the TrueNAS server.
To make this possible assign an IP address to use for access and set up administrator credentials (user name and password) to access the TrueNAS IPMI connections.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address or you can assign a static IP address. You must assign each network interface cards (NICs) installed in your system and wired to your network an IP address if you want to communicate over your network using the interfaces. To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed
DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses)
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network
Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed
Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE)
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP)
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
If you obtained network equipment and Internet service access from either an Internet or cable service provider, contact their support departments for assistance with network addresses.
For SCALE support or assistance refer to the TrueNAS community forums, blog, or the Discord, or the tutorials included in the TrueNAS Documentation Hub.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses either SMTP to send mail from SCALE to either administrator or designated individual email addresses for system alert notifications.
If you do not know this information and do not have a network administrator in your company, or if you are a home user, contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
Directory Service Access
This section does not apply to small companies with very few users or home deployments of SCALE.
If your company uses a directory server such as Active Directory or LDAP, TrueNAS SCALE works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap. Active Directory and LDAP configuration settings have similar requirements.
Active Directory and LDAP configuration settings have similar requirements.
Provide the following information to configure SCALE Active Directory access:
Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow SCALE to communicate with the server)
List of trusted domains SCALE should allow
Provide the following information to configure SCALE LDAP access:
Host name where the LDAP sever is located and where SCALE accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for SCALE to use for authentication
Not all companies uses Kerberos or IDmap but if your company does you might be asked to provide:
3.2 - Preparing for SCALE UI Configuration (Enterprise)
Provides information you need to complete the SCALE Enterprise configuration using the SCALE UI.
TrueNAS Enterprise
SCALE Enterprise customers, or those that purchased systems and service contracts from iXsystems, should use the information in this article to prepare for their SCALE system deployments.
The iXsystems Support department provides assistance with the configuration areas documented in this section.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Because there are many possible scenarios for network configurations, this section covers the basics of the access and information required to configure SCALE to work in your network environment.
If you are the individual tasked with installing and configuring the TrueNAS SCALE server but are not responsible for network services in your company, contact your network administrator to request they provision and verify new IP address assignments and provide the other information for access.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from .iso file.
IPMI Access
The Intelligent Platform Management Interface (IPMI) provides a way for system administrators to remotely access their TrueNAS system.
Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server.
TrueNAS Enterprise systems sold by iXsystems provide IPMI network ports, but other hardware might not have IPMI ports.
iXsystems requires access through your IPMI server to access the TrueNAS server to provide remote administration support.
To make this possible:
Assign an IP address to the IPMI port of each controller in the TrueNAS array.
If you have a High Availability (HA) system, the server is equipped with two controllers so assign two IP addresses, one for each controller.
Create and provide administrator credentials (user name and password) for access to the TrueNAS IPMI connections.
Configure the administrator credentials to access both IP addresses assigned to the HA system controllers.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address or you can assign a static IP address. You must assign each network interface cards (NICs) installed in your system and wired to your network an IP address if you want to communicate over your network using the interfaces. To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed
DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses)
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network
Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed
Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE)
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP)
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
TrueNAS Enterprise
The failover feature on TrueNAS SCALE Enterprise platforms with High Availability (HA) is currently incompatible with the network Spanning Tree Protocol (STP).
Please validate that STP is disabled on the network switch ports connected to the TrueNAS SCALE HA platform before enabling the failover feature.
If you have an HA system with two controllers, you must assign a total of three IP addresses:
A virtual IP for access to the UI no matter which controller is active
An IP address for the primary network port on controller A
An IP address for the primary network port on controller B
iXsystems Support can assist you with any questions you have with these network requirements.
Provide the information listed to iXsystems when requested to expedite configuring your system network settings.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses either SMTP to send mail from SCALE to either administrator or designated individual email addresses for system alert notifications.
Have your network administrators provide the SMTP addresses to allow TrueNAS to send emails from your network.
Directory Service Access
TrueNAS SCALE works with either Active Directory or LDAP directory servers, and it can also work with Kerberos and IDmap.
Active Directory and LDAP configuration settings have similar requirements.
Provide the following information to configure SCALE Active Directory access:
Domain name for where the Active Directory server is located
Authentication credentials for access to the Active Directory server (admin user name and password to allow SCALE to communicate with the server)
List of trusted domains SCALE should allow
Provide the following information to configure SCALE LDAP access:
Host name where the LDAP sever is located and where SCALE accesses it
Base and bind distinguished names (DN) and the bind password which are the authentication credentials
Kerberos realm and keytab information if used in your directory server deployment for SCALE to use for authentication
Not all companies uses Kerberos or IDmap but if your company does you might be asked to provide:
3.3 - Preparing for SCALE UI Configuration (Home Users)
Provides information home users need to complete the SCALE configuration using the SCALE UI.
SCALE users installing and configuring SCALE on their home server should follow the instructions in this article to prepare for their SCALE system deployment.
Support options available to assist you include the TrueNAS community forums, blog, Discord, and tutorials documented in the TrueNAS Documentation Hub.
Home users obtaining network equipment and Internet service access from either an Internet or cable service provider, can contact those support departments for assistance with SMTP and some network configuration addresses such as default gateways or DNS name server addresses.
Physical Access
When in the same location as the hardware designated for the TrueNAS installation, you can connect a monitor and keyboard to the system to do the initial installation and configuration.
An additional USB port is required when using a USB storage device to install TrueNAS from .iso file.
IPMI Access
Intelligent Platform Management Interface (IPMI) servers provide a way for system administrators to remotely access and control systems.
Through this remote access, administrators can install software, and configure or administer systems at the console level as though they are in the room with the server.
Home users with compatible hardware have the option to use an IPMI connection to remotely administer their system over the Internet.
To make this remote access possible you need an IPMI capable system or service:
Assign an IP address to access to the controller in the TrueNAS system.
Set up your administrator credentials (user name and password) for access through the TrueNAS IPMI connections.
Network Access
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address or you can assign a static IP address. You must assign each network interface cards (NICs) installed in your system and wired to your network an IP address if you want to communicate over your network using the interfaces. To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed
DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses)
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network
Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed
Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE)
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP)
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
Home users obtaining network equipment and Internet service access from either an Internet or cable service provider, can contact the provider support departments for assistance with network addresses.
For SCALE support or assistance refer to the TrueNAS community forums, blog, or the Discord, or the tutorials included in the TrueNAS Documentation Hub.
SMTP Access
Simple Mail Transfer Protocol (SMTP) service or servers allow for the transfer of electronic mail across an Internet connection.
TrueNAS uses either SMTP to send mail from SCALE to either the administrator or designated individual email addresses for system alert notifications.
Contact your Internet or cable service provider to obtain the SMTP addresses to allow TrueNAS to send emails from your network.
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).
TrueNAS Enterprise
SCALE Enterprise customers should receive their systems already installed and ready for UI configuration. If there are any issues with SCALE that requires you to install or re-install SCALE on your TrueNAS server, contact iXsystems Support for assistance.
Enterprise customers with High Availability (HA) systems should not attempt to re-install their systems on their own. The dual controller install process is complicated and the risk of causing serious network issues is high. Contact iXsystems Support for assistance!
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
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.
Performing PGP ISO Verification
You need an OpenPGP encryption application for this method of ISO verification.
Obtain an OpenPGP encryption application to use.
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.
Using 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
Freeware or online checksum utilities are available for Windows users.
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 have not disabled it or set it to Other OS, do it now so you can boot the install media.
Select the install device as the boot drive, exit, and reboot the system.
If the USB stick is not shown as a boot option, try a different USB slot.
Slots available for boot differs by hardware.
Using the TrueNAS Installer Console Setup
If you are doing a clean install from the SCALE .iso file as part of migrating from a different version of TrueNAS CORE or SCALE, or to recover from a serious issue that requires you to re-install SCALE from the .iso, have your network configuration information ready to use after the installation completes.
Also have your SCALE system configuration file and data backups handy so you can recover your system settings and import your data into the recovered SCALE clean-install system.
After the system boots into the installer, follow these steps.
Select Install/Upgrade.
Select the desired install drive.
Select Yes to proceed with a clean installation of TrueNAS SCALE from the .iso.
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.
Select Create Swap and press Enter.
Select option 1 Administrative user (admin) then OK to install SCALE and create the admin user account.
SCALE Bluefin 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.
We do not recommend selecting 3 Configure using Web UI.
Next, enter a password for the new admin user.
Select Boot via UEFI at the TrueNAS Boot Mode prompt, then select OK and press Enter to begin the installation.
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 UEFI 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 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 TrueNAS systems with additional applications installed inside the TrueNAS VM.
Enable MAC spoofing and promiscuous mode on the switch first, and then the port group the VM is using.
Jail Networking
If you have installed TrueNAS in VMware, you need functional networking to create a jail.
For the jail to have functional networking, you have to change the VMware settings to allow Promiscuous, MAC address changes, and Forged Transmits.
Setting
Description
Promiscuous Mode
When enabled at the virtual switch level, objects defined within all portgroups can receive all incoming traffic on the vSwitch.
MAC Address Changes
When set to Accept, ESXi accepts requests to change the effective MAC address to a different address than the initial MAC address.
Forged Transmits
When set to Accept, ESXi does not compare source and effective MAC addresses.
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:
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.
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 install drive.
Select Yes to proceed with a clean installation of TrueNAS SCALE from the .iso.
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.
Select Create Swap and press Enter.
Select option 1 Administrative user (admin) then OK to install SCALE and create the admin user account.
SCALE Bluefin 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.
We do not recommend selecting 3 Configure using Web UI.
Next, enter a password for the new admin user.
Select Boot via UEFI at the TrueNAS Boot Mode prompt, then select OK and press Enter to begin the installation.
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 configure SCALE network and general settings. Experienced users can use the Console Setup Menu to configure network settings, but if you are unfamiliar with the Console setup menu and how network configuration works, we recommend you use the SCALE UI to configure settings. TrueNAS SCALE uses DHCP to assign an IP address to the primary system interface and displays it at the top of the Console setup menu screen so you can log into the web UI.
Provides a sequential process to complete the installation of a SCALE Enterprise (HA) dual controller system using an iso file and the SCALE UI.
TrueNAS Enterprise
TrueNAS SCALE Enterprise is generally available with the release of SCALE 22.12.2.
Do not attempt to install Enterprise High Availability systems with TrueNAS SCALE until it becomes generally available or the deployment is experimental in nature.
Installing TrueNAS SCALE on High Availability (HA) systems is complicated and should be guided by Enterprise level support.
Contact iXsystems Support for assistance whenever attempting to install TrueNAS SCALE on Enterprise HA hardware.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Do NOT use Linux or CLI commands to recover or clean-install the SCALE iso file or configure any initial configuration settings!
Incorrect use of CLI commands can further disrupt your system access and can potentially do greater damage to your system. Proceed at your own risk.
Installing SCALE for an Enterprise (HA) System
This article outlines a procedure to do a clean install of a SCALE Enterprise High Availability (HA) systems using an iso file.
HA systems are dual controller systems with the primary controller referred to as controller 1 (sometimes also as controller A) and controller 2 (or controller B).
For best results, we recommend executing this procedure on both controllers at the same time.
You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off.
When controller 1 is completely configured, power on controller 2 to install TrueNAS and reboot the controller.
When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
SCALE includes features and functions to help guide with completing the configuration process after installing and getting access to the SCALE web interface.
Have this information handy to complete this procedure:
All the assigned network addresses and host names (VIP, controller 1 and 2 IP addresses)
Other network information including domain name(s), and DNS server, default gateway, alias or other static IP addresses
The IPMI access addresses for each controller and the administration credentials for IPMI access to these addresses
SCALE license file provided by iXsystems.
SCALE Storage Controller 1 (A) and 2 (B) serial numbers (refer to contracts or documentation provided with the system, or contact iXsystems Support and provide your contract number)
HA system controllers each have serial numbers, the lower number assigned is for controller 1 (e.g. of two controller serial numbers assigned A1-12345 and A1-12346, the A1-12345 is for controller 1 and A1-12346 is for controller 2).
When restoring after a clean install, also have ready:
Storage data backups to import into the Enterprise HA system.
System configuration file from the previous TrueNAS install.
Overview of the Installation Procedure
For best results, we recommend executing this procedure on both controllers at the same time.
You can simultaneously install using two USB flash drives inserted into the USB port for each controller (1 and 2) or by establishing an IPMI connection with each controller in separate browser sessions.
Alternately, install and configure controller 1 while keeping controller 2 powered off.
When controller 1 is completely configured, power on controller 2 to install TrueNAS and reboot the controller.
When controller 2 boots after installing, sync the system configuration from controller 1 to controller 2.
There are two ways to install the HA dual controller system to ensure controller 1 comes online as the primary controller:
Install both controller simultaneously beginning with controller 1, then immediately starting the install on controller 2.
Installing each controller individually to specific points in the installation process.
Simultaneous installation must start with controller 1 so it comes online first.
Installing each controller individually follows a particular method to ensure controller 1 comes online as the primary controller.
The sections in this article cover the primary steps as a simultaneous installation:
Download the iso file from the TrueNAS website and prepare the USB flash drives if not using IPMI for remote access.
Log into your IPMI system using the network address assigned to controller 1, and then establish a second connection with controller 2 in a new browser session.
Install SCALE using the iso file and select the Fresh Install option.
Install on controller 1, then immediately begin installing on controller 2 in the other IPMI session to simultaneously install SCALE on both controllers.
Disable DHCP, then enter the network settings to controller 1 using the Console Setup Menu.
Enter the IP address and netmask assigned to controller 1, then enter the global network settings for host name, domain name, and nameservers.
Use the SCALE UI for system configuration as it has safety mechanisms in place to prevent disrupting network access that could require you to repeat the clean install to access your system.
However, if you are experienced with the Console Setup Menu and are using it to configure network settings you can configure the rest of the controller 1 network settings with the Console setup menu.
Log into the SCALE UI for controller 1 to sign the EULA agreement and apply the system HA license.
Disable failover to configure the rest of the network settings and edit the primary network interface on controller 1, and then enable failover.
Complete the minimum storage requirement by adding or importing one pool on controller 1.
Sign in using the Virtual IP (VIP) address.
With controller 2 powered up, on controller 1 sync to peer to complete the install and make controller 2 the standby controller.
The sections that follow describe these steps in detail.
Overview of the Alternative Installation Process
This process of installing each controller sequentially has two methods:
Install and configure controller 1 up to the point where you are ready to sync to controller 2.
When complete, install controller 2 and reboot. After the console setup menu displays, switch back to controller 1 and sync to peer.
This synchronizes the completed configuration from controller 1 to controller 2 and keeps controller 1 designated as the primary controller.
Or
Begin installing controller 2 immediately after installing controller 1. When controller 2 finishes installing, power it off and keep it powered down.
When finished configuring controller 1, power up controller 2 and wait for it to finish booting up. Switch back to controller 1 and sync the configuration to controller 2.
This section provides an overview of the alternative method to clean install an HA system with controller 2 powered off while installing and configuring controller 1.
These steps are nearly identical to the section above but controller 2 is either powered off or not installed while you install and configure controller 1.
Use either the prepared USB flash drive inserted into a USB port for controller 1 or log into an IPMI session and install SCALE on controller 1.
Finish the installation and allow controller 1 to complete its first boot.
Use either the prepared USB flash drives inserted into a USB port for controller 2 or login into an IPMI session for controller 2 to install SCALE.
When the installation finishes, power down controller 2.
Configure the required network settings on controller 1 with the Console setup menu.
Log into controller 1 using the IP address assigned to controller 1.
Apply the HA license, sign the EULA, and complete the UI configuration to the point where you are ready to sync to peer on controller 1, but do not sync yet.
Power up controller 2 and wait for it to complete the boot process.
Log into controller 1, go to System Settings > Failover, and click Sync to Peer.
This synchronizes controller 2 with controller 1 and reboots controller 2. Controller 2 becomes the standby controller when it finishes rebooting.
If you are remote to the system and are installing through an IPMI connection you do not need to save the .iso file to a USB flash drive.
If you are physically present with the TrueNAS SCALE system, burn the .iso file to a USB flash drive and use that as the install media.
Using IPMI to Install the ISO on a Controller
Use this process to install the iso file on both controller 1 and controller 2. Best practice is to begin the install on controller 1, then immediately begin the install on controller 2.
Enter the IP address assigned to the controller 1 IPMI port into a web browser and log into your IPMI system with admin credentials.
Select Remote Control > iKVM/HTML5 to open the Console Setup window.
IPMI interfaces can vary but they generally have options for Remote Control and iKVM/HTML5 to open a console session on the platform.
Install the .iso file. Select the Virtual Media > CD-ROM image option in your IPMI system.
a. Enter the IP address of where you downloaded the .iso file into Share Host.
You might need assistance from your Network or IT department to obtain this address.
b. Enter the path to the .iso file.
For example, if you stored the file in an iso folder enter /iso/TrueNAS-SCALE-22.12.1.iso in Path to Image.
c. Click Save, then Mount. You should see the .iso file under Device 1 or the device name your IPMI configures.
Return to the Remote Control > iKVM/HTML5 window opened in step 2. Either use your keyboard or open the keyboard in the window then:
a. Type 8 to reboot controller 1 (also repeat for controller 2), and type y to confirm and reboot.
b. As the system reboots, be prepared to hit the F11 key when you first see the TrueNAS Open Storage splash screen.
Alternatively you can start clicking on the F11 key on the online keyboard until you see the TrueNAS SCALE Installer screen.
c. Select the UEFI: ATEN Virtual CDROM device from the boot list. The bootstrap loader begins. When it ends the SCALE installer opens.
Using the SCALE Installer
If you are doing a clean install from the SCALE .iso file to recover from an issue that requires you to re-install SCALE from the .iso, have your network configuration information ready to use for controller 1 after the installation completes. Do not configure network settings on controller 2.
Also have your SCALE system configuration file and data backups handy so you can recover your system settings and import your data into the recovered SCALE clean-install system.
Select Install/Upgrade.
Select the desired install drive.
Select Yes to proceed with a clean installation of TrueNAS SCALE from the .iso.
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.
Select Create Swap and press Enter.
Select option 1 Administrative user (admin) then OK to install SCALE and create the admin user account.
SCALE Bluefin 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.
We do not recommend selecting 3 Configure using Web UI.
Next, enter a password for the new admin user.
Select Boot via UEFI at the TrueNAS Boot Mode prompt, then select OK and press Enter to begin the installation.
Select OK after you see The TrueNAS installation on succeeded displays. The Console setup menu screen displays.
Enter 3 to Reboot System and immediately return to the IPMI Virtual Media > CD-ROM image screen to click Unmount. Click Save.
If you fail to unmount the iso image before the system completes the reboot, the bootstrap install continues in a boot loop.
After installing the SCALE .iso file on both controller 1 and 2 and finishing the TrueNAS SCALE Installer process, use the Console setup menu to configure the required network settings on controller 1 so it can access the SCALE UI.
TrueNAS SCALE single controller systems use the DHCP-assigned IP address for the primary network interface to access the SCALE UI to complete the rest of the network and other configuration settings.
However, HA systems with dual controllers must use static IP addresses.
To allow controller 1 to access the UI, you must disable DHCP and add the controller 1 static IP address and netmask as an alias on the primary network interface, and then enter the network settings for host name, domain name, default gateway, and the name servers (1 and 2).
You can configure the rest of the HA global network settings in the SCALE web UI.
To use the Console setup menu to configure required network settings on controller 1:
Use either Tab or the arrow keys to select the interface assigned as your primary network interface.
If you have more than one interface installed and wired to your network, the primary interface is typically eno1.
With the interface highlighted, press Enter to open the Update Network Interface screen.
Tab or arrow down to ipv4_dhcp and change it to no.
Tab or arrow down to the aliases setting and enter the static IP address for controller 1.
Tab or arrow down to Save, and then press Enter. A pending network changes notice displays with additional options.
Type a to apply the change, then p to make it persist.
Type q to return to the main Console setup menu.
Type 2 and then press Enter to open the Network Configuration screen.
SCALE UI Enterprise customers see the End User License Agreement (EULA) screen the first time they log in.
Sign the agreement to open the main SCALE Dashboard.
Apply the system license next.
Go to System Settings > General and click Add License on the Support widget. Copy your license and paste it into the License field, then click Save License.
The Reload dialog opens. Click Reload Now. Controller 1 restarts, and displays the EULA for controller 2. Sign the EULA agreement for controller 2, and add the license.
The controller 1 and 2 (or a and b) serial numbers display on the Support widget on the System Settings > General screen.
Configuring Network Settings
You must disable the failover service before you can configure network settings!
Only configure network settings on controller 1! When ready to sync to peer, SCALE applies settings to controller 2 at that time.
SCALE Enterprise (HA) systems use three static IP addresses for access to the UI:
VIP to provide UI access regardless of which controller is active.
If your system fails over from controller 1 to 2, then fails over back to controller 1 later you might not know which controller is active.
IP for controller 1. If enabled on your network, DHCP assigns only the controller 1 IP address.
If not able to use DHCP, you must change this to the static IP address your network administrator assigned to this controller.
IP for controller 2. DHCP does not assign the second controller an IP address.
Have your list of network addresses, host and domain names ready so you can complete the network configuration on controller 1 without disruption or system timeouts.
SCALE safeguards allow a default of 60 seconds to test and save changes to a network interface before reverting changes. This is to prevent users from breaking their network connection in SCALE.
To configure network settings on controller 1:
Disable the failover service.
Go to System Settings > Services locate the Failover service and click edit.
Select Disable Failover and click Save.
Edit the primary network interface to add failover settings.
Go to Network and click on the primary interface eno1 to open the Edit Interface screen for this interface.
First, enter the IP address for controller 1 into IP Address (This Controller) and select the netmask (CIDR) number from the dropdown list.
Next, enter the controller 2 IP address into IP Address (TrueNAS Controller 2).
Finally, enter the VIP address into Virtual IP Address (Failover Address).
Click Save
Click Test Changes after editing the interface settings.
You have 60 seconds to test and then save changes before they revert. If this occurs, edit the interface again.
Adding the Storage Pool
Create or import a storage pool from a backup. You must have at least one storage pool on controller 1.
After saving the storage pool, controller 2 automatically restarts. Wait until it comes back online before syncing controller 1 with controller 2.
For more information on how to create a new pool click here.
For more information on how to import a pool click here.
Syncing Controller 1 and 2
Turn the failover service back on. Go to System Settings > Services locate the Failover service and click edit.
Select Disable Failover to clear the checkmark and turn failover back on, then click Save.
The system might reboot. Use IPMI to monitor the status of controller 2 and wait until the controller is back up and running.
Log out of the controller 1 UI, and log in using the VIP address.
Sync controller 1 and 2.
With controller 2 powered on, but not configured, from controller 1 click Sync To Peer.
Select Reboot standby TrueNAS controller and Confirm, then click Proceed to start the sync operation.
This sync controller 2 with controller 1 which adds the network settings and pool to controller 2.
When the system comes back up, log into SCALE using the virtual IP address.
The main Dashboard displays two System Information widgets. In standard configurations by iXsystems, Controller 1 shows its serial number and a host name that includes the letter a. Controller 2 is labeled as Standby Controller and shows its serial number and a host name that includes the letter b.
Take note of this information.
If controller 2 comes on line as the primary and controller 1 as the standby, you installed and configured these controllers incorrectly.
Go to System Settings > Failover, clear the Default TrueNAS Controller option, and click Save.
The system reboots and fails over to the current standby controller (in this case, to controller 1).
Log back into the UI with the VIP address, go to System Settings > Failover and select Default TrueNAS Controller to make controller 1 the primary controller.
and then select Sync to Peer. SCALE makes controller 2 the standby controller and syncs the configuration on controller 1 to controller 2.
Click Save.
Provides information on using the Console setup menu after installing TrueNAS SCALE from the iso file to configure network settings.
The Console setup menu (CSM) displays at the end of the iso installation process and after the system boots up.
You can access this menu to administer the TrueNAS system if it has a keyboard and monitor.
By default, TrueNAS does not display the Console setup menu when you connect via SSH or the web shell.
The admin user, the root user (if enabled), or another user with root permissions can start the Console setup menu by entering this command:
For network configuration options 1, 2, and 3, we recommend using the SCALE UI to configure network interfaces, as it has safeguards to prevent breaking network access to SCALE.
1) Configure network interfaces
Use this to configure the primary network interface with a static IP. This is for switching away from the DHCP-assigned IP address TrueNAS provides when the system boots after installing SCALE.
Also, use this to set up other network interfaces or to add alias IP addresses for the primary interface.
2) Configure network settings
Use this to set up the network default gateway, host name, domain, IPv4 gateway and DNS name servers.
Configured options display in the Global Configuration widget in the web UI Network screen.
3) Configure static routes
Use this to set up static IP routes, but this is not required as part of the initial configuration setup.
4) Change local administrator password
Use to change the administrator user password.
If you selected option 1 on the iso installer menu, you already configured the admin user and password.
Use can use this to change the admin password before you log into the SCALE UI.
This is not the password for the root user in the CLI or the root user login password for the web UI.
The root user password is disabled by default. You can turn on the root user password in the UI, but we do not recommend doing that.
5) Reset configuration to defaults
Use to wipe all system configuration settings and return the system to a fresh install state.
6) Open TrueNAS CLI Shell
Use to start a shell for running TrueNAS commands, or use the SCALE UI System Settings > Shell.
Type exit to leave the shell.
7) Open Linux Shell
Use to start a shell window for running Linux CLI commands.
Configuration changes made here are not written to the database and are reset on each system boot.
We do not recommend using the Linux shell unless you are an advanced user. Type exit to leave the shell.
8) Reboot
Use to power down, then automatically power on the system.
9) Shut down
Use to power down the system.
Console setup menu options can change with software updates, service agreements, etc.
During its first boot, TrueNAS attempts to connect to a DHCP server from all live interfaces.
If it receives an IP address, the Console setup menu displays it under The web user interface is at: so you can access the SCALE web UI.
You might be able to access the web UI using a hostname.domain command at the prompt (default is truenas.local) if your system:
Does not have a monitor.
Is on a network that supports Multicast DNS (mDNS).
Console Setup Menu Network Settings
You can either use SCALE UI or the Console setup menu to configure your network settings for the primary network interface or other interfaces such as a link aggregate (LAGG) or virtual LAN (VLAN), or aliases for an interface, and to configure other network settings such as the default gateway, host name, domain, and the DNS name servers, or add static routes.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the SCALE UI to configure your network interfaces and other network configuration settings.
The TrueNAS SCALE UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS SCALE if you make a mistake with network interface settings.
Enter 1 to display the Configure Network Interfaces screen where you can select the interface settings.
Follow the instructions on the screen to configure an IP for a network interface.
Type n to open the new interface screen or press Enter to edit the existing interface.
You can enter aliases for an interface when you create a new one or edit an existing interface.
Static IP addresses are used to set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access.
Use aliases to add multiple internal IP addresses, representing containers or applications hosted in a VM, to an existing network interface without having to define a separate network interface.
In the UI, you can add aliases when you add an interface or edit an existing interface. Use the Add button in the Aliases widget to add a static IP address. Press Add again to add each additional alias.
From the Console Setup Menu, select option 1 to configure network settings and add alias IP addresses.
Type q to to return to the main Console setup menu screen.
Enter 2 to display the Network Settings screen where you can set up the host name, domain, default gateway and name servers.
Static IP addresses are used to set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access.
Use aliases to add multiple internal IP addresses, representing containers or applications hosted in a VM, to an existing network interface without having to define a separate network interface.
In the UI, you can add aliases when you add an interface or edit an existing interface. Use the Add button in the Aliases widget to add a static IP address. Press Add again to add each additional alias.
From the Console Setup Menu, select option 1 to configure network settings and add alias IP addresses.
Configuring Required Network Settings
TrueNAS uses DHCP to assign the IP address required to access the SCALE UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by SCALE, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide iXsystems Support when they guide you through your configuration.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure SCALE.
To use the Console setup menu to change the network interface IP address, type 1 and then press Enter to open the Configure Network Interfaces screen.
Use either Tab or the arrow keys to select the interface to use as your primary network interface if you have more than one interface installed and wired to your network.
Type in the IP address then use either Tab or the arrow keys to move through the menu and down to select Save, and then press Enter.
After saving, return to the main Console setup menu by entering q.
To configure the default gateway, host name, domain and DNS name severs using the Console setup menu type 2 and then press Enter to open the Network Settings screen.
To configure network settings in the SCALE UI, enter the IP address displayed on the Console setup menu screen in a browser URL field and press Enter.
Log in with the admin user name and the password you set for the administration user during the iso installation process, and then go to Network and or edit and interface or global network configuration settings.
For home users, you have a few options to allow Internet access using TrueNAS SCALE:
Use 8.8.8.8 as the DNS nameserver address
Use your ISP provider DNS servers (contact them for assistance with these addresses)
SCALE has implemented rootless login, making the admin user the default account, and has disabled the root password by default.
You can change the admin user password in the UI or from the Console setup menu.
You can set and enable the root user password in the UI, but for security hardening, we recommend you leave it disabled.
Changing the admin user (or root if you have not created the admin user) password disables 2FA (Two-Factor Authentication).
Disabling a password in the UI prevents the user from logging in with it. When both root and local admin user passwords are disabled and the web interface session times out, a temporary sign-in screen allows logging in.
Immediately go to the Credentials > Local User screen, select the admin user, and then Edit to re-enable the password.
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 Pool to re-import pools.
Enter 5 in the Console setup menu, then enter y to reset the system configuration. The system reboots and reverts to default settings.
Completing your System Setup
After setting up network requirements, log into the web UI to complete your system setup by:
See the Software Status page for iXsystems’ software version recommendations based on user type.
Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new TrueNAS SCALE major version.
System configuration files generated from releases before 22.12.4 (Bluefin) are not compatible with 23.10 (Cobia).
When available, update the system to 22.12.4 (Bluefin), resolve any migrations from deprecated services to replacement apps, and download a fresh system configuration file before attempting to upgrade.
Upgrading from the Web Interface
Log in to the SCALE web interface and go to System Settings > Update.
The Update Screen displays the current active update train. For more information on other available trains, see Release Schedules.
When a new maintenance version is available from the current train, TrueNAS SCALE stages available updates.
Click Apply Pending Update to install it.
After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
Alternately, upload an .update file and perform a manual update.
Click Install Manual Update File.
The Save configuration settings from this machine before updating? window opens.
Click Export Password Secret Seed then click Save Configuration.
The Manual Update screen opens.
Click Choose File to locate the update file on the system.
Select a temporary location to store the update file. Select Memory Device or select one of the mount locations on the dropdown list to keep a copy in the server.
Click Apply Update to start the update process. A status window opens and displays the installation progress. When complete, a Restart window opens.
Click Confirm, then Continue to restart the system.
Uploading an .update file from another train and manually updating switches the system between train types.
Changing trains is a one-way operation!
Do not change to a prerelease or nightly release unless the system is intended to permanently remain on early versions and is not storing any critical data.
Upgrading when Apps are Deployed
Upgrading from Bluefin to Cobia when applications are deployed is a one-way operation.
You cannot return to or roll back to an earlier SCALE release by simply activating an earlier release boot environment.
You also cannot easily roll back app on-disk data after updating the structure to Cobia.
After upgrading to Cobia, deployed apps do not work in the earlier release boot environment because the path to system dataset/ix-applications/docker does not exist in Cobia and is not restored when rolling back.
When apps are deployed in an earlier SCALE major version, you must take snapshots of all datasets that the deployed apps use, then create and run replication tasks to back up those snapshots.
After rolling back to the earlier version from 23.10 (Cobia), these snapshots are used to restore the applications datasets to their pre-upgrade condition and allow previously installed apps to resume normal functionality.
At minimum, you need pre-upgrade snapshots of the ix-applications dataset and a recursive snapshot of ix-applications to get the docker dataset, and then snapshots of all datasets apps use as host paths.
Without these snapshots, to downgrade to Bluefin requires deleting the app(s) and redeploying it/them.
It is recommended to use replication tasks to copy snapshots to a remote server used for backups of your data.
If you do not have a remote server to store backup snapshots, you can create a new pool and dataset on the system for local replications, but this is not a recommended general backup strategy.
When you rollback the TrueNAS SCALE system from Cobia to an earlier SCALE major version, copy the snapshots from the remote backup server to the local system in a new temporary dataset.
Create a new dataset on the same pool as the ix-applications dataset (the pool apps use).
Before Upgrading
Verify your Bluefin apps are running (not stopped or in the deploying state), and that you have access to your data and the application web portals.
Create and run replication tasks to a remote server.
See Setting Up a Remote Replication Task for more information.
Before upgrading to Cobia, create and replicate snapshots for:
The ix-applications dataset to restore the migration JSON files to the earlier version.
A recursive replication of the ix-applications dataset to see the docker snapshot.
Snapshots of any datasets that deployed apps use for storage, such as the MinIO app data dataset.
If a Bluefin app uses host path(s) to existing datasets, such as with the MinIO and the /data dataset, create and run remote replication tasks for these datasets.
If you nested these datasets for apps under a parent dataset, set up a recursive remote replication of the parent dataset to create the snapshots of all the nested child datasets the apps use.
Upgrade to Cobia and save the configuration file. This is always recommended so you can restore your system configuration if necessary.
Rolling Back to an Earlier SCALE Release
Do not replicate remote backup snapshots into the ix-applications dataset!
Create a dataset or use an existing dataset on the same pool as the ix-applications dataset to hold these snapshots.
Select the earlier release boot environment, make it the active boot environment, then reboot the system.
See Managing Boot Environments for more information.
Go to the remote system and create and run a replication task to copy the snapshots back to the system you rolled back to an earlier SCALE release.
Alternately, create a Pull replication task on the rolled-back system to bring the snapshots from the remote system to the local system.
Replicate each snapshot: the ix-applications, ix-applications/docker, and all snapshots of datasets set up as host paths in an application.
When moving a snapshot from a different pool on the same server, replicate to a dataset on the same pool as the ix-applications dataset (for example, tank/repsnaps if ix-applications is in the tank pool).
Go to the location of the snapshots, then:
a. Roll back to the ix-applications snapshot taken before the upgrade. This updates the migration JSON files to the pre-upgrade version of the files.
b. Locate the ix-applications/docker snapshot, click on it to expand it, then click Clone to Dataset.
Rename the dataset to poolname/ix-applications/docker to create the missing docker dataset from this snapshot.
c. Roll back the snapshots for any dataset used as a host path in an application to the snapshots taken before the upgrade.
Go to Shell or open an SSH session and verify the docker dataset exists. Enter:
cd /mnt/poolname/ix-applications
ls
Where poolname is the name of the pool assigned as the pool for applications to use and with the ix-applications dataset.
The command output now show the docker dataset.
Reboot the system.
The applications now show on the Applications > Installed Applications screen.
It takes a while for apps to return to the Active state.
After doing the above, if the applications do not show on the Installed Applications screen, either open an SSH session or go to Shell, cd to the ix-applications dataset location, and remove the app_migrations.json and migrations.json files.
This command is destructive and could interfere with automatic updating for the currently installed applications.
Enter at the prompt:
sudo rm app_migrations.json
When prompted, enter the admin password.
Repeat the command for the migrations.json file.
Reboot the system, then return to the Applications > Installed Applications screen.
The applications are now visible.
Wait for the apps to return to the Active state.
Migrating from CORE to SCALE
SCALE is a new and maturing software.
CORE systems with High Availability enabled (HA) can not be upgraded to SCALE with HA.
Migrating from CORE to SCALE is not recommended when custom modifications have been made to the system database.
If any such modifications are present in CORE, these must be reverted before attempting a migration to SCALE.
CORE users should always exercise caution and back up their data and system configuration before starting an upgrade.
Systems with TrueNAS CORE major version 12.0 or earlier must update to the latest CORE 13.0 release (e.g. 13.0-U5) prior to migrating to SCALE.
When appropriate, a CORE to SCALE migration is performed with an .iso and USB stick and preserves much of your existing CORE configuration.
See Migrating from CORE for the USB migration process.
5 - CORE to SCALE Migrations
TrueNAS CORE to TrueNAS SCALE migrations.
This section provides information and instructions for CORE users wanting to migrate to SCALE.
TrueNAS Enterprise
High Availability (HA) systems cannot migrate directly from CORE to SCALE.
Enterprise customers with HA systems should contact iXsystems Support before attempting any migration.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Migrating TrueNAS from CORE to SCALE is a one-way operation.
Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-Ux release before attempting to migrate from CORE to SCALE.
SCALE Bluefin deprecates and Cobia removes the built-in DDNS, OpenVPN server and client, rsync, S3, and TFTP service.
The WebDAV service and share feature are also deprecated in Bluefin and removed in Cobia.
New applications are available in Bluefin to serve as replacements for the functions these services provided.
To migrate from CORE to SCALE Cobia, first upgrade to and migrate from the latest CORE release to the latest release of SCALE 22.12 (Bluefin).
While running SCALE Bluefin, take the necessary steps to transition from these deprecated services to the applications that replace them, then upgrade to SCALE 23.10 (Cobia).
The replacement applications are available in SCALE 22.12 and 23.10.
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.
After migration, it is strongly recommended to review each area of the UI that was previously configured in CORE.
Migration Articles
Preparing to Migrate: Guides CORE users through preparation elements and steps before beginning the one-way CORE to SCALE migration process.
Migrating TrueNAS CORE to SCALE: Provides instructions on migrating from TrueNAS CORE to SCALE. Migration methods include using an ISO or manual update file.
Component Naming: Provides information on disk and interface naming changes related to the change from FreeBSD storage and sharing in CORE to Linux in TrueNAS SCALE.
ZFS Feature Flags Removed: Provides information on the removal of the ZFS feature flag merged into OpenZFS on June 29, 2021.
5.1 - Preparing to Migrate
Guides CORE users through preparation elements and steps before beginning the one-way CORE to SCALE migration process.
TrueNAS Enterprise
High Availability (HA) systems cannot migrate directly from CORE to SCALE.
Enterprise customers with HA systems should contact iXsystems Support before attempting any migration.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Migrating TrueNAS from CORE to SCALE is a one-way operation.
Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-Ux release before attempting to migrate from CORE to SCALE.
What can or cannot migrate?
Although TrueNAS attempts to keep most of your CORE configuration data when upgrading to SCALE, some CORE-specific items do not transfer.
These are the items that don’t migrate from CORE:
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.
Malformed certificates.
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.
CORE plugins and jails. Save the configuration information for your plugin and back up any stored data.
After completing the SCALE install, add the equivalent SCALE application using the Apps option.
If your CORE plugin is not listed as an available application in SCALE, use the Launch Docker Image option to add it as an application and import data from the backup into a new SCALE dataset for the application.
NIS data.
System tunables.
ZFS boot environments.
AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
CORE netcli utility. A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI.
By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.
SAS multipath is not supported in TrueNAS SCALE.
TrueNAS CORE account names beginning with a number are not supported in TrueNAS SCALE.
Usernames in SCALE must begin with a letter or an underscore.
Before attempting a CORE to SCALE migration, review the local user accounts and rename or replace any accounts that begin with a numeric character (0-9).
TrueNAS 13.X and earlier support VMs with UEFI and GRUB bootloaders.
TrueNAS 22.02 and later does not support the GRUB bootloader.
VMs configured with the UEFI bootloader can migrate.
VMs configured with the GRUB bootloader are unable to migrate.
It is important for all users to double-check the VM configuration and network interface settings before starting the VM.
Init/shutdown scripts transfer, but can break. Review them before use.
Preparing for Migration
Read this article before you attempt to migrate your CORE system to a SCALE major version.
We strongly recommend not using USB flash drives or USB-attached drives for backups as these can have issues, including with recovering backed up files.
For more information on using USB drives and devices in general, read the CORE Hardware Guide.
If you must use a USB type device, verify you can access files on the device before you upgrade/migrate to SCALE.
TrueNAS Enterprise
CORE Enterprise customers are encouraged to contact Support for assistance with the process of moving from CORE to SCALE, especially customers with HA systems.
Upgrade your CORE system to the most recent publicly-available CORE major maintenance release version.
TrueNAS systems on 12.0x or earlier should upgrade to the latest CORE 13.0 release (e.g. 13.0-U6.1 or newer) prior to migrating to SCALE.
CORE systems at the latest 13.0 release can use the iso upgrade method to migrate to SCALE.
Migrate GELI-encrypted pools to a non-GELI-encrypted pool before upgrading from CORE 12.0x or earlier releases!
Verify the root user is not locked.
Go to Accounts > Users, select the root user and click Edit to view current settings and confirm Lock User is not selected.
Write down, copy, or take screenshots of settings to use in the event of a post-upgrade/migration issue or to duplicate in SCALE.
Use the checklist below to guide you through this step:
System dataset - Identify your system dataset. If you want to use the same dataset for the system dataset in SCALE, note the pool and system dataset.
When you set up the first required pool on SCALE import this pool first.
VMs - If you have virtual machines configured in CORE, write down or screenshot network and other setting information.
Plugins or jails - Plugins and jails do not migrate. Record settings for each plugin/jail and back up the data associated with each.
CAs, certificates, CSRs - If you added certificate authorities, certificates, or certificate signing requests to CORE, they should migrate with the system config file, but as a precaution against possible malformed certificates copy private and public certificate keys and save each, then copy or screenshot all CA, certificate, and CSR setting. Make sure you have backed-up copies of certificates used in CORE to import or configure in SCALE.
Usernames beginning with (0-9) - Review local user account names and rename or replace these with a letter or underscore before migrating.
Tunables on CORE - SCALE does not use Tunables the way CORE does. SCALE allows adding script configurations on the System Settings > Advanced screen, using the Sysctl widget.
Init/shutdown scripts - If using init/shutdown scripts in CORE, copy them or take a screenshot to add them to SCALE.
Cron jobs - If configured in CORE, copy or use screenshots of cron job scripts if you want to add the same jobs in SCALE.
Global self-encrypting drive (SED) Password - Unlock these drives in CORE before you clean install SCALE. Write down the SED password configured in CORE to use in SCALE.
Credentials - Copy or write down the credentials for SSH connections and keypairs, and any cloud service backup providers configured in CORE if you do not have the credential settings saved in other files kept secured outside of CORE.
Data protection tasks - Write down or take screenshots of replication, periodic snapshot, cloud sync, or other task settings to reconfigure these in SCALE if you want to duplicate these tasks.
Write down or take screenshots of your network configuration information.
Capture the global network settings, interfaces (LAGG, VLAN, bridge settings), static IP addresses, and aliases.
FreeBSD and Linux use different nomenclature for network interfaces, bridges, LAGGs, and VLANs.
Because of the difference, network settings can either get lost or not transfer which means you have no network connectivity.
You can find interface names in the CORE UI on the Network > Interfaces screen.
When using a TrueNAS Enterprise system from iXsystems, refer to the network port ID manuals of your TrueNAS Systems to find the network port assignments in TrueNAS SCALE.
When using custom hardware for TrueNAS, refer to the manual or documentation provided with your system or locate this information on your server hardware and take note of it.
If there are issues after a clean install of SCALE from an iso file or you are not using DHCP for network and interface configuration, use the information from your CORE settings to configure your SCALE network settings and to reconfigure your static IPs or aliases.
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address or you can assign a static IP address. You must assign each network interface cards (NICs) installed in your system and wired to your network an IP address if you want to communicate over your network using the interfaces. To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed
DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses)
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network
Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed
Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE)
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP)
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
Make sure S3 MinIO data is backed up as a precaution. The migration process from the S3 service requires first migrating to the MinIO plugin in TrueNAS CORE, migrating from CORE to SCALE, then installing the SCALE MinIO app and importing S3 data.
Back up any critical data.
Download your system configuration file and a debug file.
After updating to the latest publicly-available release of CORE and making any changes to CORE user accounts or any other settings download these files and keep them in a safe place and where you can access them if you need to revert to CORE with a clean install using the CORE iso file.
After completing the steps that apply to your CORE system listed above, download the SCALE ISO file and save it to your computer.
Burn the iso to a USB drive (see Installing on Physical Hardware in Installing SCALE) when upgrading a physical system.
Deprecated Services in SCALE
The built-in services listed in this section are available in CORE, but deprecated in SCALE 22.12.3 (Bluefin) and removed in later SCALE releases.
They require attention before attempting to migrate to SCALE.
Each of the sections has information that can help you determine the best steps forward to secure any critical data before attempting to migrate from CORE to SCALE.
They provide details on transitioning from that service to an application with the functionality of the deprecated service.
TrueNAS SCALE has apps you can deploy as replacements for these services.
SCALE 24.04 provides the option to force an upgrade without converting deprecated services to apps.
The force option is not recommended for the S3 service as forcing the upgrade results in losing access to and the ability to recover the MinIO S3 data.
Review and write down or take screenshots of your Dynamic DNS service provider, domain, IP address, port number, URL, and credential (username and password) settings to use when you reconfigure in a replacement app.
If establishing a new provider, create the user account before proceeding. Otherwise, use the existing provider details.
To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user.
Note the UID and GID for this new user to enter in the application configuration screen.
Install a replacement application such as DDNS-Updater using the CORE service settings from your notes.
SCALE suggests other applications to consider other than DDNS-Updater application.
Review your OpenVPN client and server service settings.
Take note of all certificate, device type, port, protocol, TLS crypt authentication, and additional parameter settings to use in a replacement app.
A certificate configured on CORE should migrate to SCALE, but as a precaution, record the certificate authority (CA) and certificate settings, and make a copy of the private and public keys the CA and certificate uses.
Install a replacement application such as WG Easy using the CORE service settings from your notes.
SCALE suggests other applications to consider other than the WG Easy VPN application.
Review your rsync and module service settings.
Take note of all host path, access mode type, number of simultaneous connections, user and group IDs, allow and deny host addresses, and any auxiliary parameter settings.
Before you configure a new rsync application like Rsync Daemon (Rsync-d), validate that it is needed.
When rsync is configured externally with SSH or using an rsync task in Data Protection > Rsync Tasks, and when Rsync Mode is set to SSH, the deprecated rsync service is not used or necessary for rsync to function.
Install a replacement application such as Rsync Daemon using the CORE service settings from your notes.
SCALE suggests other applications to consider other than the Rsync Daemon application.
You must migrate your S3 service and data before you upgrade or migrate from CORE to SCALE!
If you have the S3 service configured in CORE, you must first migrate to the MinIO plugin.
After migrating from CORE to SCALE and then installing the SCALE MinIO app, you can import S3 data from the CORE plugin to the SCALE app.
Review your S3 service settings.
Take note of the credentials (Access Key and Secret Key), and data storage volume and host path.
If a certificate other than the default freenas_default is used, take note.
A certificate configured on CORE should migrate to SCALE, but as a precaution, record the certificate authority (CA) and certificate settings, especially any private and public keys the certificate uses.
Follow the migration instructions provided in Migrating MinIO Data from CORE to SCALE.
This is an involved and time-consuming process with specific requirements. The amount of data being migrated determines how long this process takes.
Review your TFTP service settings.
Take note of all directory, host, auxiliary parameter, permission, and credential (username and password) settings.
To grant access to a specific user (and group) other than using the default admin user UID and GID, add the new non-root administrative user.
Note the UID and GID for this new user to enter in the application configuration screen.
To use a specific dataset or storage volume for files, create any new dataset in Bluefin before installing the application.
Install the replacement application such as TFTP Server (TFTP-HPA) using the CORE service settings from your notes.
SCALE suggests other applications to consider other than the TFTP Server (TFTP-HPA) application.
Disable both the WebDAV share and service.
Also disable the Start Automatically option to prevent the service from re-enabling after a system restart.
Review any existing WebDAV service authentication settings.
Take note of all IP addresses, port numbers, URLs and credentials (username and password).
Remove any existing WebDAV shares. Go to Shares > WebDAV and use Edit to view any existing configurations.
Take note of the share name, path, and read only settings. Delete the WebDAV share configuration.
In SCALE Bluefin:
To grant access to a specific user (and group) other than using the default admin user UID and GID, add a new non-root administrative user for the share(s).
Note the UID and GID for this new user to enter in the application configuration screen.
After disabling the WebDAV service and clearing any existing share configurations from the Shares > WebDAV screen in Bluefin, install the WebDAV application to recreate your shares using the CORE service settings from your notes. Use the webdav user and group in control, and the UID and GID (666) in the application.
5.2 - Migrating TrueNAS CORE to SCALE
Provides instructions on migrating from TrueNAS CORE to SCALE. Migration methods include using an ISO or manual update file.
Migration Overview
This article provides information and instructions for migrating non-Enterprise TrueNAS CORE to SCALE.
TrueNAS Enterprise
TrueNAS Enterprise customers should consult with iXsystems Support before attempting migrate to TrueNAS SCALE.
The process requires an extended maintenance window, requires executing steps in the correct order to prevent issues with system configuration and operation, and additional system review post-migration to catch and correct any configuration issues.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Review the Migration Preparation article for detailed recommendations and preparation steps before attempting to migrate from CORE to SCALE.
Depending on system configuration, migrating from CORE to SCALE can be more or less complicated.
Root is the system administration account for CORE and the Angelfish and early Bluefin releases of SCALE.
Users migrating from CORE to SCALE or from the pre 22.12.3 release of SCALE Bluefin must manually create an admin user account.
Only fresh installations using an iso file provide the option to create the admin user during the installation process.
SCALE Bluefin systems with only the root user account can log in to the TrueNAS web interface as the root user and then create the admin account.
After logging in as root, TrueNAS alerts you to create the local administrator account.
As part of security hardening and to comply with Federal Information Processing standards (FIPS), iXsystems plans to completely disable root login in a future release.
System administrators should create and begin using a new admin user.
Migration Methods
TrueNAS Enterprise
High Availability (HA) systems cannot migrate directly from CORE to SCALE.
Enterprise customers with HA systems should contact iXsystems Support before attempting any migration.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Migrating TrueNAS from CORE to SCALE is a one-way operation.
Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-Ux release before attempting to migrate from CORE to SCALE.
Clean Install
You can migrate from CORE to SCALE with a clean install using an iso file.
With a clean SCALE install, you need to reconfigure your CORE settings in SCALE and import your data.
Follow the instructions in the Install articles.
When TrueNAS SCALE boots, you might need to use the Shell to configure networking interfaces to enable GUI accessibility.
After logging in to the TrueNAS SCALE UI, use a system configuration file to restore the system settings to the SCALE installation and import the data storage pools.
Manual Update
Some CORE 13.0 releases can migrate using the CORE UI Upgrade function using a SCALE update file downloaded from the website.
To use this method, you must upgrade to the latest maintenance release.
Earlier releases of CORE must upgrade to 13.0 and then the latest maintenance release U6.1 to use this method.
If this process fails, retry using the iso file method above.
Confirm that the TrueNAS CORE system is on the latest public release, 13.0-U6.1 or newer.
Click CHECK FOR UPDATES in the System Information card on the Dashboard or go to System > Update.
Click INSTALL MANUAL UPDATE FILE.
Click SAVE CONFIGURATION to download a backup file that can restore the system configuration in the event something goes wrong with the migration.
Select a Temporary Storage Location (either Memory Device or a Pool) for the manual update file.
Click Choose File and select the TrueNAS-SCALE.update file you downloaded.
Then click APPLY UPDATE.
After the update completes, reboot the system if it does not reboot automatically.
After TrueNAS SCALE reboots, sign in with the root user credentials used in CORE.
Uploading the CORE config file deletes the admin user account created during a clean install and therefore requires you to recreate it.
After booting and gaining access to the UI, go to System Settings > General and upload the system config file.
This migrates your CORE settings, imports your pools, shares, etc. into SCALE.
After uploading the config file, review each area of the UI previously configured in CORE to validate pools imported and settings migrated correctly. Begin with your network settings.
Use the information gathered during your preparation to migrate to restore settings, tasks, VMs, credentials, etc. not present in SCALE after uploading the config file.
Recreating the Admin User Account
Root is the system administration account for CORE and the Angelfish and early Bluefin releases of SCALE.
Users migrating from CORE to SCALE or from the pre 22.12.3 release of SCALE Bluefin must manually create an admin user account.
Only fresh installations using an iso file provide the option to create the admin user during the installation process.
SCALE Bluefin systems with only the root user account can log in to the TrueNAS web interface as the root user and then create the admin account.
After logging in as root, TrueNAS alerts you to create the local administrator account.
As part of security hardening and to comply with Federal Information Processing standards (FIPS), iXsystems plans to completely disable root login in a future release.
System administrators should create and begin using a new admin user.
5.3 - Preparing to Migrate TrueNAS CORE to SCALE (Enterprise HA)
Provides information for CORE Enterprise (HA) users planning to migrate to SCALE and what you need to know and have ready before beginning the one-way process.
TrueNAS Enterprise
High Availability (HA) systems cannot migrate directly from CORE to SCALE.
Enterprise customers with HA systems should contact iXsystems Support before attempting any migration.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Migrating TrueNAS from CORE to SCALE is a one-way operation.
Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-Ux release before attempting to migrate from CORE to SCALE.
TrueNAS Enterprise
SCALE Bluefin deprecates and SCALE Cobia removes the built-in DDNS, OpenVPN server and client, rsync, S3, and TFTP services.
The WebDAV service and share feature are also deprecated in Bluefin and removed in Cobia.
New applications are available in SCALE Bluefin to serve as replacements for the functions provided by these services.
To avoid any potential service outages, Enterprise customers with licensed TrueNAS systems are prevented from upgrading from SCALE 22.12.3 (or later) to SCALE 23.10 unless the deprecated services have been replaced and/or disabled.
Enterprise customers can contact iXsystems Support for assistance migrating from deprecated services.
What can or cannot migrate?
Although TrueNAS attempts to keep most of your CORE configuration data when upgrading to SCALE, some CORE-specific items do not transfer.
These are the items that don’t migrate from CORE:
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.
Malformed certificates.
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.
CORE plugins and jails. Save the configuration information for your plugin and back up any stored data.
After completing the SCALE install, add the equivalent SCALE application using the Apps option.
If your CORE plugin is not listed as an available application in SCALE, use the Launch Docker Image option to add it as an application and import data from the backup into a new SCALE dataset for the application.
NIS data.
System tunables.
ZFS boot environments.
AFP shares also do not transfer, but migrate into an SMB share with AFP compatibility enabled.
CORE netcli utility. A new CLI utility is used for the Console Setup Menu and other commands issued in a CLI.
By default, any TrueNAS user account with netcli as the chosen Shell updates to use the nologin option instead. See the Users Screens reference article for descriptions of all Shell options.
SAS multipath is not supported in TrueNAS SCALE.
TrueNAS CORE account names beginning with a number are not supported in TrueNAS SCALE.
Usernames in SCALE must begin with a letter or an underscore.
Before attempting a CORE to SCALE migration, review the local user accounts and rename or replace any accounts that begin with a numeric character (0-9).
TrueNAS 13.X and earlier support VMs with UEFI and GRUB bootloaders.
TrueNAS 22.02 and later does not support the GRUB bootloader.
VMs configured with the UEFI bootloader can migrate.
VMs configured with the GRUB bootloader are unable to migrate.
It is important for all users to double-check the VM configuration and network interface settings before starting the VM.
Init/shutdown scripts transfer, but can break. Review them before use.
Before Migrating to SCALE
You cannot directly migrate a TrueNAS Enterprise High Availability (HA) system from CORE to SCALE!
Instead, the system can be freshly installed with TrueNAS SCALE and storage data pools reimported after the install process is complete.
This section outlines actions to take or consider to prepare for the clean installation of SCALE for an Enterprise (HA) system.
Before you begin the clean install of SCALE, on CORE:
Back up your stored data files and any critical data!
If you need to do a clean install with the SCALE iso file, you can import your data into SCALE.
Write down your network configuration information to use after the clean install of SCALE.
TrueNAS uses DHCP to assign the IP address to the primary system network interface. DHCP only provisions one IP address. You can use this DHCP-provided address or you can assign a static IP address. You must assign each network interface cards (NICs) installed in your system and wired to your network an IP address if you want to communicate over your network using the interfaces. To configure your TrueNAS server to work with your network, you need:
DHCP broadcast messages enabled on the network or the subnet(s) in your network where TrueNAS is installed
DNS name sever IP addresses in your network (SCALE can accommodate up to three name server IP addresses)
IP address for the Network Time Protocol (NTP) server you use to synchronize time across your servers and network
Main domain name or the domain name for the portion of your network where the TrueNAS SCALE server is deployed
Host name you want to use if not using the default-assigned host name in SCALE (truenas is the default host name in SCALE)
IP address for each additional network interface added in your system and connected to your network (static IP not provided by DHCP)
IP address assigned to the controller. Either allow DHCP to assign the IP address or assign a static IP.
Identify your system dataset.
If you want to use the same dataset for the system dataset in SCALE, note the pool and system datasat.
When you set up the first required pool on SCALE import this pool first.
Review and document down any system configuration information in CORE you want to duplicate in SCALE. Areas to consider:
Tunables on CORE.
SCALE does not use Tunables the way CORE does. SCALE provides script configuration on the System Settings > Advanced screen as Sysctl scripts.
A future release of SCALE could introduce similar tunables options found in CORE but for now it is not available.
CORE init/shutdown scripts to add to SCALE.
CORE cron jobs configured if you want to set the same jobs up in SCALE.
The global self-encrypting drive (SED) password to configure in SCALE, or unlock these drives in CORE before you clean install SCALE.
Cloud storage backup provider credentials configured in CORE if you do not have these recorded in other files kept secured outside of CORE.
Replication, periodic snapshot, cloud sync, or other tasks settings to reconfigure in SCALE if you want to duplicate these tasks.
Make sure you have backed-up copies of certificates used in CORE to import or configure in SCALE.
Record deprecated service settings and any WebDAV share dataset and user configurations.
Download the SCALE SCALE ISO file or the SCALE upgrade file and save it to your computer or on two USB drives (see the Physical Hardware tab in Installing SCALE).
5.4 - Migrating TrueNAS CORE to SCALE (Enterprise HA)
Discusses migrating a TrueNAS CORE High Availability (HA) system to SCALE.
TrueNAS Enterprise
High Availability (HA) systems cannot migrate directly from CORE to SCALE.
Enterprise customers with HA systems should contact iXsystems Support before attempting any migration.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
Migrating TrueNAS from CORE to SCALE is a one-way operation.
Attempting to activate or roll back to a CORE boot environment can break the system.
Upgrade your CORE system to the latest publicly-available 13.0-Ux release before attempting to migrate from CORE to SCALE.
TrueNAS Enterprise
SCALE Bluefin deprecates and SCALE Cobia removes the built-in DDNS, OpenVPN server and client, rsync, S3, and TFTP services.
The WebDAV service and share feature are also deprecated in Bluefin and removed in Cobia.
New applications are available in SCALE Bluefin to serve as replacements for the functions provided by these services.
To avoid any potential service outages, Enterprise customers with licensed TrueNAS systems are prevented from upgrading from SCALE 22.12.3 (or later) to SCALE 23.10 unless the deprecated services have been replaced and/or disabled.
Enterprise customers can contact iXsystems Support for assistance migrating from deprecated services.
Customers with CORE Enterprise High Availability (HA) systems that want to migrate to SCALE cannot directly migrate the system.
Instead, the process is to clean install SCALE on the system and reimport the storage pools.
Due to software differences between CORE and SCALE, an HA system with CORE installed cannot directly migrate to SCALE.
Moving an HA system from CORE to SCALE
First, back up your data storage and export your pools to the server.
Next, do a clean install of SCALE using the iso file. You must observe the proper sequence for controller 1 and controller 2 so the system comes up with controller 1 as the primary and controller 2 the standby controller.
Remember:
After installing SCALE, configure controller 1 using the SCALE UI, configure controller 1 to the point just before you sync to peer, then power up controller 2 with SCALE already installed and at the Console setup menu screen but not configured, then on controller 1 sync to peer.
After configuring network in controller 1, import all your pools.
Creating a new pool before importing pools could result in accidentally wiping disks currently used with an exported pool.
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 enumerates interface names using interface drivers, such as igb for Intel devices, followed by a number.
TrueNAS CORE Enterprise systems use ix followed by a number.
TrueNAS SCALE enumerates interface names using PCI locations. By default, SCALE systems identify their network ports with eno or enp followed by a number.
TrueNAS CORE identifies bonded interfaces or link aggregations with lagg followed by a number (lagg1).
TrueNAS SCALE uses bond followed by a number (bond1).
See the TrueNAS Systems section for lists of the default port names for each platform.
Related Content
5.6 - ZFS Feature Flags Removed
Provides information on the removal of the ZFS feature flag merged into OpenZFS on 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_compatstorage 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
6 - Configuration Instructions
Configuring TrueNAS SCALE after install.
This section provides instructions for users that are configuring TrueNAS SCALE for the first time.
TrueNAS Enterprise
TrueNAS SCALE Enterprise customers should contact iXsystem Support for assistance with the initial set up and configuration of their systems.
After completing the installation process, you can either use the Console setup menu to reconfigure the primary network interface with a static IP address or use the SCALE UI to make network changes and complete the initial configuration.
Configuring your system includes:
Setting up your first pool
Setting up data sharing
Setting up backup for the system and your stored data
Other options include:
Setting up Clustering
Configuring virtual machines (VMs) or Apps
Configuration Articles
First Time Login: Guides with configuring web interface access and logging in to the TrueNAS SCALE web interface for the first time.
Configuring SCALE Using the UI: Provides a sequential process to complete SCALE initial configuration using the SCALE UI.
Setting Up Storage: Provides basic instructions for setting up your first storage pool and dataset or zvol.
Setting Up Data Sharing: Provides general information on setting up basic data sharing on TrueNAS SCALE.
Backing Up TrueNAS: Provides general information and instructions on setting up data storage backup solutions, saving the system configuration and initial system debug files, and creating a boot environment.
Guides with configuring web interface access and logging in to the TrueNAS SCALE web interface for the first time.
Now that you have installed TrueNAS SCALE or migrated from TrueNAS CORE to SCALE, you can log into the SCALE web user interface (UI) to complete your initial system configuration and then begin managing data!
Important! Use only the web user interface (UI) or the TrueNAS CLI to make configuration changes to the system.
After installing TrueNAS, you can configure and use the system through the UI.
By default, using the LINUX Shell command-line interface (CLI) to modify the system *does not modify the settings database. If the system restarts it reverts to the original database settings and wipes any user-made command line changes.
The SCALE TrueNAS CLI allows administrators experienced with CLI configuration to configure SCALE settings just as in the UI. The TrueNAS CLI functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
Web Interface Access
TrueNAS automatically creates several ways to access the UI, but you might need to adjust the default settings for your network environment.
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, either connect a monitor and keyboard to your TrueNAS system or connect with IPMI for out-of-band system management.
When powering on a TrueNAS system, the system attempts to connect to a DHCP server from all live interfaces to access the web UI.
On networks that support Multicast Domain Name Services (mDNS), the system can use a host name and domain to access the TrueNAS web interface.
By default, TrueNAS uses the host name and domain truenas.local.
To change the host name and domain in the web interface, go to Network and click Settings on the Global Configuration card.
To access the web interface using an IP address, either use the IP address displayed at the top of the Console Setup Menu after installing SCALE or use the IP address you assigned in the Console Setup Menu.
TrueNAS Enterprise
SCALE Enterprise (HA) systems can use the DHCP-assigned IP address for the primary controller to access the SCALE UI or with a static IP address that is configured using the Console Setup Menu.
Logging Into the SCALE UI
Using 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 SCALE web interface.
The browser you use can impact the quality of your user experience. We generally recommend using Firefox, Edge, or Chrome.
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create a local administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS SCALE plans to permanently disable root account access in a future release.
With the implementation of rootless login, root is no longer the default administrator username, rather you use the new admin user created during the installation process.
We recommend creating the admin user during the installation process and using it to log into SCALE.
Based on the authentication method selected in step 4 of the SCALE TrueNAS installer Console Setup process, you could see one of three sign-in splash screen options for the web UI.
Selecting 1. Administrative user (admin) opens the SCALE sign-in screen to log in with the admin username and password created during installation.
Selecting 2. Root user (not recommended) opens the SCALE sign-in screen to log in with the root username and the root password created during installation.
Selecting 3. Configure using Web UI opens a SCALE sign-in screen where you select the option for either the admin or root user and create the password.
If you select option 1, the root user still exists but with the password disabled by default, which means only the admin user can log into the system.
You can activate the password for the root user for some limited uses, but you should return to a security-hardened operation by disabling the root password immediately after you finish with the limited use.
Logging In as Admin
If you set up the admin user during the installation using the option 1. Administrative user (admin), enter the username admin and password you set up.
To modify user credentials, go to Credentials > Local Users, click anywhere on the user row, then click Edit. For more information see Managing Users.
Logging In as Root
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create a local administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS SCALE plans to permanently disable root account access in a future release.
If you created the root user rather than setting up an admin user during the installation process, log into the UI as the root user with the root password.
To create an admin user go to Credentials > Local Users, and click Add to open the Add User screen.
Follow the directions in Managing Users to create an admin user with all required settings.
Creating an Administrator Account at First Log in
If you select option 3. Configure using Web UI during installation SCALE asks you to create the root or administration user when you first log into the web UI. This option presents a sign-in splash screen with two radio buttons.
Select either the Administrative user or Root user (not recommended) option, then enter the password to use with that user.
If you choose Root user (not recommended) as the TrueNAS authentication method, go to the Credentials > Local Users screen and create the admin account immediately after you enter the UI. Create the admin user account settings, enable the password, and click Save. After setting up the admin user, edit the root user to disable the password and resume rootless login security hardening.
Troubleshooting Accessing the Web UI
If you cannot remember the administrator password to log in to the web interface, connect a keyboard and mouse to the TrueNAS system and open the Console Setup Menu to reset the admin account password.
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, Edge, or Chrome.
If the UI becomes unresponsive after an upgrade or other system operation, clear the site data and refresh the browser (Shift+F5).
After logging in for the first time, you see the main system Dashboard screen.
The Dashboard displays basic information about the installed version, systems component usage, and network traffic.
TrueNAS Enterprise
SCALE Enterprise users with an iXsystems-provided TrueNAS server also see an image of the system in the System Information widget. Click on the system image to open the System Settings > View Enclosure screen.
The Dashboard for non-Enterprise systems displays the TrueNAS SCALE logo on the System Information widget.
You can reorder dashboard widgets by clicking Reorder and then dragging them into your preferred order. You can also choose which widgets appear on the dashboard by clicking Configure.
The top row (toolbar) has links to outside resources and buttons to control the system.
The left-hand panel lists the main feature and functional areas and lets users navigate to the various TrueNAS configuration screens.
Top Toolbar
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.
The SCALE top navigation top toolbar provides access to functional areas of the UI that you might want to directly access while on other screens in the UI.
Icon buttons provide quick access to dropdown lists of options, dropdown panels with information on system alerts or tasks, and can include access to other information or configuration screens.
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 the community section for support.
The How would you rate this page? icon opens a feedback window.
Use this window to submit a star rating and comments or suggestions for the current page.
The feedback window allows users to submit their general user-experience feedback.
Submit bug tickets through the File Ticket link that opens the File Ticket form, also accessed from the System Settings > General screen File Ticket button. See Filing an Issue Ticket in SCALE for further instructions.
The Take screenshot of the current page toggle is on by default. When on, TrueNAS SCALE automatically creates and attaches a screenshot.
Turn off the toggle to submit feedback without an image.
When off, the window displays Attach image (optional) as an alternative.
Click Choose File to attach an existing screenshot.
The Status of TrueCommand icon lets users sign up with and connect to TrueCommand Cloud.
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.
The Alertsnotifications icon displays a list of current alert notifications.
To remove an alert notification click Dismiss below it or use Dismiss All Alerts to remove all notifications from the list.
Use the settings icon to display the Alerts dropdown list with two options: Alert Settings and Email.
Select Alert Settings to add or edit existing system alert services and configure alert options such as the warning level and frequency and how the system notifies you.
See Alerts Settings Screens for more information.
TrueNAS Enterprise
The Alert Settings Screens article includes information about the SCALE Enterprise high availability (HA) alert settings.
Select Email to configure the method for the system to send email reports and alerts.
See Setting Up System Email for information about configuring the system email service and alert emails.
The Settingsaccount_circle icon opens a dropdown list of options for passwords, API keys, and TrueNAS information.
Click on the Change Passworddialpad icon button to display the change password dialog where you can enter a new password for the currently logged-in user.
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 an API key. API keys identify an outside resource or application without a principal.
For example, when adding a new system to TrueCommand you are required to add an API key to authenticate the system. Use this function to create an API key for this purpose.
Click API Docs to access the API documentation portal with information on TrueNAS SCALE API commands.
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 button to open the dropdown list of power options. Options are Log Out which logs you out of the SCALE UI but does not power off the system, Restart which logs you out of the SCALE UI and restarts the server, or Shut Down which logs you out of the SCALE UI and powers off the system as though you pressed the power button on the physical server.
Managing Sessions
The Power icon power_settings_new on the right side of the top toolbar gives access to three power related settings.
Log Out ends the session and returns to the UI sign-in screen. This does not affect system power.
Restart power-cycles the system.
Shut Down turns the system off.
To monitor and manage all active sessions, go to System Settings > Advanced.
The Sessions widget displays a list of all active sessions, including the user who initiated the session and what time it started.
It also displays the Token Lifetime setting for your current session.
It allows administrators to manage other active sessions and to configure the token lifetime for their account.
The Terminate Other Sessions button ends all sessions except for the one you are currently using.
You can also end individual sessions by clicking the logout button next to that session.
You must check a confirmation box before the system allows you to end sessions.
The logout button is inactive for your current session and active for all other current sessions.
It cannot be used to terminate your current session.
Token Lifetime displays the configured token duration for your current session (default five minutes).
TrueNAS SCALE logs out user sessions that are inactive for longer than that user’s configured token setting.
New activity resets the token counter.
If the configured token lifetime is exceeded, TrueNAS SCALE displays a Logout dialog with the exceeded ticket lifetime value and the time that the session is scheduled to terminate.
Click Extend Session to reset the token counter.
If the button is not clicked, the TrueNAS SCALE terminates the session automatically and returns to the log in screen.
Click Configure to open the Token Settings screen and configure Token Lifetime for the current account.
Provides a sequential process to complete SCALE initial configuration using the SCALE UI.
TrueNAS Enterprise
iXsystems TrueNAS Enterprise customers should contact iXsystems Support when their systems arrive to receive additional guidance on their next steps.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
All TrueNAS SCALE users should follow these instructions to complete their initial system set up and configuration.
Use the information mentioned in the installation preparation instructions overview article for your SCALE installation type (Enterprise, non-Enterprise,or home use) to configure your network, SMTP, or directory service settings.
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create a local administrator account with all required permissions and begin using it to access TrueNAS.
When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.
TrueNAS SCALE plans to permanently disable root account access in a future release.
After a fresh install from an iso file, administrators log in with the admin account created during install and should no longer log in as the root user.
After you log into SCALE with the administrator account you can begin to configure SCALE using the web interface.
Enterprise Licenses and Proactive Support
TrueNAS Enterprise
Applying Enterprise Licenses
TrueNAS SCALE Enterprise customers should contact iXsystems support to obtain license information for their TrueNAS system.
To apply the license information, go to the System Settings > General screen and use the Update License option on the Support widget (system information card).
Setting up Proactive Support
TrueNAS SCALE Enterprise customers with Silver or Gold Coverage support contracts have the option to configure proactive support.
Customers with appropriate support contracts can configure Proactive Support after they apply their system license, and after acknowledging and signing the End User License Agreement (EULA).
The Support widget on the System Settings > General screen displays the Proactive Support option after you enter your system license.
Setting Up Networking
After installing the SCALE iso file, the SCALE installer provides the DHCP-assigned IP address for the web UI and displays it at the top of the Console Setup Menu screen.
TrueNAS uses DHCP to assign the primary web UI IP address and provision the other required global network addresses.
If you have more than one network interface card installed and connected to your network, you need to assign an IP address and configure it in SCALE.
TrueNAS uses DHCP to assign the IP address required to access the SCALE UI and displays it on the Console Setup Menu screen, and it sets the host name to truenas.
If you do not plan to use the DHCP-assigned network addresses provided by SCALE, identify your host and domain names, the static or fixed IP addresses you plan to assign to your network interface card(s), the default gateway, subnet mask(s), and the DNS name servers in your network.
TrueNAS Enterprise
For Enterprise systems, have your network information ready to provide iXsystems Support when they guide you through your configuration.
All other users should have their network information ready before starting to configure network settings. This makes the process go faster and reduces the risk of issues when you configure SCALE.
We recommend that only experienced administrators familiar with network configuration and the Console setup menu use it and that less experienced and knowledgeable system administrators use the SCALE UI to configure your network interfaces and other network configuration settings.
The TrueNAS SCALE UI includes safety measures to prevent you from completely disrupting network connectivity for your TrueNAS SCALE if you make a mistake with network interface settings.
If you are unfamiliar with network services, devices, or configurations, you can find more information here to help guide you through this important and required configuration area.
TrueNAS Enterprise
You must disable failover in the UI on SCALE Enterprise HA systems to add or change any network setting. Complete network changes and test them, then re-enable failover.
Adding Network Interfaces
Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet.
You can combine multiple interfaces with Link Aggregation (LAGG) or a Network Bridge.
Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
When multiple Network Interface Cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces load balance automatically.
However, ethernet network topology allows only one interface to communicate at a time.
Additionally, both interfaces must handle broadcast messages since they are listening on the same network.
This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, you can use a Link Aggregation (LAGG) configured for Link Aggregation Control Protocol (LACP).
A single LAGG interface with multiple NICs appears as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups.
It provides additional bandwidth or redundancy for critical networking situations.
However LACP has limitations as it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, you can configure one or more static IP aliases for a single NIC.
In summary, it is recommended to use LACP if you need multiple interfaces on a network.
If you need multiple IP addresses, you can define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, you can refer to this discussion from National Instruments.
If your system includes more than one network interface card (NIC) connected to your internal network (wired to your router or Internet access point), you can add an interface in SCALE.
DHCP is available for only a single interface; any other physical interfaces must be configured with static IP addresses.
You can also configure virtual network interfaces such as a bridge, link aggregate (LAGG), or virtual LAN (VLAN) interface.
Static IP addresses and aliases provide different support for various network applications.
TrueNAS Enterprise
SCALE Enterprise HA systems use a virtual IP (VIP) to maintain access to the UI even if the system fails over to the standby controller. This VIP address might experience a minor blip at failover, but you do not need to log in with the standby controller IP address to gain access to the UI after a failover.
You can configure a network interface with a static IP or add an alias IP address on the same screen in the SCALE UI.
For more information on when to use an alias or a static IP address, see Managing Interfaces.
Setting Up Storage
TrueNAS SCALE requires at least one storage pool. We recommend creating the required pool and then planning the rest of your storage needs before you move on to adding sharing, container applications, virtual machines, or begin storing data.
When planning your data storage, consider the type of data sharing you want to do, any container applications you might want to deploy, and how you want to organize stored data.
The storage creation process begins with creating a pool and then adding the datasets or zvols as needed. Creating your initial storage is explained here.
Setting the System Dataset
SCALE assigns the root parent dataset of the first created pool as the system dataset.
If your system has enough disks to add more pools, you can change the system dataset to a different root parent dataset for another pool.
Setting Up Shares
After setting up your system storage, you can configure data sharing using one of the sharing protocols available in SCALE.
For more information on configuring data sharing and the three built-in share types available in SCALE:
Services you need to configure and enable are based on those you want to deploy on your SCALE system.
All SCALE systems should enable SSH service as part of the initial UI configuration.
TrueNAS Enterprise
Enterprise or SCALE systems with large numbers of disks should also enable SMART service and configure SMART testing.
SCALE Enterprise HA systems should enable and configure the failover service.
Configure and enable these services based on your SCALE system needs:
Set this service to allow SSH login for administration users (admin or, if also enabled, the root user) on all SCALE systems.
SMART service and SMART tests
SMART service and tests are important for systems with large numbers of disks.
Managing systems with large numbers of disks can present challenges when determining the disk with issues if SMART service and testing is not set up.
Failover service on SCALE Enterprise High Availability (HA) systems
The failover service enables an HA system to fail over to the standby system controller after a disruption to the primary controller. This service is not included on non-Enterprise and non-HA systems.
Enterprise customers should not make changes to failover settings or the service on their own except when disabling failover to make changes to network settings.
Contact iXsystems Support for assistance before making any changes to other failover settings.
When you add data sharing the system prompts you to enable the appropriate sharing service as part of the configuration and set up process.
If your installation includes a UPS, configure and enable the UPS service as well.
Setting Up SMART Testing
All systems can take advantage of the SMART service and testing if your disks support this service.
Disks that do not support SMART testing do not display the option to set up testing.
See Managing SMART Tests for information on running or managing scheduled SMART tests or Managing Disks for more information on running a manual test from a selected disk.
Setting Up Backup Solutions
After completing your initial system configuration and before you begin day-to-day operations, we recommend you configure the system and data storage backup. These include:
Save or create a new boot environment to use as a restore point if system issues cause you to lose access to the SCALE UI.
Download a system debug to capture system information to use as a comparison against future debug files.
To download a system debug file, go to System Settings > Advanced and click Save Debug to begin the download.
Keep both the system configuration file and the initial system debug file in a safe location where important files are regularly backed up.
You can use the boot environment in an SSH session to restore your system to the point where you completed your system configuration and then import data or pools to recover stored data.
TrueNAS Enterprise
For Enterprise customers with High Availability (HA) systems, the HA restore process requires recovering both controllers.
Contact iXsystems Support for assistance before attempting to recover your system. If you choose to restore access to controller 1 and the SCALE UI, contact iXsystems Support to get assistance with properly recovering your second controller.
Enterprise HA customers should not start issuing CLI commands to recover the system!
Contact iXsystems Support after you restore access to controller 1 to request further assistance and before taking actions that could disrupt or damage system access further and result in requiring a complete reinstall to recover.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
After saving both files, we recommend you set up snapshots, remote replication, or add a cloud storage provider service and set up a cloud sync task to back up your storage data.
TrueNAS SCALE provides options to back up your stored data:
Snapshots and periodic snapshot tasks
Replication to another system (remote replication)
Cloud storage provider access and cloud sync tasks
You can take single snapshots or [schedule periodic snapshot tasks](/scaletutorials/dataprotection/periodicsnapshottasksscale/ to capture changes to stored data without the storage overhead that comes with backing up through data replication, or you can use one of the replication options SCALE provides.
Another data storage backup option is to create an account with a cloud storage service provider, then let SCALE manage the backups.
Use the Backup Credentials screen Cloud Credentials to add authentication credentials for a supported cloud service and then schedule a Cloud Sync Tasks to regularly back up your storage data to the cloud.
Checking System Alert Settings and Services
You can view system alerts, configure the alert service and settings you want to use, and enter an email account to receive alerts from SCALE from the Alerts dropdown panel accessed by clicking the alert icon on the top toolbar.
The alert icon on the top toolbar displays a red circle with a number in it if SCALE encounters a configuration error or exceeds a threshold that you set (such as a temperature or a usage level).
The Alerts icon number indicates the number of new alerts that have occurred.
Click on the alert icon to open the Alerts dropdown panel.
The Alerts dropdown panel also includes a gear Settings icon that provides access to the alert settings configuration screen and a system email account screen where you enter the address to receive messages when a system event triggers an alert.
Click Alert Settings to configure an alert service such as PagerDuty or customize alert settings that determine the threshold for trigging an alert.
Click Email to assign an email address to receive system alert notifications.
TrueNAS Enterprise
The Alert Settings screen includes access to the Enterprise HA setting options to customize the event thresholds that produce alerts or send emails.
Setting Up Directory Services
TrueNAS SCALE allows you to configure an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings.
SCALE allows you to configure either directory server but not both.
We do not recommended that you switch between directory services. This can result in configuration issues that could disrupt your system!
However, it is possible to change from either directory service to the other. If you want to migrate from LDAP to Active Directory, you must disable LDAP in SCALE and then remove the current directory server settings. To change from Active Directory to LDAP, use the Leave Domain option and disable the service before attempting to configure and enable LDAP.
TrueNAS Enterprise
iXsystems Support can assist Enterprise customers with configuring directory service settings in SCALE with the information customers provide, but they cannot configure customer Active Directory system settings.
Non-Enterprise users can find support for configuring directory services in the TrueNAS Documentation Hub tutorials or in the community forums.
Using Enclosure Management
TrueNAS Enterprise
For TrueNAS Enterprise customers with compatible hardware, the TrueNAS SCALE main Dashboard displays an image of the TrueNAS system server on the System Information widget.
Click on the image to open the View Enclosure screen, or select the System Settings > Enclosure option on the main menu navigation panel.
The View Enclosure screen provides details about the system disks, the pools and VDEVs they are in, the hardware, and the disk status. Click on a drive to view the disk details.
If the TrueNAS system has an expansion shelf, an image of the expansion shelf populated with disks also displays.
If using SCALE on servers not provided by TrueNAS, the System Information widget on the Dashboard displays the TrueNAS SCALE logo and the System Settings > Enclosure option does not exist on the menu navigation panel.
Using Applications in SCALE
SCALE provides a list of applications you can deploy on the Apps > Available Applications screen.
See the Apps tutorials for procedures for generically deploying and managing apps, App catalogs, custom apps, and specific app deployment and notes.
Updating SCALE
You can update your system with an iso file using the system administration console or an update file installed through the SCALE UI.
There are a few ways to find available updates for your instance of TrueNAS SCALE:
The main Dashboard > System Information widget alerts you when a SCALE update is available to download and install.
Click the update option to open the System Settings > Updates screen.
Go to System Settings > Updates to check if an update is available.
For all update options and procedures using the SCALE UI see Updating SCALE.
Always save the system configuration file and save a new boot environment for your current release and configuration before updating to either a new incremental or full release.
It is also good practice to download a fresh debug file before and after a system update.
Provides basic instructions for setting up your first storage pool and dataset or zvol.
Now that you are logged in to the web interface, it is time to set up TrueNAS storage.
These instructions describe a simple mirrored pool setup, where half the selected disks are used for storage and the other half for data protection.
However, there are a many different 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 minimum.
You can configure data backups in several ways and have different requirements.
Backing data up in the cloud requires a 3rd party cloud storage provider account.
Backing up with replication requires you to have additional storage on the TrueNAS system or (ideally) another TrueNAS system in a different location.
Setting Up Storage
Your system must have at least one storage pool configured.
After installing SCALE, enter the IP address assigned by DHCP (displayed in the Console Setup Menu) into a browser window to access the SCALE sign-in splash screen.
Log in to SCALE.
Begin by configuring your first storage pool.
See Creating Storage Pools for more information on how to plan for and create pools in SCALE.
If you want to create additional pools with other disks not assigned to a pool, you can do that now or as you have a need for them.
Creating a Storage Pool
To create a pool using the Pool Manager you:
Enter a name.
Move disks to a data VDEV.
Add any other VDEV to the pool you want to include and then add disks to them.
Click Create
You access the Pool Manager from the Storage Dashboard.
Click Storage on the main navigation panel on the left of the screen. Click Create Pool (Legacy) to open the Pool Manager screen for new pools.
If you already have a pool created on your system you can use either the Create Pool button at the top right of the screen or click the Add To Pool button on the Unassigned Disks widget to create a new pool.
The root dataset of the first pool you create automatically becomes the system dataset.
After adding your first pool, you can move on to creating datasets for data sharing, applications you plan to deploy, or other use cases.
Adding Datasets or Zvols
New pools have a root dataset that allows further division into new non-root parent and child datasets or into storage volumes (zvols).
A dataset is a file system that stores data and has specific permissions.
A zvol is a virtual block device (like a virtual disk drive) that has a predefined storage size.
Zvols are generally used with the iSCSI sharing protocol and also virtual machines (VMs) for their data storage needs.
To create a dataset or zvol, you can click Datasets on the main navigation panel or go to Storage and click Manage Datasets on the Usage widget for a specific pool to open the Datasets screen.
To create a dataset using the default settings, go to Datasets.
Default settings include the settings datasets inherit from the parent dataset.
Select a dataset (root, parent, or child), then click Add Dataset.
You can create datasets optimized for SMB shares or with customized settings for your dataset use cases.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but it is not used for application data storage.
If you want to store data by application, create the dataset first, then deploy your application.
When creating a dataset for an application, select App as the Share Type setting. This optimizes the dataset for use by an application.
Review the Share Type and Case Sensitivity options on the configuration screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
Organize the pool with as many datasets or zvols you need according to your access and data sharing requirements before moving data into the pool.
After you finish creating your initial pool and the datasets or zvols, you can continue building and organizing your TrueNAS pools and datasets or move on to configuring how the system shares data
If you do not plan to set up data sharing, you can set up backup solutions for your system and stored data.
Provides general information on setting up basic 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.
Sharing Data Methods
TrueNAS SCALE provides four types of sharing methods, but this article only discusses three:
You can create datasets optimized for SMB shares or with customized settings for your dataset use cases.
If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but it is not used for application data storage.
If you want to store data by application, create the dataset first, then deploy your application.
When creating a dataset for an application, select App as the Share Type setting. This optimizes the dataset for use by an application.
Review the Share Type and Case Sensitivity options on the configuration screen before clicking Save.
You cannot change these or the Name setting after clicking Save.
Create the TrueNAS user accounts with Samba Authentication set.
a. Go to Credentials > Local Users and click Add to create a user.
b. Enter the values in each required field, and then verify Samba Authentication is selected.
For more information on the fields and adding users, see Creating User Accounts.
c. Click Save.
Edit the SMB share dataset permissions to set the Select an ACL Preset to Open.
a. Go to Datasets. Select the name of the dataset for the SMB share you created.
Scroll down to the Permissions widget on the right side of the screen.
Click Edit to open the ACL Editor screen and edit the permissions.
b. Select Use Preset. The Select a preset ACL dialog displays. Select NFS4_OPEN from the dropdown list.
c. Click Continue.
d. Click Save Access Control List.
For more information on Access Control Lists and editing permissions, see Setting Up Permissions.
Create the new SMB share.
a. Click Shares on the main navigation panel, then click Add on the Windows (SMB) Shares widget to open the Add SMB configuration screen.
b. 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.
c. Enter a name for the share.
d. Click Save.
Turn the SMB service on.
If the dialog to enable the service does not open, click the for the share and select Turn On Service.
As of SCALE 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support.
This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SCALE SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
Connect to the share. On a Windows 10 system, open the File Browsers and then:
a. In the navigation bar, enter \\ and the TrueNAS system name or IP address. A login credentials dialog displays.
b. Enter the TrueNAS user account credentials you created on the TrueNAS system.
Add additional packages like nfs-common to any client systems that require them.
Create the NFS share.
a. Select Shares on the main navigation panel, then click Add on the UNIX (NFS) Share Targets to open the Add NFS configuration screen.
b. 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.
c. Click Save.
Access the dataset.
On a Unix-like system, open a command line and enter command showmount -e {IPADDRESS} where {IPADDRESS} is your TrueNAS system IP address.
tmoore@ChimaeraPrime:~$ showmount -e 10.238.15.194
Export list for 10.238.15.194:
/mnt/pool1/testds (everyone)
Make a local directory for the NFS mount. Enter command sudo mkdir nfstemp/
tmoore@ChimaeraPrime:~$ sudo mkdir nfstemp/
Mount the shared directory.
Enter command sudo mount -t nfs {IPADDRESS:dataset path} where {IPADDRESS} is your system IP address and {:dataset path} is the full path displayed in step 3.b. above.
tmoore@ChimaeraPrime:~$ sudo mount -t nfs 10.238.15.194:/mnt/pool1/testds nfstemp/
From here, cd into the local directory and view or modify the files as needed.
Setting up 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 scope of this getting started guide, but detailed articles are available in the SCALE Tutorials section.
With simple sharing now set up, you can back up your configuration and set up data backup.
Provides general information and instructions on setting up data storage backup solutions, saving the system configuration and initial system debug files, and creating a boot environment.
After configuring your TrueNAS storage and data sharing or any other function, service, or application, it is time to ensure effective back up of your data.
You should also set up a data storage backup method using either a cloud sync or replication task.
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 an Amazon S3 bucket.
SCALE support major providers like Storj, Amazon S3, Google Cloud, Box, and Microsoft Azure, along with a variety of other vendors.
These providers can charge fees for data transfer and storage, so please review the 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.
Add your cloud storage credentials to TrueNAS.
Go to Credentials > Backup Credentials and click Add to open the Cloud Credentials configuration screen.
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 after you log into your account using OAuth Authentication.
After logging into the provider with the OAuth credentials, the provider provides the access token.
Google Drive and pCloud use one more setting to authenticate credentials.
Enter the name and select the cloud storage provider from the Provider dropdown list.
Enter the provider account email in OAuth Client ID and the password for that user account in OAuth Client Secret.
Click Log In To Provider. The Authentication window opens. Click Proceed to open the OAuth credential account sign in window.
Yandex displays a cookies message you must accept before you can enter credentials.
Enter the provider account user name and password to verify the credentials.
(Optional) Enter the value for any additional authentication method.
For pCloud, enter the pCloud host name for the host you connect to in Hostname.
For Google Drive when connecting to Team Drive, enter the Google Drive top-level folder ID.
Enter the access token from the provider if not populated by the provider after OAuth authentication. Obtaining the access token varies by provider.
Provider
Access Token
Box
For more information the user access token for Box click here. An access token enables Box to verify a request belongs to an authorized session. Example token: T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl.
The authentication process creates the token for Google Drive and populates the Access Token field automatically. Access tokens expire periodically, so you must refresh them.
pCloud
Create the pCloud access token here. These tokens can expire and require an extension.
(Required) Type a memorable task description in Description.
Select an existing backup credential from the Credential dropdown list.
If you have not added the cloud credential, click Manage Credentials to open the Backup Credentials screen.
Select the option from Direction and in Transfer Mode.
Select the location where to pull from or push data to in the Folder field. A Bucket field also displays for some cloud providers.
Select the dataset location in Directory/Files.
Cloud provider settings change based on the credential you select. Select or enter the required settings that include where files are stored.
Select the time from the Schedule options.
Click Save to add the task.
You can use Dry Run to test your configuration before you click Save or select the option on the Cloud Sync Task widget after you click Save.
To manually start a saved task, click the Run Now for the cloud sync task you want to start.
Using Replication for Data Backup
Replication is the process of taking a moment-in-time snapshot of data and then copying that snapshot to another location.
Snapshots typically use less storage than full file backups and have more management options.
To create a simple replication task with the TrueNAS replication wizard:
Create a periodic snapshot task using the Periodic Snapshot Task or use the Run Once replication schedule option.
If scheduling a task, SCALE creates the periodic snapshot task when it runs the replication task according to the scheduled time.
Create the replication task.
Go to Data Protection and click Add on the Replication Tasks widget. The Replication Task Wizard opens on 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. Have your destination and source information ready.
Next enter the Source and Destination paths. To populate the field with the full path, you can either type the full path to the data you want to back up or click on the caret to the left of mnt and at the pool and dataset levels to expand the options. Click on the dataset and/or the file if you want to narrow backup down to that level.
The task 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.
If using this option you must have a periodic snapshot task already defined. If running on a schedule you don’t have to have a pre-defined snapshot task.
Select the radio button to specify the destination snapshot lifetime.
Click START REPLICATION. The task appears on the Replication Tasks widget with the status as PENDING.
Backing Up the System Configuration
Now that you configured your system network, storage, and the data shares you want, and you have set up your data back up solution, it is time to back up your system configuration.
When you download the configuration file, you have the option to Export Password Secret Seed, which includes encrypted passwords in the configuration file.
This allows you to restore the configuration file to a different operating system device where the decryption seed is not already present.
Users must physically secure configuration backups containing the seed to prevent unauthorized access or password decryption.
We recommend backing up the system configuration regularly.
Doing so preserves settings when migrating, restoring, or fixing the system if it runs into any issues.
Save the configuration file each time the system configuration changes.
If you plan to set up a cluster that includes this TrueNAS SCALE, wait to download your system configuration file until after the cluster is set up and working.
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.
Downloading the Initial System Debug File
After saving the system configuration, go to System Settings > Advanced and click Save Debug. After the download completes save this initial debug file with your system configuration file.
Create a Boot Environment
After installing and completing your SCALE system configuration, create a boot environment to use as a restore point.
If an issue occurs where you lose access to the SCALE UI, you can establish an SSH session and restore it from the boot environment.
You can clone the boot environment listed after the initial-install environment and rename the clone to something you recognize, such as the release number with date and time.
Initial setup procedures to prepare a system for clustering.
TrueNAS SCALE has the unique ability to 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.
Clustering is considered experimental and should not be used in a production environment or for handling critical data!
Clustering Options
TrueNAS SCALE provides a few options for setting up system clustering:
6.7 - Configuring Virtualization and Apps in TrueNAS SCALE
Provides general information on setting up virtual machines and applications on TrueNAS SCALE.
Configuring TrueNAS SCALE to work with virtualized features, such as virtual machines (VMs) and applications, is a part of the setup process that when optimized takes advantage of the network storage capabilities that SCALE offers.
Before You Begin
This article assumes that you have the latest release version of TrueNAS SCALE installed on your system.
The following steps comprise a list of configuration prerequisites that you have completed and are familiar with before beginning VM and application installations.
Network Configuration
The primary network interface is configured as part of the SCALE installation process.
Go to Network > Global Configuration screen in the TrueNAS web UI to determine that the default gateway, host name, domain and DNS name servers have been configured correctly.
See Console Setup Menu Configuration for more information on network settings.
VLAN Configuration (Optional)
You have the option of configuring a virtual LAN (VLAN) to route traffic for your VMs.
VLAN benefits include the reduction of broadcast traffic and the ability to group resources in different physical locations into a broadcast domain.
VLANs virtually segment a network.
Different VLANs can communicate with each other using layer 3 devices.
See Setting Up a Network VLAN for more information on creating virtual LANs (VLAN).
Storage Configuration
Storage pool creation is part of the initial process of setting up storage for SCALE.
A TrueNAS dataset is a file system within a data storage pool.
See Setting Up Storage to review storage pool creation and Adding and Managing Datasets for information on dataset configuration.
Shares Configuration
After creating the pool and datasets, set up shares to enable data access.
Different types of data sharing methods are discussed in Setting Up Data Sharing.
You should investigate more specific coverage of each share based on your individual use case.
See Adding NFS Shares for information on creating a basic NFS share.
Adjust access permissions using the advanced options.
Directory Services Configuration
Certain directory services need to be set up as part of SMB and NFS share configuration.
See Active Directory Screen for a better understanding of how to configure Active Directory, and Configuring Kerberos for an outline of required Kerberos information.
For LDAP best practices see Configuring LDAP.
Virtualization Configuration
To run a virtual machine (VM), hardware requirements include an x86 machine running a recent Linux kernel using either an Intel processor with VT extensions or an AMD processor with SVM extensions (AMD-V).
To install a VM on SCALE, first research the minimum and recommended specifications for the OS you plan to use and your full use case for that VM.
Allocating too many resources to a VM can cause performance on the TrueNAS SCALE system to suffer, so we recommend you plan ahead and ensure your SCALE system has the resources to run both itself and a full VM deployment effectively.
Software requirements include an installer for the OS you intend to install on the VM.
A TrueNAS storage pool is required.
It is recommended to have additional datasets created beneath the storage pool to further organize your VM data.
The first time you open the Applications screen, it displays an Apps Service Not Configured status on the screen header.
Click Settings > Choose Pool to choose a storage pool for Apps.
A storage pool for applications must be chosen before application installation can begin.
Select a pool that has enough space for all the application containers you intend to use.
Set up a new dataset before installing your applications if you want to store your application data in a separate location from other storage on your system.
After an Apps storage pool is configured, the status changes to Apps Service Running.
For custom applications, Install Custom App details each field on the Install Custom App screen.
Prior to beginning a custom application installation, determine the following information:
Container host networking requirements, including host interface
IP address management: DHCP or static IP
DNS policy and nameservers
Container entrypoint (executables run when the container is started): commands or arguments
Container environment variables: names and values
Port forwarding
Storage: host path and mount path configuration
You can find additional options for configuring general network interfaces and IP addresses for application containers in Apps > Settings > Advanced Settings.
Guides for getting assistance with TrueNAS SCALE issues.
There are several options to get support for your TrueNAS installation.
TrueNAS SCALE users can engage with the TrueNAS community to answer questions and resolve issues using the links listed at the bottom of all TrueNAS Documentation Hub articles.
TrueNAS Enterprise hardware customers can access the fast and effective support directly provided by iXsystems.
Contents
Accessing TrueNAS Support: Provides instructions for SCALE users to access the TrueNAS Community and Social Media, get system support, and report problems though the SCALE UI.
Provides instructions for SCALE users to access the TrueNAS Community and Social Media, get system support, and report problems though the SCALE UI.
About TrueNAS Support
TrueNAS Enterprise
Enterprise SCALE hardware customers with support contracts should contact iXsystems Support using either the Commercial Support option on the top header of the TrueNAS Documentation Hub website, or through one of the contact options listed below.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
TrueNAS SCALE users are welcome to report bugs, suggest new TrueNAS features, and vote for suggested improvements in the Jira project instance.
Have questions? We recommend searching through the software documentation and community resources for answers.
Non-Enterprise SCALE customers experiencing software bugs or instability can try to find answers in the various community forums, or they can file an issue ticket through the Jira ticket reporting system for TrueNAS.
The Issue Reporting article has more information on what type of information and attachments to include in Jira tickets.
When reporting an issue, download a system debug file taken immediately following the issue occurrence.
This captures the system configuration information and logs iXsystems needs to help resolve your issues.
On TrueNAS SCALE systems, go to System Settings > Advanced, then click Save Debug and wait for the file to download to your local system.
Generating the debug file might take a few minutes to complete. After that, it downloads to your system.
Upload this debug to the private attachments area using the link provided when you open a Jira ticket.
After uploading the file, link the attachment to the Jira ticket number before you click Save.
Support is also available through the TrueNAS community forums, blog, and Discord.
These options are accessible on the top header of the TrueNAS Documentation Hub website and from the links at the bottom of all articles.
Using the TrueNAS Community
The TrueNAS Community is an active online resource for asking questions, troubleshooting issues, and sharing information with other TrueNAS users.
You must register to post.
Community Resources are user-contributed articles about every facet of using TrueNAS.
They are organized into broad categories and incorporate a community rating system to better highlight content that the whole community has found helpful.
Using TrueNAS Social Media
You are always welcome to network with other TrueNAS users using the various social media platforms!
Provides information on using TrueNAS SCALE UI to file an issue ticket in Jira.
Filing Issue Tickets
We encourage TrueNAS SCALE users to report bugs and to vote for or suggest new TrueNAS features in the project Jira instance.
Have questions? We recommend searching through the software documentation and community resources for answers.
If you encounter a bug or other issue while using TrueNAS SCALE, you can report issues in one of two ways:
Log into Jira and use Create to open a new ticket.
Use the File Ticket option on the System Settings > General screen to create a bug report in the TrueNAS Jira Project.
The web interface provides a form to report issues without logging out of SCALE, and that prompts you to provide the information and attachments we need to assist users.
New Jira tickets are not marked as iX Private so it is possible to search the project first to see if another user already reported the issue.
Each Jira ticket sends a link to a private file attachment area to safeguard user personal and private data. If the attached files do not require privacy, attach them to the Jira ticket. All incoming tickets are triaged. If private files are attached to a new ticket, the ticket or files can be made private at that time.
To report an issue using the SCALE UI, go to System Settings > General and click File Ticket on the Support widget to open the File Ticket form.
Click Login to JIRA and enter your credentials in the fields provided.
After logging in, select Allow to give TrueNAS read and write access to your data on the Jira site.
After logging into Jira, select either Bug or Feature as the Type of ticket to create, then choose the appropriate Category for your request.
Attach a debug file to all bug tickets.
Click Attach Debug. SCALE generates the debug file, uploads it to the private attachment area, and creates the link to the Jira ticket. Debug files give the TrueNAS team pertinent information about the system and what could be causing any issues.
If the debug file is too large to attach to your ticket, the following displays:
Provide a brief summary of the issue in Subject.
Enter as many details about the issue as possible and the reason for submitting the ticket in the Description field.
Attach any applicable screenshots and click Save.
After the ticket generates, the Ticket confirmation dialog opens. Click Open Ticket to view the ticket in Jira.
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.
8.2 - Software Development Life Cycle
Notice about the typical development timeframe and end of life expectations for TrueNAS SCALE major versions.
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.
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:
8.3 - TrueNAS Data Collection Statement
iXsystems, Inc. statement about non-sensitive anonymous data collection.
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
TrueNAS Enterprise
icon opens a feedback window.
icon lets users sign up with and connect to 
