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. This includes RC, Beta, and other releases. So long as you are moving from an older version to a newer version, it will work unless noted otherwise.

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 Gold 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 will fail to reboot on its own. You will have to power cycle the system to complete the upgrade. 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.

Note for Captive Portal RADIUS WISPr Bandwidth Users

The WISPr RADIUS attributes were incorrectly applied to all versions pre-2.0 release. They were applied as Kbps where WISPr is supposed to be bps, hence those using WISPr attributes will have one one-thousandth of your previous bandwidth unless your RADIUS server is corrected. Your RADIUS server will need to have these values updated to bps for proper functionality once upgraded to 2.0 release or newer versions.

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.

pfSense 2.1 Upgrade Notes

See the CARP section at the end of this article for a CARP-specific pfsync note about 2.1 upgrades.

Additionally, if upgrading from pfSense 2.0.x to pfSense 2.1:

The "State Killing on Gateway Failure" feature now kills ALL states when a gateway has been detected as down, not just states on the failing WAN. This is done because otherwise the LAN-side states were not killed appropriately, and thus some connections would be in limbo, especially SIP. Due to the change in its behavior, "State Killing on Gateway Failure" is now disabled by default in new configurations and is disabled during upgrade regardless of the user's previously chosen setting. If you want the feature even with its new behavior, it must be manually re-enabled post-upgrade. This setting is located on System > Advanced on the Miscellaneous tab.

The "Allow IPv6" checkbox is NOT changed on upgrade unlike it was in early 2.1 BETA firmware. This was changed so that the user's chosen existing behavior is preserved. To allow IPv6 traffic, the setting must be changed manually. This setting is located on System > Advanced on the Networking tab.

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 /etc/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).

VM Snapshots

An easy fallback plan for virtualized firewalls is to take a snapshot of the VM before performing an upgrade. This way, if anything should go wrong, you can easily roll back to a known-good state.

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.

If upgrading from any previous version of pfSense (1.2.x, 2.0.x, etc) to pfSense 2.1 in a CARP environment, note that you should ensure that your pfsync interface has a rule to pass the correct traffic for state synchronization to work properly. pfSense 2.1 removed the automatic pfsync rule, since the documentation always recommended adding it manually and to add it behind the scenes with no way to block it could be counter-productive and potentially insecure. If you did not follow the documentation and add your own pfsync or allow all rule on the sync interface, your state synchronization may break after this upgrade. Add an appropriate rule to the sync interface and it will work again. At a minimum, you should pass traffic of the pfsync protocol from a source of your synchronization subnet to all CARP nodes.

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.