Personal tools

Upgrade Guide

From PFSenseDocs

Jump to: navigation, search
This article is part of the HOWTO series.


pfSense Upgrade Guide

The supported means of upgrading from one pfSense release to another depend on the platform being used. Any version of pfSense can be reliably upgraded to any newer 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 System > 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.

Changing architecture (32 bit to 64 bit or vice versa) during upgrade

Upgrading a 32 bit system to 64 bit, or vice versa, is not supported. If you want to change architecture you should reinstall and restore the configuration. The config is the same on both versions.

Upgrading from 32 bit to 64 bit mostly works fine with a couple caveats - your 32 bit RRD data is invalid on the 64 bit version and will have to be deleted by running 'rm -rf /var/db/rrd*'. You will lose all RRD history, this cannot be converted. Also after the upgrade, the reboot binary will be 64 bit which cannot run on a 32 bit platform, so the system may fail to reboot on its own. In that case you will have to power cycle the system. Many users have done this upgrade without seeing any caveats other than this, but it is not recommended.

2.0 Upgrade Note

When upgrading 1.2.3 to 2.0, you should uninstall all packages first, then perform the upgrade. Some old packages can cause problems with the configuration upgrade process, or possibly prevent the system from booting at all in some rare cases. After the upgrade is complete, the packages can be reinstalled. The configuration is automatically retained.

International/Special Characters in 1.2.x Configs

International characters, such as åäö and so on, were not supported on 1.2.3, but were allowed in some places due to overly lenient input validation and less strict XML parsing. This causes invalid XML, and as such if you were lucky enough to not have 1.2.x crash and toss out the config on you with such characters, it will not upgrade to 2.0 cleanly.

2.0 will reset and toss out the config on every reboot, leaving you at an "assign interfaces" prompt since it does not have a valid configuration.

You can run your config through an xml parser like xmllint and it will show you where the problems are. Fix them, and the configuration can be upgraded. The good news is that these characters are handled properly in most areas of the 2.0 GUI, and they are CDATA escaped so they are safe from such errors.

You can install the new Pre-2.0 Upgrade Check package (System > Packages, Available packages tab), and then go to Diagnostics > Pre-Upgrade Check. This package will check over your config.xml and alert you to potential issues.

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. It is very important to ensure you uninstall the open-vm-tools package before upgrading, and reinstall it after upgrading, as the old version will crash the new OS if you do not and leave you with an unbootable system.


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.

If you are on pfSense 1.2.3 or newer, you can download an upgrade image from the mirrors. Be sure to download an appropriate sized nanobsd upgrade file for your CF card. If you are unsure what size CF image was used to install originally, check /tmp/nanosize.txt

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

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.

Downgrading from pfSense 2.0 to 1.2 not possible

Because many 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. You must keep a backup of your 1.2.3 configuration and restore that if you wish to revert back after upgrading to 2.0.

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.3 to 2.0, going from FreeBSD 7.2 to 8.1).

Upgrading CARP

If you are going from 1.2.3 to 2.0, Check your CARP VIPs to make sure they are actually on the proper interface. That is, that the interface chosen for the VIP properly matches the subnet in which the CARP VIP resides, and that the subnet mask is proper. 2.0 validates this more strictly than 1.2.3 did, and as a consequence if you had misconfigured CARP VIPs on 1.2.3, they may not upgrade cleanly.

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.

NOTE for 2.0 upgrades: Refer to Redundant Firewalls Upgrade Guide for specifics for upgrading to 2.0 with CARP.