Upgrade Guide

From PFSenseDocs

This article is part of the HOWTO series.

Contents 1 pfSense Upgrade Guide 1.1 Full installation 1.2 Live CD 1.3 VMware Appliance 1.4 Embedded 1.5 SMP/Multiprocessor Users 1.6 Preparing a fall back plan 1.6.1 Downgrading to a previous release 1.6.2 Downgrading from pfSense 2.0 to 1.2 not possible 1.6.3 Reinstalling the previous release 1.7 Reinstalling packages 1.8 Upgrading CARP

pfSense Upgrade Guide

The supported means of upgrading from one pfSense release to another depend on the platform being used. Any non-embedded version of pfSense can be reliably upgraded to any other version while retaining the existing configuration.

First, as you should always do before upgrading any sort of system, make sure you have a good, up to date backup. You just need to visit the Backup/Restore page and download a backup of your configuration. Those with a pfSense Portal subscription should consider using the AutoConfigBackup and making a manual backup noting the reason as prior to upgrade.

Full installation

Download the full update file from your favorite mirror. In the web interface, visit the System -> Firmware page and upload that file there.

Alternatively, the console upgrade mechanism is preferred by some users. Enable SSH on the Advanced page, SSH into your pfSense install, and choose the console upgrade menu option. It's easiest to paste the URL of the update file location there. The system then automatically downloads and installs the specified update, including verification of the md5.

Live CD

For live CD installations, just burn the new CD, put it in your firewall, and reboot the system with the same configuration storage medium.

VMware Appliance

The VMware Appliance can be upgraded using the same methods as a full installation.

Embedded

Only the new nanobsd-based embedded supports upgrades. For those using an embedded release pre-1.2.3, you need to reflash with the appropriate sized nanobsd release for your CF card, then restore your configuration.

Be aware that some of the changes that come with NanoBSD may require fixes or updates to your BIOS or CF image.

ALIX Routers must have at least BIOS revision 0.99h. For help updating, see: ALIX BIOS Update Procedure

WRAP Routers will not work with stock 1.2.3 Embedded Images, see: NanoBSD on WRAP

For help with altering a CF image (before or after writing), for example to add your configuration without using the WebGUI, see: Modifying Embedded

SMP/Multiprocessor Users

Because of changes in the upgrade system between 1.0 and 1.2, after upgrading a 1.0 system to 1.2, you will be using a uniprocessor kernel. Previous installs defaulted to SMP kernels (and future releases will revert to that behavior) so if you are using a SMP system, it will now function as a single processor system. To install a SMP kernel, apply the 1.2 update file a second time. This time you will be prompted on the upgrade page for the kernel to use. Select SMP there, and apply the 1.2 update (though the install is already 1.2, it will still install the same 1.2 update and replace your kernel). If you are not prompted for which kernel to use, go to Diagnostics -> Command and run 'rm /boot/kernel/pfsense_kernel.txt'. Then go back to the upgrade screen and you will have that option.

Preparing a fall back plan

In case something goes wrong during the upgrade, plan for how you will recover prior to upgrading. There is a remote chance that a regression from one version to another, either in the pfSense or FreeBSD code, can leave your system unusable. With some advance planning, you can quickly return to the previous release.

Downgrading to a previous release

For those using a pfSense 1.2.x release, you can safely downgrade to a previous 1.2.x release by using the same upgrade methods, with the previous version's update file. If you upgrade to 1.2.1, you can safely use the 1.2 update file to downgrade back to 1.2. Your configuration will be retained.

Downgrading from pfSense 2.0 to 1.2 not possible

Because some of the changes in pfSense 2.0 bring vastly enhanced capabilities with significantly different configuration requirements, when upgrading from 1.2.x to 2.0, some portions of your configuration are converted to a structure that will not work correctly on any previous release. pfSense 2.0 is currently in ALPHA and not recommended for any production deployments at this time.

Reinstalling the previous release

The worst case scenario on upgrading is a FreeBSD regression leaving you with a system that no longer boots successfully, or no longer comes up on the network. In this case, you'll have to reinstall from CD. You may wish to have the live CD from the previous release available in case this is necessary. This is the least likely scenario, with maybe one in every ten or twenty thousand installs affected with upgrades containing significant FreeBSD release changes (such as pfSense 1.2 to 1.2.1, going from FreeBSD 6.2 to 7.0).

Reinstalling packages

After an upgrade, especially if you upgrade from 1.2 release to 1.2.1, 1.2.2 or 1.2.3, you should reinstall packages after the upgrade. To do so, browse to Diagnostics -> Backup/Restore and click "Reinstall packages".

Upgrading CARP

Generally the recommended path for upgrading a CARP pair is to first upgrade the secondary. After it comes back up, disable CARP on the primary under Status > CARP, and run on the secondary for a period of time. After you're comfortable the secondary is running as desired, upgrade the primary, and it will switch back to master after rebooting for the upgrade.

NOTE: the underlying pfsync protocol that synchronizes states between firewalls has changed formats between different FreeBSD versions and hence some upgrade scenarios will require dropping all states when switching the new version to master status. This is true when upgrading to 1.2.3 from any prior release.