Pre-Upgrade Tasks

Make a Backup … and a Backup Plan

Before making any modifications to a firewall, the best practice is to make a backup using the WebGUI:

  • Navigate to Diagnostics > Backup/Restore

  • Set the Backup Area to All in the Backup Configuration section of the page

  • Click fa-download Download

  • Save this file somewhere safe

Keep multiple copies of the backup file in different secure locations. Consider using the free Auto Config Backup service (Using the AutoConfigBackup Service). Auto Config Backup can create a manual backup with a note identifying the change, which is encrypted and stored on Netgate servers.

Another good practice is to have install media handy for the new release, in case something goes awry and a reinstall is required. Should that happen, have the backup file on hand and refer to Backup and Recovery.

Check and Clean Up ZFS Boot Environments

Systems running pfSense Plus software installed using ZFS will automatically create ZFS Boot Environment entries during the upgrade process as a safety measure so users can boot back into the previous version easily. These entries consume space which presents itself as shrinking disk capacity and less free space on the disk. Eventually if left unchecked there may not be sufficient room to contain an upgrade without removing older boot environments.

See also

See Boot Environment Disk Space Usage for more information about ZFS Boot Environment space usage.

Tip

The amount of space consumed by a boot environment varies depending on how much the disk contents change during and after an upgrade. It is safer to estimate on the high side and consider it may use at least 1.5-2GB for a major upgrade. Upgrades that involve less changes on the filesystem will use less.

Before any upgrade, navigate to System > Boot Environments and review the list. Remove older entries which are no longer necessary (Managing Boot Environments in the GUI). Typically users only keep the latest 2-3 entries but preferences vary.

Low Memory Hardware and AWS/Azure Instances

Hardware with 1 GiB or less available memory may have issues upgrading depending on which features, services, or packages are running. This includes some Netgate hardware such as the Netgate 1100 when running with ZFS and/or certain services/packages. For the best chance of success in these cases, temporarily disable any non-critical services before starting the upgrade.

Tip

A Pre-Upgrade Reboot can also temporarily reduce memory used for ZFS caching, which can help in this situation as well.

pfSense Plus software can no longer run on AWS “.nano” size instances as they lack sufficient RAM to upgrade properly. Attempting to upgrade a “.nano” instance to pfSense Plus software version 24.03 will fail before the upgrade is performed. Migrate the instance to a “.micro” or larger size before attempting to upgrade, or redeploy instead.

Similar to the above, pfSense Plus software can no longer run on Azure A0 instances. Migrate to instances with more memory.

Remove / Dismount any Installation Media

Some users leave an installation disk plugged in or mounted for various reasons, but this can interfere with the upgrade process. Be sure to dismount and remove any installation media such as a USB thumb drive, optical disk, or ISO in a virtual drive. This includes items mounted via Hypervisors/Virtual Machine emulated or passed-through hardware, IPMI virtual media, and other similar mechanism.

VM Snapshots

An easy fall-back plan for virtualized firewalls is to take a snapshot of the VM before performing an upgrade. This way, it can easily roll back to a known-good state if the VM encounters a problem.

Note

Before rolling back a VM due to problems, ensure the hardware compatibility of the VM is current and update the VM Guest operating system to match the upgraded OS if there is a matching choice in the Hypervisor.

Pre-Upgrade Reboot

Reboot the firewall before applying an update. This step is optional, but a best practice.

If the hardware has a problem, such as a disk issue, then performing a reboot before the upgrade will allow that to be identified early. Otherwise, a hardware issue could be confused with an issue that occurred as a result of the upgrade process.

If the installation is using ZFS, a reboot will reset the amount of memory the OS is using for ZFS caching as well, which can help ensure the upgrade runs smoothly.

There is still a chance that the upgrade could draw out a hardware issue, such as a disk failing from the writes that happen in the upgrade process, but that is much less common to see in practice.

Packages

Warning

When the firewall is configured to pull packages from a release newer than the one current running, Do not upgrade packages before upgrading pfSense® software. Either remove all packages or leave the packages alone before running the update.

The safest practice is to remove all packages before upgrading to a new release. The upgrade process will handle packages automatically, but packages are frequently a source of problems. To ensure a smooth upgrade, note the installed packages, remove them, perform the upgrade, and then reinstall when the upgrade is complete.