Upgrading FreeNAS®
Contents |
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 disks. You will need to recreate your configuration as the installation process will not import 0.7 configuration settings.
- Upgrades from versions prior to 8.0.1-BETA3 to any later 8.x version must be done using the ISO. For example, upgrading from 8.0-RELEASE to 8.0.3-RELEASE using the GUI will not work as the image size increased from 1GB to 2GB between 8.01-BETA2 and 8.0.1-BETA3.
- The format of the file used by the GUI upgrade process changed in 8.2.0-BETA3 from .xz to .txz. This means that you should download the .txz version if you are upgrading from 8.2.0-BETA3 or higher. If you are upgrading from any version prior to 8.2.0-BETA3, use the .xz file.
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. Should you experience problems with a newly upgraded operating system, simply select the other boot option (typically F2) at 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
Preparing for the Upgrade
Before upgrading the system, perform the following steps:
1. Depending upon the type of upgrade method, download either the .iso or the .GUI_Upgrade.* file that matches the system's architecture. Download the file 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. 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.
5. Stop all services in Services → Control Services.
If you have created a Plugins Jail, it is not touched during the upgrade. This means that any installed plugins, software, or jail customizations will not be affected by the upgrade.
However, saving the config is step #3 does not save any configuration changes made within a Plugins Jail. For this reason, it is recommended to install the Plugins Jail into a ZFS dataset and to take a snapshot of the jail dataset before performing an upgrade.
From the ISO
To upgrade using this method, download the latest version of the ISO that matches the architecture of the system (32- or 64-bit) and burn it 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 No at this screen, the installer will do a fresh install of the version on the CD rather than upgrade the current version. This means that you will have to re-import your disks and restore the backup of your configuration.
To upgrade, press enter to accept the default of Yes. 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
From the GUI
To perform the upgrade using this method, 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 use system RAM 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 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
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:
more /var/log/messages
Additionally, if the database upgrade failed, a file called /data/upgrade-failed should be created with details.
If the problem is not obvious or you are unsure how to fix it, see FreeNAS Support Resources.
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) when you see this menu:
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 → Import Volume.
3. Restore the configuration in System → Settings → Upload Config.
Upgrading a ZFS Pool
Beginning with version 8.3.1, FreeNAS® supports ZFSv28, while previous 8.x versions of FreeNAS® use ZFSv15. If you import a ZFS volume from an earlier version of FreeNAS®, it will still be at ZFSv15. However, any new pools that you create will be formatted with ZFSv28.
If you wish to upgrade an existing ZFSv15 pool to ZFSv28, 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 ZFSv28.
- 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 15.
zpool status
pool: volume1
state: ONLINE
status: The pool is formatted using an older 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 older software versions.
scan: none requested
config:
NAME STATE READ WRITE CKSUM
volume1 ONLINE 0 0 0
raidz1-0 ONLINE 0 0 0
ada0p2 ONLINE 0 0 0
ada1p2 ONLINE 0 0 0
ada2p2 ONLINE 0 0 0
ada3p2 ONLINE 0 0 0
errors: No known data errors
zpool get version volume1 NAME PROPERTY VALUE SOURCE volume1 version 15 default
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 is currently running ZFS pool version 28.
Successfully upgraded 'volume1' from version 15 to version 28
zpool get version volume1
NAME PROPERTY VALUE SOURCE
volume1 version 28 default
The upgrade itself should only take a seconds and is non-disruptive. However, the upgrade is non-reversible.
