(408) 943-4100               V   Commercial Support Toggle between Light and Dark mode

Major Version Upgrades

  6 minute read.

Last Modified 2021-03-17 17:36 EDT

TrueNAS provides flexibility for keeping the operating system up-to-date:

  1. Upgrades to major releases, for example from version 9.3 to 9.10, can still be performed using either an ISO or the web interface. Unless the Release Notes for the new major release indicate that the current version requires an ISO upgrade, either upgrade method can be used.
  2. Minor releases have been replaced with signed updates. This means that it is not necessary to wait for a minor release to update the system with a system update or newer versions of drivers and features. It is also no longer necessary to manually download an upgrade file and its associated checksum to update the system.
  3. The updater automatically creates a boot environment, making updates a low-risk operation. Boot environments provide the option to return to the previous version of the operating system by rebooting the system and selecting the previous boot environment from the System > Boot menu.

This article describes how to use an .iso file to perform a major version upgrade from an earlier version of FreeNAS/TrueNAS. See the Updating article for instructions about using the web interface to keep the system updated.

The upgrade path for major versions of FreeNAS/TrueNAS is 9.3 > 9.10 > 11.1 > 11.3 > 12.0. It is always recommended to upgrade to a supported version of the software.

Caveats

Be aware of these caveats before attempting a major version upgrade:

  • Upgrading a data storage pool can make it impossible to go back to a previous version. For this reason, the update process does not automatically upgrade storage pools, though the system shows an alert when a pool can be upgraded. Unless new ZFS feature flags are needed, it is safe to leave the pool at the current version. If the pool is upgraded, it will not be possible to boot into a previous TrueNAS version that does not support the newer feature flags.
  • Upgrading the firmware of Broadcom SAS HBAs to the latest version is recommended.
  • When upgrading from 9.3.x to 9.10, read this changes FAQ first.
  • Upgrades from FreeNAS 0.7x are not supported. The system has no way to import configuration settings from FreeNAS 0.7x versions. The configuration must be manually recreated. If supported, the FreeNAS 0.7x pools or disks must be manually imported.
  • Upgrades on 32-bit hardware are not supported. However, if the system is currently running a 32-bit version of FreeNAS/TrueNAS and the hardware supports 64-bit, the system can be upgraded. Any archived reporting graphs will be lost during the upgrade.
  • UFS is not supported. If the data currently resides on one UFS-formatted disk, create a ZFS pool using other disks after the upgrade, then use the instructions in Importing a Disk to mount the UFS-formatted disk and copy the data to the ZFS pool. With only one disk, back up its data to another system or media before the upgrade, format the disk as ZFS after the upgrade, then restore the backup. If the data currently resides on a UFS RAID of disks, it is not possible to directly import that data to the ZFS pool. Instead, back up the data before the upgrade, create a ZFS pool after the upgrade, then restore the data from the backup.
  • If you have GELI-encrypted pools and are upgrading to TrueNAS 12.0 or newer, you might want to migrate data out of the GELI-encrypted pools into ZFS-encrypted pools. The GELI pools cannot be converted; the data must be migrated to a new ZFS pool. See the Encryption article for more details.

Preparation

Before upgrading the operating system, follow these steps:

  1. Back up the TrueNAS configuration in System > General > Save Config.
  2. Back up any or have the keys or passphrases for encrypted data available.
  3. Warn users that TrueNAS shared data will be unavailable during the upgrade. It is recommended to schedule the upgrade for a time that will least impact users.
  4. Stop all system Services.

ISO Upgrades

To upgrade TrueNAS using an .iso file, go to https://www.truenas.com/download-truenas-core/ (TrueNAS CORE latest release) or https://download.freenas.org to download the .iso to the computer that will be used to prepare the installation media. For example, this is the path to download an .iso of the latest FreeNAS 11.3 release:

DownloadLatest

Burn the downloaded .iso file to a CD or USB stick. Refer to the Prepare the Install File instructions in the Installation article for tips about burning the .iso to media using different Operating Systems.

Insert the prepared media into the system and boot from it. The installer waits ten seconds in the installer boot menu before booting the default option. If needed, press Spacebar to stop the timer and choose another boot option. After the media finishes booting into the installation menu, press Enter to select the default option 1 Install/Upgrade. The installer presents a screen showing all available drives.

All drives are shown, including boot drives and storage drives. Only choose boot drives when upgrading. Choosing the wrong drives to upgrade or install will cause loss of data. If unsure about which drives contain the TrueNAS operating system, reboot and remove the install media. Log in to the TrueNAS web interface and go to System > Boot > ACTIONS > Boot Pool Status to identify the boot drives. More than one drive is shown when a mirror has been used.

Highlight the drive where TrueNAS is installed and press Spacebar to mark it with a star. If a mirror has been used for the operating system, mark all of the drives where the TrueNAS operating system is installed. Press Enter when done.

The installer recognizes earlier versions of FreeNAS/TrueNAS installed on the boot drives and asks to either upgrade or do a fresh install:

InstallerUpgradeChoice

To perform an upgrade, press Enter to accept the default Upgrade Install. The installer will display another reminder that the operating system should be installed on a disk that is not used for storage.

InstallerUpgradeMethod

The updated system can be installed in a new boot environment, or the entire operating system device can be formatted to start fresh. Installing into a new boot environment preserves the old code, allowing a roll-back to previous versions if necessary. Formatting the boot device is usually not necessary but can reclaim space. User data and settings are preserved when installing to a new boot environment and also when formatting the operating system device. Move the highlight to one of the options and press Enter to start the upgrade.

The installer unpacks the new image and checks for upgrades to the existing database file. The database file that is preserved and migrated contains your TrueNAS configuration settings.

Installer Upgrade Preserved Database

Press Enter. TrueNAS indicates that the upgrade is complete and a reboot is required. Press OK, highlight 3 Reboot System, then press Enter to reboot the system. If the upgrade installer was booted from CD, remove the CD.

During the reboot there can be a conversion of the previous configuration database to the new version of the database. This happens during the Applying database schema changes line in the reboot cycle. This conversion can take a long time to finish, sometimes fifteen minutes or more, and can cause the system to reboot again. The system will start normally afterwards. If database errors are shown but the web interface is accessible, log in, go to System > General, and use the UPLOAD CONFIG button to upload the configuration backup that was downloaded before starting the upgrade.