Upgrading High Availability Clusters

This document provides guidance on upgrading redundant firewalls in a high availability configuration across major versions of pfSense® software.

Upgrading from one version to another generally follows the this procedure, exceptions are noted later in the page:

  • Review release notes, blog, and upgrade guide.

  • Take a backup from both nodes.

    Danger

    Do not skip this step, backups are critical!

  • Upgrade the secondary node as described in the Upgrade Guide.

  • Test the secondary node to be sure it is operating as expected – correct packages present, services running, no obvious errors in logs, etc.

  • Enter Persistent CARP maintenance mode on the primary node from Status > CARP.

  • Ensure traffic is still flowing properly and that the network is functional.

    If it is not, then exit maintenance mode on the primary node, fix the secondary node, then try again.

  • Upgrade the primary node as described in the Upgrade Guide.

  • Check the primary node to ensure it upgraded and is operating as expected – correct packages present, services running, no obvious errors in logs, etc.

  • Leave Persistent CARP maintenance mode on the primary node.

  • Test everything again.

Tip

If this cluster is using the ISC DHCP backend, consider converting to the Kea DHCP backend as the ISC DHCP backend is deprecated and will be removed in the near future. See Converting High Availability DHCP from ISC to Kea for details.

XMLRPC Config Sync Considerations

Upgrade either the primary or the secondary first, leaving the other on the older version until testing is complete.

Supported versions of pfSense software from the last several years properly check for and prevent unintentionally synchronizing data between incompatible versions.

pfsync considerations

The underlying pfsync protocol often changes between FreeBSD versions. Versions of pfSense software with a different base OS version of FreeBSD may not be capable of synchronizing their states between each other. Failover will still function, but not stateful failover so all existing connections will be dropped.

pfsync and State Policy

The State Policy (Firewall State Policy) of the firewall can introduce a conflict in state synchronization if nodes using pfsync do not have identical hardware.

See pfsync and Physical Interfaces for details and a potential workaround.

CARP considerations

CARP is generally the same between versions and will fail over and back as expected.