Upgrading pfSense - Version Upgrade and Migration Guide

Keeping pfSense up to date is essential for maintaining security, stability, and access to new features. Security patches address discovered vulnerabilities, while minor and major releases introduce functional improvements and platform changes. This guide covers the full upgrade lifecycle: prerequisites, the upgrade process itself, major version transitions, rollback strategies, and post-upgrade troubleshooting.

Prerequisites

A successful upgrade requires preparation. Skipping these steps risks configuration loss, extended downtime, or a system that fails to boot after the update.

Back Up the Configuration

A configuration backup is the only reliable way to restore the firewall after a failed upgrade. Export the configuration through Diagnostics > Backup & Restore.

1. Navigate to Diagnostics > Backup & Restore.
2. Under Backup Configuration, select ALL in the Backup area field.
3. Enable Encrypt this Configuration File if the backup will be stored in an unsecured location.
4. Click Download Configuration as XML.
5. Store the file in a safe location - not on the firewall itself.

Warning:

The configuration backup does not include package data, filesystem contents outside /cf/conf/, or manually placed custom scripts. If the firewall has been modified beyond standard configuration, back up those files separately.

Review the Release Notes

Before upgrading, read the release notes for the target version. Release notes document:

• removed or changed features;
• configuration format changes;
• known issues and incompatibilities;
• hardware requirements (for example, mandatory AES-NI support in certain releases).

Release notes are published in the Netgate documentation portal.

Verify Package Compatibility

Installed packages may not be compatible with the target pfSense version. Before upgrading:

1. Navigate to System > Package Manager > Installed Packages.
2. Record the names and versions of all installed packages.
3. Check the Netgate forum and bug tracker for known issues with those packages on the target version.

Packages that have not been ported to the new version will be removed automatically during the upgrade. They will need to be reinstalled from the repository after the upgrade completes, if available.

Additional Recommendations

• Virtual environments: take a VM snapshot before starting the upgrade. This enables instant rollback without restoring from a configuration backup.
• Physical hardware: ensure console access is available (serial port, IPMI, iLO, or iDRAC) in case the web interface becomes unreachable after the upgrade.
• Pre-upgrade reboot: reboot the firewall before starting the upgrade procedure. This confirms that the system starts cleanly and that there are no hidden filesystem issues.
• Internet connectivity: the firewall must be able to reach Netgate update servers to download upgrade files. Verify DNS resolution and routing on the WAN interface.

Upgrading via the Web Interface

The web interface is the recommended upgrade method for most deployments. The process is automated: it downloads the update, verifies integrity, installs it, and reboots the system.

Checking for Updates

1. Navigate to System > Update.
2. In the Branch field, select the update branch. For production environments, use the stable branch (Latest stable version). Development and Release Candidate branches are intended for test environments only.
3. The system will check for available updates and display the target version if an upgrade is available.

Fig. 1. System > Update - checking for available updates

If the system is already running the latest version, a message indicates that no updates are available.

Performing the Upgrade

1. Once an update is detected, click Confirm (or Invoke Update, depending on the interface version).
2. The system downloads the update files, verifies their integrity, and begins installation.
3. A detailed installation log is displayed during the process. Do not close the browser or manually reboot the firewall.
4. After installation completes, the system reboots automatically.

Fig. 2. Upgrade in progress - installation log

5. After the reboot, log into the web interface and verify the version under System > Update or in the System Information widget on the Dashboard.
6. Check the installed packages under System > Package Manager > Installed Packages and reinstall any that are missing.

Warning:

The firewall stops processing traffic during the reboot phase of the upgrade. For high-availability deployments, switch traffic to the standby CARP node beforehand, or schedule a maintenance window.

Upgrading via the Console

Console-based upgrades are appropriate for headless systems, remote administration over SSH, and situations where the web interface is unavailable.

Upgrading from the Console Menu

1. Connect to the firewall console (serial port, SSH, or physical console).
2. From the pfSense main menu, select option 13) Update from console.
3. The system checks for updates, downloads the required files, and performs the installation.
4. After installation, the system reboots automatically.

Upgrading from the Command Line

For fully automated upgrades from the shell:

pfSense-upgrade -d      # Download and install update

Additional options:

pfSense-upgrade -c       # Check for available updates without installing
pfSense-upgrade -d -y    # Download, install and auto-confirm prompts

Warning:

The pfSense-upgrade command initiates a reboot after installation completes. SSH sessions will be disconnected. Ensure that you can reconnect after the reboot.

Using pkg Directly

In certain situations (for example, diagnostics), administrators may interact with the FreeBSD package manager directly. This method is not recommended for routine upgrades and can damage the system.

pkg-static upgrade -f    # Force reinstall of all packages (diagnostic use only)

Direct pkg usage is acceptable only when coordinating with Netgate support or when recovering a broken package database.

Major Version Upgrades

Upgrades between major versions (for example, 2.6.x to 2.7.x) require additional caution. These upgrades frequently involve changes to the underlying FreeBSD version, PHP version, configuration format, and the set of supported packages.

Common Changes in Major Upgrades

Major Upgrade Procedure

1. Verify the upgrade path. Not all versions support a direct jump. For instance, upgrading from 2.4.x to 2.7.x may require an intermediate upgrade to 2.5.x first. The supported upgrade path is documented by Netgate.
2. Test first. If possible, perform the upgrade on identical hardware in a test environment. This reveals driver and package issues before touching the production system.
3. Record the current state. In addition to a configuration backup, save:
   • routing table (netstat -rn);
   • interface state (ifconfig -a);
   • PF rules (pfctl -sr);
   • NAT rules (pfctl -sn).
