Version-Specific Notes

This document covers specific concerns which must be taken into account by administrators when upgrading pfSense® software from an older version.

Review sections for each intermediate version between the version running on the firewall and the current release.

Upgrading from versions older than pfSense Plus 21.02.2 or pfSense CE 2.5.1

Warning

WireGuard was removed from the base system in releases after pfSense Plus 21.02-p1 and pfSense CE 2.5.0, when it was removed from FreeBSD.

If upgrading from a version that has WireGuard active, the upgrade will abort until all WireGuard tunnels are removed. For more details, see the Release Notes

WireGuard is available as an add-on package on pfSense Plus 21.05, pfSense CE 2.5.2, and later versions. The settings for the WireGuard add-on package are not compatible with the older base system configuration.

Note

The WireGuard package is still under active development. Follow the development progress on the developer’s YouTube channel

Upgrading from versions older than pfSense 2.5.0

  • The built-in relayd load balancer has been deprecated and removed as it does not compile or run on pfSense 2.5.0. A copy of the load balancer configuration will be left in /conf/deprecated_load_balancer.xml for reference when converting to an alternate solution, such as HAProxy (HAProxy package).

  • PHP was migrated from PHP 7.2 to PHP 7.4. A number of PHP errors were fixed along the way but certain combinations of configuration parameters may result in further errors. Note any problems on the Netgate Forum, and if possible, try to include relevant portions of config.xml with personal data removed.

  • Due to the significant nature of the changes in this version of pfSense software, warnings and error messages, particularly from PHP and package updates, are likely to occur during the upgrade process. These errors are primarily seen on the console as the upgrade is applied, but may appear in a crash report once the upgrade completes. In nearly all cases these errors are a harmless side effect of the changes between FreeBSD 11.2 and 12.x and between PHP 7.2 and PHP 7.4.

  • See the FreeBSD 12 Release Notes for information on deprecated hardware drivers that may impact firewalls upgrading to pfSense version 2.5.0. Some of these were renamed or folded into other drivers, others have been removed, and more are slated for removal in FreeBSD 13 in the future.

  • OpenSSL was upgraded to 1.1.1a as a part of upgrading to FreeBSD 12.0, this will impact all packages which depend on OpenSSL, especially those not obtained from Netgate. Be aware that this will require obtaining new versions of such packages after the upgrade.

Upgrading from versions older than pfSense 2.4.5-p1

  • Upgrading to pfSense software version 2.4.5-p1 requires pfSense-upgrade version 0.70 or later. Most installations will automatically pick up the new version and upgrade normally. If this does not happen automatically and the upgrade to version 2.4.5-p1 is not offered, use the following procedure:

    • Navigate to System > Updates

    • Set Branch to Previous stable version

    • Wait a few moments for the upgrade check to complete

    • Optional: Confirm that the latest version of pfSense-upgrade is present (version >= 0.70) using pkg-static info -x pfSense-upgrade.

      If the correct version is not present, wait a bit longer and check again as that package may be updating in the background.

    • Set Branch to Latest stable version

    • Wait a few moments for the upgrade check to complete

    At this point, the upgrade check should see 2.4.5-p1 and the upgrade can proceed.

  • pfSense software version 2.4.5-p1 includes pkg version 1.13.x which introduces a new metadata version. Most installations will automatically pick up the new version and upgrade normally. In certain cases, especially coming from much older versions, the pkg utility may require a manual update before it can correctly process the new metadata.

    The pkg utility can be upgraded manually with the following command run from an ssh or console shell:

    # pkg-static bootstrap -f

    See Repository Metadata Version Errors for more details.

