pfSense to OPNsense: what transfers, what you rebuild

There is no supported upgrade path from pfSense to OPNsense. The projects share an ancestor and have diverged for years; the configuration formats are related but not compatible, and importing one into the other produces a firewall that looks configured and is not.

The migration is a rebuild. That sounds worse than it is — a firewall configuration is mostly a set of decisions, and rebuilding is a chance to drop the rules nobody can explain. What follows is what carries across, what has to be redone, and how to roll back when the cutover goes sideways.

Why people move

Usually licensing and release policy rather than technology. Both are capable firewalls on FreeBSD; feature sets overlap heavily. The honest reasons we hear are wanting a predictable release cadence, wanting the web UI plugin model, or an organisational policy about the licence.

What is not a good reason: performance. On the same hardware with the same rules, the difference is not what makes a slow firewall fast. If throughput is the problem, look at the NIC, the ruleset and whether hardware offload is fighting you — on either platform.

What transfers and what does not

Check plugin equivalence before committing. If the deployment depends on a pfSense package with no OPNsense counterpart, that is the whole decision — find it before the migration weekend, not during it.

Order of work

• •Export the pfSense config.xml. It is the reference document even though it will not be imported.
• •Inventory rules and ask, for each, what it is for. Rules with no answer are candidates for removal rather than migration.
• •Build OPNsense in a VM first, with the same interface layout. Everything can be configured and reviewed before hardware is involved.
• •Recreate in order: interfaces, aliases, NAT, firewall rules, VPN, services.
• •Export the CA and certificates from pfSense and import them, so VPN clients are not all reissued.
• •Test against the VM with a laptop on the LAN side before touching the production path.

# aliases are the most mechanical part and the easiest to script
# pull them out of the pfSense export for review or transformation
xmllint --xpath '//aliases/alias' config.xml \
  | sed 's|</alias>|</alias>\n|g'

# the same file is the source for DHCP static mappings
xmllint --xpath '//dhcpd//staticmap' config.xml | head

Rules are where the time goes

Both platforms use pf underneath, so the concepts map: interface, source, destination, port, action. The differences that catch people out are in the periphery.

• •Rule evaluation order and the placement of floating rules differ enough to be worth re-checking rather than assuming.
• •Interface group behaviour is not identical — verify which rules apply to which interfaces after the rebuild.
• •Default deny is the same; what differs is the surrounding automatic rules, so read them rather than assume parity.
• •Rule descriptions are not decoration. Copy them across. The next person needs the reason, not the syntax.

A rebuild typically produces fewer rules than the original. In every migration we have done, part of the old ruleset was for systems that no longer exist. Removing those is real value, and it only happens because the rebuild forces the review.

Cutover and rollback

The plan that works: keep the pfSense box intact and physically present. Do not repurpose the hardware, do not wipe it. Cutover is a cable move and a gateway change, which means rollback is also a cable move.

• •Pick a window when someone can be on site, because the failure mode is losing remote access to the firewall.
• •Have console access to the new box that does not depend on the network being right.
• •Bring VPN tunnels up before the cutover where the far end allows a second peer — it removes the biggest unknown from the window.
• •Test from a client on the LAN, not from the firewall itself. The firewall can reach things a client cannot.
• •Leave the old unit powered off but wired for at least a week.

After cutover

• •Watch the state table and logs under real load, not just at the moment of the switch.
• •Verify every VPN tunnel carries traffic, rather than merely showing as established.
• •Check MTU across tunnels with a large transfer — this is where a rebuilt VPN differs subtly from the original.
• •Re-test outbound NAT for anything that depends on a specific source address.
• •Confirm backups of the new configuration are running before the week is out.

Where this fits

We do firewall migrations as fixed-scope work: rule audit, rebuild in a lab, cutover with a rollback plan, and the post-cutover verification list above. Billed at €65/hour, and the rule audit alone is frequently worth it even when the migration does not go ahead.