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.


The amount of space consumed by a boot enviroment varies depending on how much the disk contents change during and after an upgrade. It is safer to estimate on the high side and consdier 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.

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.

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.


Before rolling back a VM due to problems, ensure the hardware compatibility of the VM is current. For example, on ESX 6.7, ensure the hardware compatibility is set to ESXi 6.7 and later (VM version 14) and update the VM Guest operating system to match the upgraded OS, such as Other/FreeBSD 11 (64-bit)

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.

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.



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.