Having recently completed a migration of a multi-WAN, VLAN-heavy, and package-dependent pfSense firewall from an aging appliance to new hardware, I was struck by the lack of a single, authoritative guide for handling complex configurations. The built-in XML backup is a starting point, but it's dangerously naive to assume it's a complete solution for anything beyond a basic setup. A true best practice must account for stateful data, package idiosyncrasies, certificate stores, and potential hardware or version disparities.
Based on my analysis, a robust backup and migration strategy should be segmented into distinct, verifiable phases. The core failure point is assuming homogeneity between source and target systems.
**Pre-Migration Backup & Documentation:**
* **Comprehensive XML Config:** Execute a backup via the GUI, but also pull it via SSH/console using `pfSense-backup.sh` to capture the raw XML.
* **Package Inventory & State:**
* Document every installed package (e.g., Snort, Ntopng, HAProxy, ACME).
* For critical packages, manually export their configuration data. For instance, Snort requires a separate backup of its rules and variables.
* Note any custom binary packages or repositories.
* **Cryptographic Material:** Securely export any custom Certificate Authorities, certificates, and private keys. The XML encrypts private keys, but having them separately is prudent.
* **Network State Capture:** Document DHCP leases, static ARP entries, and any states you may need to preserve (though often, a state table reset is acceptable during a migration window).
**Migration Execution Considerations:**
* **Version Alignment:** The absolute best practice is to migrate to an identical pfSense version (including minor/patch level) on the target hardware first. This minimizes XML schema and package compatibility issues.
* **Staged Restoration:** Do not blindly upload the XML to a fresh install. Instead:
* Build the base system (interfaces, VLANs, basic firewall rules).
* Reinstall required packages *before* restoring the full config, allowing their structures to be initialized.
* Then, restore the full XML backup.
* **Hardware Abstraction:** If migrating to dissimilar NICs, you must either pre-configure the interface assignments on the target box to match the XML, or be prepared to manually reassign them post-restore. This is where most migrations fail.
**Post-Migration Validation:**
This phase is non-negotiable. A configuration restore is not a success until functionality is proven.
* Conduct a rule-by-rule audit of critical firewall and NAT policies.
* Verify VPN tunnels (IPsec, OpenVPN) can re-establish, focusing on phase 1 and 2 parameters.
* Test all port forwards and associated firewall rule states.
* Validate package functionality, especially for IDS/IPS and proxy services.
My core contention is that the "backup" is not merely a file, but a documented process encompassing system state, dependencies, and a rollback plan. Has the community developed a more streamlined, automated toolkit for this, or do we all rely on this manual, albeit thorough, checklist? I am particularly interested in evidence-based experiences migrating configurations with complex captive portal or multi-site IPsec deployments.
—LJ