4. Perform the upgrade via the web interface or console using the standard procedure.
5. Verify the system after the upgrade. Confirm that all interfaces, routing, firewall rules, VPN tunnels, and critical services are functioning correctly.

Package Compatibility in Major Upgrades

During major version upgrades, all installed packages are removed and reinstalled from the target version repository. Packages not ported to the new version will be unavailable. Before upgrading, determine whether alternatives exist for any critical packages that may not carry over.

Rollback

pfSense does not provide a built-in operating system-level rollback mechanism. Reverting to a previous version is accomplished through one of the following methods.

Restoring from a VM Snapshot

The fastest method is reverting to a VM snapshot taken before the upgrade. The procedure varies by hypervisor:

• VMware ESXi: Snapshot Manager - select the snapshot - Revert.
• Proxmox VE: Datacenter - select the VM - Snapshots - Rollback.
• Hyper-V: Checkpoints - Apply.

After restoring the snapshot, the virtual machine returns to its pre-upgrade state, including configuration, filesystem, and pfSense version.

Reinstalling with Configuration Restore

If no VM snapshot is available or the system runs on physical hardware:

1. Install the previous pfSense version from installation media.
2. Complete the basic installation with default settings.
3. Log into the web interface and navigate to Diagnostics > Backup & Restore.
4. Under Restore Backup, upload the previously saved XML configuration file.
5. Confirm the restore. The system applies the configuration and reboots.

Warning:

Restoring a configuration from a newer pfSense version onto an older one may fail if the configuration contains parameters absent in the target version. In such cases, manually edit the XML file to remove unsupported sections before importing.

ZFS Systems (pfSense Plus)

pfSense Plus with the ZFS filesystem supports Boot Environments. Before an upgrade, the system automatically creates a boot environment with the current state. To roll back:

1. Reboot the firewall.
2. In the boot loader, select the previous boot environment.
3. The system boots with the prior version and configuration.

Boot environments can be managed from the console menu or the command line:

bectl list        # List available boot environments
bectl activate BE_name   # Set boot environment for next reboot

Migration from Other Platforms

pfSense does not support importing configurations from other firewalls - Cisco ASA, FortiGate, MikroTik, OPNsense, or Sophos. The configuration must be planned and built from scratch.

Planning a Migration

When transitioning from another platform, prepare in advance:

1. Document the existing configuration - firewall rules, NAT, routes, VPN tunnels, DHCP pools, DNS settings.
2. Map feature equivalences. Not all features of the source platform have direct counterparts in pfSense. For example, FortiGate Application Control does not have an equivalent mechanism in pfSense.
3. Plan interface addressing. Interface names in pfSense (WAN, LAN, OPTx) differ from the naming conventions of the source platform.
4. Set up a test environment. Before switching production traffic, deploy pfSense in parallel and validate all critical functions.

Migration from OPNsense

OPNsense shares historical roots with pfSense, but the configuration formats have diverged. Direct import of a config.xml from OPNsense into pfSense is not supported. The configuration must be recreated manually.

Troubleshooting

Upgrade Is Stuck

If the upgrade process has stalled and shows no progress for more than 30 minutes:

1. Do not power-cycle the firewall - this can corrupt the filesystem.
2. Connect to the console (serial port or SSH if still available).
3. Check whether the upgrade process is running:

ps aux | grep pfSense-upgrade

4. If no upgrade process is listed, attempt to restart the upgrade:

pfSense-upgrade -d

5. If there are filesystem errors, run a check:

fsck -y /

Packages Broken After Upgrade

After an upgrade, installed packages may need to be reinstalled:

1. Navigate to System > Package Manager > Installed Packages.
2. If a package is listed but not functioning - remove it and install again.
3. If the package is not available in the target version repository - find an alternative or contact the package developer.

For diagnosing issues with a specific package:

pkg info <package_name>        # Check installed package info
pkg check -d -a                # Verify package dependencies

System Does Not Boot After Upgrade

If the firewall fails to boot after an upgrade:

1. Connect a monitor and keyboard (or a serial console).
2. In the boot loader, select Boot Single User (option 2 in the loader menu).
3. Check the filesystem:

fsck -y /
mount -u /

4. Review the upgrade log:

cat /cf/conf/upgrade_log.latest.txt

5. If recovery is not possible - reinstall pfSense and restore from a configuration backup.

Web Interface Unreachable After Upgrade

If the web interface is inaccessible after the upgrade but the system has booted:

1. Connect to the console.
2. From the pfSense console menu, select option 2) Set interface(s) IP address and verify the LAN interface addressing.
3. Restart the web server:

/etc/rc.restart_webgui

4. Check for firewall rules blocking access to ports 80/443:

pfctl -sr | grep "pass.*80\|pass.*443"

DNS Errors After Upgrade

In some cases, the DNS resolver (Unbound or Dnsmasq) may fail to start after an upgrade:

1. Check the service status:

/usr/local/etc/rc.d/unbound.sh status

2. Restart the service:

/usr/local/etc/rc.d/unbound.sh restart

3. Validate the configuration for syntax errors:

unbound-checkconf

Related Sections

• pfSense System Requirements - verify hardware compatibility before upgrading, especially when transitioning between major versions
• pfSense Installation Guide - full system reinstallation when an upgrade is not possible or has failed
• pfSense Backup - configuration backup creation and management (section to be added in the next documentation wave)