THIS SITE IS NOW DEPRECATED AND IN READ-ONLY MODE. REFER TO DOC.FREENAS.ORG FOR FREENAS DOCUMENTATION.
FreeNAS® provides two methods for performing an upgrade: an ISO upgrade or an upgrade using the graphical administrative interface. Unless the Release Notes indicate that your current version requires an ISO upgrade, you can use either upgrade method. Both methods are described in this section.
Before performing an upgrade, always backup your configuration file and your data.
When upgrading, be aware of the following caveats:
- Neither upgrade method can be used to migrate from FreeNAS 0.7x. Instead, install FreeNAS® and either auto-import supported software RAID or import supported filesystems. You will need to recreate your configuration as the installation process will not import 0.7 configuration settings.
Preparing for the Upgrade
Before upgrading the system to 9.2.2, perform the following steps:
1. Download the .iso or .txz file that matches the system's architecture to the computer that you use to access the FreeNAS® system.
2. Locate and confirm the SHA256 hash for the file that you downloaded in the Release Notes for the version that you are upgrading to.
3. Backup the FreeNAS® configuration in System → Settings → General → Save Config.
4. If any volumes are encrypted, make sure that you have set the passphrase and have copies of the encryption key and the latest recovery key. Without these, you will not be able to unlock the encrypted volume after the upgrade.
5. Warn users that the FreeNAS® shares will be unavailable during the upgrade; you should schedule the upgrade for a time that will least impact users.
6. Stop all services in Services → Control Services.
Using the ISO to Upgrade
Burn the downloaded .iso file to a CDROM.
Insert the CDROM into the system and boot from it. Once the media has finished booting into the installation menu, press enter to select the default option of "1 Install/Upgrade to hard drive/flash device, etc.". As with a fresh install, the installer will present a screen showing all available drives; select the device FreeNAS® is installed into and press enter.
The installer will recognize that an earlier version of FreeNAS® is installed on the device and will present the message shown in Figure 2.6a:
Figure 2.6a: Upgrading a FreeNAS® Installation
NOTE: if you select to perform a Fresh Install, you will have to restore the backup of your configuration.
To perform an upgrade, press enter to accept the default of Upgrade Install. Again, the installer will remind you that the operating system should be installed on a thumb drive. Press enter to start the upgrade. Once the installer has finished unpacking the new image, you will see the menu shown in Figure 2.6b. The database file that is preserved and migrated contains your FreeNAS® configuration settings.
Figure 2.6b: FreeNAS® will Preserve and Migrate Settings
Press enter and FreeNAS® will indicate that the upgrade is complete and that you should reboot, as seen in Figure 2.6c. During the reboot there may 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 so be patient and the boot should complete normally. If for some reason you end up with database errors but the graphical administrative interface is accessible, go to Settings → General and use the Upload Config button to upload the configuration that you saved before you started the upgrade.
Figure 2.6c: Upgrade is Complete
Using the GUI to Upgrade
To perform the upgrade using this method, download the latest version of the .txz file that matches the architecture of the system (32- or 64-bit). Then, go to System → Settings → Advanced → Firmware Update as shown in Figure 2.6d:
Figure 2.6d: Upgrading FreeNAS® From the GUI
Use the drop-down menu to select an existing volume to temporarily place the firmware file during the upgrade. Alternately, select "Memory device" to allow the system to create a temporary RAM disk to be used during the upgrade.
After making your selection, click the Apply Update button to see the screen shown in Figure 2.6e.
Figure 2.6e: Step 2 of 2
This screen again reminds you to backup your configuration before proceeding. If you have not yet, click the "click here" link.
Browse to the location of the downloaded .txz file, then paste its SHA256 sum.
When finished, click the Apply Update button to begin the upgrade process. Behind the scenes, the following steps are occurring:
- the SHA256 hash is confirmed and an error will display if it does not match; if you get this error, double-check that you pasted the correct checksum and try pasting again
- the new image is uncompressed and written to the USB compact or flash drive; this can take a few minutes so be patient
- once the new image is written, you will momentarily lose your connection as the FreeNAS® system will automatically reboot into the new version of the operating system
- FreeNAS® will actually reboot twice: once the new operating system loads, the upgrade process applies the new database schema and reboots again
- assuming all went well, the FreeNAS® system will receive the same IP from the DHCP server; refresh your browser after a moment to see if you can access the system
Unlocking an Encrypted Volume
If your disks are encrypted and you have created a passphrase and saved the recovery key, the volume will automatically be locked during an upgrade. This is to prevent an unauthorized user from using an upgrade procedure to gain access to the data on the encrypted disks. After the upgrade, the locked volumes will be unavailable until they are unlocked with the passphrase and recovery key.
To unlock the volume, go to Storage → Volumes → View Volumes and highlight the locked volume. As seen in Figure 2.6f, clicking the "Unlock" icon will prompt for the passphrase or recovery key. You can also select which services to start when the volume is unlocked.
Figure 2.6f: Unlocking an Encrypted Volume
If Something Goes Wrong
If the FreeNAS® system does not become available after the upgrade, you will need physical access to the system to find out what went wrong. From the console menu you can determine if it received an IP address and use option "1) Configure Network Interfaces" if it did not.
If this does not fix the problem, go into option "9) Shell" and read the system log with this command:
If the database upgrade failed, a file called /data/upgrade-failed should be created with the details.
If the problem is not obvious or you are unsure how to fix it, see FreeNAS Support Resources.
FreeNAS® supports two operating systems on the operating system device: the current operating system and, if you have performed an upgrade, the previously installed version of the operating system. This allows you to reboot into the previous version should you experience a problem with the upgraded version.
The upgrade process automatically configures the system to boot from the new operating system. If the system remains inaccessible and you wish to revert back to the previous installation, type reboot from the shell or select "10) Reboot" from the console menu. Watch the boot screens and press the other boot option (typically F2) from the FreeNAS® console when you see the following options at the very beginning of the boot process. In this example, Boot: F1 refers to the default option (the newly upgraded version), so pressing F2 will boot into the previous version.
F1 FreeBSD F2 FreeBSD Boot: F1
NOTE: if a previously working FreeNAS® system hangs after a FreeNAS® upgrade, check to see if there is a BIOS/BMC firmware upgrade available as that may fix the issue.
If the upgrade completely fails, don't panic. The data is still on your disks and you still have a copy of your saved configuration. You can always:
1. Perform a fresh installation.
2. Import your volumes in Storage → Auto Import Volume.
3. Restore the configuration in System → Settings → Upload Config.
Upgrading a ZFS Pool
ZFS pools that were created in FreeNAS® 8.3.x use ZFSv28. Any ZFS pools that were created in any previous 8.x versions of FreeNAS® use ZFSv15. If you auto-import a ZFS pool from any 8.x version, it will remain at its original ZFS version unless you upgrade the pool. This means that the pool will not understand any feature flags, such as LZ4 compression, until the pool is upgraded.
If you wish to upgrade an existing ZFSv15 or ZFSv28 pool, be aware of the following caveats first:
- the ZFS version upgrade must be performed from the command line, it can not be performed using the GUI.
- the pool upgrade is a one-way street meaning that if you change your mind you can not go back to an earlier ZFS version or downgrade to an earlier version of FreeNAS® that does not support feature flags.
- before performing any operation that may affect the data on a storage disk, always backup your data first and verify the integrity of the backup. While it is unlikely that the pool upgrade will affect the data, it is always better to be safe than sorry.
To perform the ZFS version upgrade, open Shell. The following commands will determine the pool state and version. In this example, the pool name is volume1 and the ZFS version is 28.
zpool status pool: volume1 state: ONLINE status: The pool is formatted using a legacy on-disk format. The pool can still be used, but some features are unavailable. action: Upgrade the pool using 'zpool upgrade'. Once this is done, the pool will no longer be accessible on software that does not support feature flags. scan: none requested config:
NAME STATE READ WRITE CKSUM volume1 ONLINE 0 0 0 gptid/ea16925b-e96e-11e2-9ed5-e06995777a82 ONLINE 0 0 0 gptid/ea8f3a7b-e96e-11e2-9ed5-e06995777a82 ONLINE 0 0 0 gptid/eb064d06-e96e-11e2-9ed5-e06995777a82 ONLINE 0 0 0 gptid/eb7ba402-e96e-11e2-9ed5-e06995777a82 ONLINE 0 0 0
errors: No known data errors
zpool get version volume1 NAME PROPERTY VALUE SOURCE volume1 version 28 local
Next, verify that the status of the pool is healthy:
zpool status -x all pools are healthy
NOTE: do not upgrade the pool if its status does not show as healthy.
To upgrade a pool named volume1:
zpool upgrade volume1 This system supports ZFS pool feature flags. Successfully upgraded 'volume1' from version 28 to feature flags. Enabled the following features on 'volume1': async_destroy empty_bpobj lz4_compress
The upgrade itself should only take a second or so and is non-disruptive. This means that you do not need to stop any sharing services in order to upgrade the pool. However, you should choose to upgrade when the pool is not being heavily used. The upgrade process will suspend I/O for a short period, but should be nearly instantaneous on a quiet pool.