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

Updating Enterprise (HA)

  6 minute read.

Last Modified 2021-09-24 16:37 EDT

Updating a TrueNAS Enterprise system that is configured for High Availability (HA) has a slightly different flow from non-HA systems or TrueNAS Core. The system downloads the update to both controllers, updates and reboots the standby TrueNAS controller, and finally fails over from and updates the active TrueNAS controller.


An update usually takes between thirty minutes and an hour. A reboot is required after the update, so it is recommended to schedule updates during a maintenance window, allowing two to three hours to update, test, and possibly roll back if issues appear. On very large systems, a proportionally longer maintenance window is recommended.

For individual support during an upgrade, please contact iXsystems Support to schedule your upgrade.

Contact MethodContact Options
TelephoneMonday - Friday, 6:00AM to 6:00PM Pacific Standard Time:

US-only toll-free: 1-855-473-7449 option 2
Local and international: 1-408-943-4100 option 2
TelephoneAfter Hours (24x7 Gold Level Support only):

US-only toll-free: 1-855-499-5131
International: 1-408-878-3140 (international calling
rates will apply)
Scheduling at least two days in advance of a planned upgrade gives time to make sure a specialist is available for assistance. Updating from earlier than version 9.3 of TrueNAS must be scheduled with iXsystems Support.

The update process will not proceed unless there is enough free space in the boot pool for the new update files. If a space warning is shown, go to System > Boot and remove any unneeded boot environments.

Operating system updates only modify the operating system devices and do not affect end-user data on storage drives.

An update could involve upgrading the version of ZFS that is installed on the storage drives. When a ZFS version upgrade is available, an Alert appears in the web interface. Upgrading the ZFS version on storage drives is not recommended until it has been verified that rolling back to previous versions of the operating system is not necessary and that swapping the storage drives with another system that has an earlier ZFS version is not needed. After a ZFS version upgrade, the storage devices will not be accessible by earlier TrueNAS versions.

Starting the Update

In the web interface Dashboard, find the entry for the active TrueNAS controller and click CHECK FOR UPDATES. This button changes to UPDATES AVAILABLE when there is an available update.

Dashboard Enterprise

Clicking the button goes to System > Update and shows the option to Download Updates or, when the system has already detected and staged an update, Apply Pending Update.

When Download Updates or Apply Pending Update is clicked, it first gives an opportunity to save the current system configuration. Backing up the system configuration is strongly recommended before starting the update. Including the Password Secret Seed in the system configuration removes the encryption from sensitive system data, like stored passwords. When enabling this option, take extra precautions to store the downloaded system configuration file in a secure location.

After downloading the system configuration, you can continue to download and/or apply the system update. This will start the process to update and reboot the TrueNAS controllers. HA and other system services will be briefly unavailable.

Other users that are logged in to the web interface will see a warning dialog. A System Updating icon is shown in the top bar of the web interface while the update is in progress.

Update progress is shown for both TrueNAS controllers. The standby TrueNAS controller reboots when it is finished updating. This can take several minutes. When the standby controller has finished booting, the system must fail over to update and reboot the active TrueNAS controller.

Fail Over to Complete the Update

To deactivate the active TrueNAS controller and finish the update, go to the Dashboard, find the entry for the Standby controller, and click INITIATE FAILOVER.


Initiating the failover briefly interrupts TrueNAS services and availability. The browser logs out of the web interface while the active TrueNAS controller deactivates and the standby TrueNAS controller is brought online. The web interface login screen reappears when the standby TrueNAS controller finishes activating.


Log in to the web interface and check the HA status in the top toolbar. This icon shows that HA is unavailable while the previously active TrueNAS controller reboots. When HA is available, a dialog asks to finish the update. Click CONTINUE to finish updating the previously active TrueNAS controller.

Verify that the update is complete by going to the Dashboard and confirming that the Version is the same on both TrueNAS controllers.

If the update did not install on one of the controllers, the web interface generates an alert about a mismatch between controller versions.

HA Controller Versions Error Enterprise

If something else goes wrong with the update, the system generates an alert and writes details to /data/update.failed.

You can return the system to its pre-update state by activating a previous boot environment during system boot. To ensure the versions match, do this procedure for both TrueNAS controllers. This requires physical or IPMI access to the TrueNAS controller console.

Reboot the system and press the space bar when the boot menu appears, pausing the boot process.


Open the Boot Environments menu and cycle the Active boot environment until one that is dated prior to the update is selected.


Return to the first screen and press Enter to boot into the version of TrueNAS that was installed on that date.

Enterprise customers should contact iX Support for assistance updating their TrueNAS system.

  • Download the manual update file located at the TrueNAS/FreeNAS Download Page.
  • Go to System -> Update.
  • Click the INSTALL MANUAL UPDATE button.
  • Set the Include Password Secret Seed checkbox and click the Save Configuration button.
  • Select the Update File Temporary Storage Location, click the Choose File button. Select the manual upgrade file that was downloaded. Wait for the file to upload and then click the APPLY UPDATE button.
  • The Manual update will upload the file, install the file to both controllers, and then reboot the Standby Controller. To complete the upgrade process click the Close button in the dialog box. Initiate a failover of the standby controller, as instructed, by clicking INITIATE FAILOVER from the Standby Controller’s Dashboard card.
  • Log into the system.
  • Click the Continue button at the Pending Upgrade dialog box and the standby controller will reboot completing the upgrade.