Upgrading from versions older than pfSense 2.4.4

  • Third party packages from alternate repositories are causing problems for users with the upgrade process and also with post-upgrade behavior. These packages have never been supported, and had to be manually added by users outside of the GUI.

    Due to the major changes required for FreeBSD 11.2 and PHP 7.2, third party packages from alternate repositories cannot be present during the upgrade. There is no way to predict if a third party package supports the new version or will cause the upgrade itself to fail.

    The upgrade process will automatically remove pfSense-pkg-* packages installed from alternate repositories. After the upgrade completes, the user can reinstall these packages. Packages from alternate repositories will not appear in the Installed Packages list in the GUI, and must be entirely managed in the command line.

    This change does not affect packages installed from the official pfSense package repository.

  • Using the AutoConfigBackup Service is integrated into pfSense version 2.4.4 and free for all to use. It is no longer an add-on package. It is now located under Services > Auto Config Backup.

  • PHP was migrated from PHP 5.6 to PHP 7.2. A number of PHP errors were fixed along the way but certain combinations of configuration parameters may result in further errors. Note any problems on the Netgate Forum or the pfSense subreddit, and if possible, try to include relevant portions of config.xml with personal data removed.

  • Due to the significant nature of the changes in this version of pfSense software, warnings and error messages, particularly from PHP and package updates, are likely to occur during the upgrade process. These errors are primarily seen on the console as the upgrade is applied, but may appear in a crash report once the upgrade completes. In nearly all cases these errors are a harmless side effect of the changes between FreeBSD 11.1 and 11.2 and between PHP 5.6 and PHP 7.2.

  • Gateway handling changes in 2.4.4 may result in different default gateway behavior than previous releases. Nearly all cases should behave properly, but be aware that it may be necessary to re-select the default gateway after upgrade.

  • The FEC LAGG Protocol is deprecated and its options have been removed #8734

  • The login protection daemon was changed from sshlockout_pf to sshguard and the behavior may be more sensitive in some cases to SSH and GUI login failures. For example, be aware of possible issues where probes from monitoring systems may end up triggering a block.

  • Major changes to RADIUS for the base system and specifically Captive Portal could lead to behavior changes in certain cases. Read the release notes and associated bug reports for more details. Note any problems on the Netgate Forum or the pfSense subreddit.

  • A crash report containing no data (empty) may appear after the upgrade completes. See #8915

  • Intel Atom systems containing HD Graphics chipsets may experience console problems after the update. Affected systems will boot successfully, but fail to display console output after the boot menu. To fix the problem, add the following line as a Loader Tunable to use the syscons console type:

    kern.vty=sc

    • Alternately, try using i915 driver with the standard VT console using these lines as Loader Tunables:

      i915kms_load="YES"
drm.i915.enable_unsupported=1

      Warning

      This driver will consume extra bus resources and may cause resource hungry add-on hardware to fail, such as multi-port network adapters.

    • Systems with similar console problems not containing a graphics chip supported by the i915 driver may need to reinstall 2.4.4 to use a UEFI console.

  • An ISP that supplies a bogus interface MTU via DHCP may cause interface problems with certain network interface types when Advanced Configuration options are present on DHCP interfaces, such as a DHCP WAN. The typical default case is handled automatically, but advanced options override the corrected default behavior. To fix the problem, apply the patch from #8507 or add supersede interface-mtu 0 to the Option modifiers box in the WAN interface advanced DHCP options. If a custom dhclient.conf is in use, add supersede interface-mtu 0 on a line inside the interface block. See #8507. The Advanced Configuration case has been corrected for the next release.

Upgrading from versions older than pfSense 2.4.0

  • To use ZFS, a reinstall of the operating system is required. It is not possible to upgrade in-place from UFS to ZFS at this time.

  • Wireless interfaces must be created on the Wireless tab under Interfaces > Assignments before they are available for assignment

  • Some hardware devices may not boot 2.4.0 installation images, for example, due to UEFI compatibility changes. These are primarily BIOS issues and not issues with the installer images. Upgrading in place from 2.3.x typically allows affected hardware to run version 2.4.

  • To upgrade Firewalls in place which are running pfSense software version 2.2.x or earlier, first upgrade the firewall to pfSense 2.3.4 and then perform an update to pfSense 2.4.x afterward. Alternately, reinstall 2.4.x directly and restore the configuration.

Warning

When upgrading to 2.4.x from 2.2.x or earlier, remove all packages before attempting the update. Even when upgrading from 2.3.x this is the best practice to ensure a smooth upgrade process. Package settings are retained.

Older Version Upgrade Notes

Versions of pfSense software prior to 2.3 used a different upgrade method. For “full” installations, a tgz file was used by the firewall to copy in the new files. This method was problematic and is no longer used.

The best practice in these cases is to take a backup and reinstall with a current, supported version of pfSense software.

The following information is for upgrading from outdated and unsupported versions of pfSense software. They may still be of use to users attempting to upgrade from an older release to a current, supported, release.

When upgrading from a very old release, read every document below that covers versions between the older one being upgraded and the new version.