Upgrade Process Overview

This is a brief overview of the process that takes place behind the scenes when an administrator initiates an upgrade. The process varies depending on the version of pfSense software and whether or not the firewall is capable of utilizing ZFS Boot Environments. Unless otherwise stated, all steps are performed by the firewall automatically.

See also

Traditional Upgrade Process (CE, Plus with UFS)

This is the traditional upgrade process using pkg, which is used by pfSense CE software as well as installations of pfSense Plus software installed using UFS:

  • Download update files

  • Upgrade kernel

  • Reboot (Offline down time starts)

  • Upgrade base files (Operating System, PHP code, etc.)

  • Upgrade base and add-on packages

  • Finish boot (Offline down time ends, back online and ready)

ZFS Boot Environments (First Generation, Plus 22.05-23.09.1)

This is the first generation of ZFS Boot Environment upgrade support, available from pfSense Plus software version 22.05 until 23.09.1:

  • Create and activate new ZFS Boot Environment from current point

  • Download update files

  • Upgrade kernel

  • Reboot (Offline down time starts)

  • Upgrade base files (Operating System, PHP code, etc.)

  • Upgrade base and add-on packages

  • Finish boot (Offline down time ends, back online and ready)

This process essentially makes an automatic local backup before starting so that administrators can manually roll back if there are problems with the upgrade.

ZFS Boot Environments (Second Generation, Plus 24.03 and later)

This is the second generation of ZFS Boot Environment upgrade behavior, which started on pfSense Plus software version 24.03:

  • Create new ZFS Boot Environment from current point

  • Download update files

  • Upgrade kernel inside the new Boot Environment

  • Upgrade base files (Operating System, PHP code, etc.) inside the new Boot Environment

  • Upgrade base and add-on packages inside the new Boot Environment

  • Check for errors inside the new Boot Environment and stop if any problems have occurred

  • Activate the new Boot Environment

  • Reboot (Offline down time starts)

  • Monitor for problems during reboot

    • If problems are detected, automatically activate the last known good Boot Environment and reboot

  • Finish boot (Offline down time ends, back online and ready)

This method involves less down time as the only down time is during the reboot and the bulk of the upgrade process is already complete by that point. It is more robust since it can automatically detect problems and roll back without manual intervention if need be, which makes remote upgrades safer. Prior ZFS Boot Environments are still available to roll back manually if users encounter problems not detected automatically.