pfSense has a good Upgrade Guide with a varity of options for how to upgrade the popular firewall software.

Here’s my favorite method, refined over a few years and multiple re-reads of the documentation.

  1. Take a backup, both via Auto Config Backup, if configured, and locally (Diagnostics -> Backup and Restore). Make sure you do this from both routers, if using High Availability (HA).

  2. Reboot the router(s). As mentioned in the documentation, this helps make sure your router can still reboot, before you start changing things.

  3. Make sure you have console access to the router that won’t go down when you reboot it. Much of the upgrade happens after a reboot, at which point you lose all visibility via the web interface and/or via SSH. Do this before you initiate the upgrade (I like to initiate the upgrade from the IPMI console, to “prove” that it’s working before I break something).

    In my case, I have two routers configured in a HA setup. With the primary still routing traffic, I use a VPN connection through that router to open an IPMI connection to the secondary router. When uprading the primary, these paths are reversed.

  4. From the web interface, navigate to System -> Update and ensure the Branch to which you wish to update is selected.

  5. At this point, I like to start a screen recording so I can go back and investigate if anything goes awry. Quicktime Player on a Mac is good for this.

  6. From the console (IPMI or otherwise), type 8 to open a shell, and then type:

    pfSense-upgrade -4

    This starts the upgrade process and forces the router to use IPv4 (otherwise, it will default to IPv6, if configured, which I’ve found to be more buggy). It also provides more details and immediate feedback than the web interface.

    I’ve seen this process hang due to intermittent network issues during the download. It seems to be safe to hit Control-C to cancel the process and re-run this command (it even picks up where it left off!).

  7. The router will download packages and reboot to begin the upgrade. This is where the IPMI console with a screen recorder (or VGA console with a camera phone recording a video) can be particularly helpful in case something goes wrong.

  8. After the upgrade, the router boots up immediately. I like to give it one more reboot at this point to prove that the router can still reboot cleanly.

  9. At this point, if you’re using a single router (no HA), you’re done. If you have a second router to upgrade, once the secondary router is online again, go to Status -> CARP on the primary and hit Enter Persistent CARP Maintenance Mode. This forces the primary router to fail over all Virtual IPs to the secondary router, allowing you to safely upgrade and reboot without the routers flapping back and forth.

  10. Repeat steps 3-7 for the primary router, and be sure to press Leave Persistent CARP Maintenance Mode on the primary when you’re done.

That should do it. May you have many seamless pfSense upgrades!