Read the migration report#

report.md is the half of the import that is not commands. It lists, in the order the importer worked, everything that came across, everything that came across in a different shape, and everything that could not come across at all. The third list is the work you still have to do, and it is the reason this page exists: the commands file is quick to skim and quick to trust, and the things that will bite you in a fortnight are all in the report.

Read it before you boot anything.

Before you start#

• report.md from a run of the importer with --out.
• The old router still running, or at least still reachable, so you can check anything the report raises.

What the file looks like#

# OPNsense import report

Source: `/home/you/config.xml`

- translated: 31
- translated differently: 3
- not translated: 9

## Translated

- **interfaces**: lan igc0 -> eth0 (192.0.2.1/24)
- **nat**: forward 443 -> 192.0.2.10 (web)
...

## Translated differently

- **qos**: the shaper
  OPNsense shapes with dummynet pipes in both directions; this is CAKE on egress, which
  is the direction that actually controls a home uplink

## Not translated

- **plugins**: OpenVPN servers and clients
  configured and running upstream; set it up again on the new box

Each entry is an area, a detail, and — in the second and third sections — the reason. The counts at the top are the same three numbers the importer prints when it finishes.

Section 1 — Translated#

Everything that came across as it was. Read it for one purpose: to check that the count matches what you expect. The lines worth looking at every time:

Section 2 — Translated differently#

Things that arrived, but not in the shape they left. Nothing here is broken; each one is a decision the importer made because VyOS expresses the idea differently. Every entry carries its reason.

The ones you will actually see:

Interface names. lan was igc0, now eth0 appears for every port when you did not pass --map. If any of them is wrong, fix the mapping and re-run rather than editing the commands file — several later sections derive addresses from the interface section.

A forward matched on something other than the WAN. OPNsense can match a forward on an interface group or on a specific address; the import puts it on the WAN interface. If the old rule was deliberately scoped to a second uplink or a VLAN, re-add that scope from the NAT page.

The PXE boot file. The old router handed out a different loader per client architecture; VyOS has one file name per subnet, so one was chosen. If you boot both UEFI and legacy clients, dnsmasq is the answer.

The shaper. Two dummynet pipes became one CAKE policy on egress. See Shape a link with CAKE.

The router's own IPv6 rules. They are not read. What is written is default-deny on both families, so a box that gains IPv6 later is closed rather than open. Add the v6 rules you need from the Firewall page.

Section 3 — Not translated#

The work list. Every entry names something the old router was doing that the new one will not do until you set it up. Here is each one the importer can produce, what it means, and where to go.

Plugins that were running#

- **plugins**: OpenVPN servers and clients
  configured and running upstream; set it up again on the new box

The importer checks twelve OPNsense plugin trees and names any that were enabled.

NAT reflection#

- **nat**: NAT reflection on 3 forwards
  the router lets LAN clients reach these services by the WAN address; on VyOS that needs
  a second destination rule matched on the LAN plus source NAT back to the router, which
  is a decision, not a translation. Split-horizon DNS is usually the better answer

Two ways to close this, and the second is better on most networks.

1. Hairpin the forward. The NAT page's New port forward panel has a checkbox for it, and stages the extra destination rule plus the source NAT that makes the reply come back through the router. Step by step in Publish a service.
2. Answer the name differently inside. Give the service a name in an authoritative zone on the router's own resolver that points at its inside address, so LAN clients never touch the public one. Authoritative records for local names.

UPnP#

There is no UPnP answer on a Wheelhouse router, and the report says so wherever the old router had the plugin on. There is no service upnp configured and no catalogue app for it; the Companions page reports the gap rather than hiding it. Games consoles and some peer-to-peer clients that relied on it will need a port forward instead.

Wildcard DNS records#

- **dns**: wildcard record *.lab.example.com -> 192.0.2.10
  the VyOS forwarder answers for names, not wildcards; run a resolver that does
  (a dnsmasq container) if you need it

Wildcard DNS, per-host DHCP options and a PXE matrix is the whole answer: one dnsmasq app closes this and two other gaps at once.

Names for DHCP clients#

The old router registered its leases in DNS so printer.lan resolved without anyone typing it anywhere. The VyOS forwarder does not. Either give the hosts that need names a reservation plus a static host mapping, or hand DNS to dnsmasq, which does register its own leases.

Per-reservation resolvers#

VyOS hands out resolvers per subnet, not per reservation. If one host genuinely needs a different resolver from the rest of the segment, put it on its own subnet, or set the resolver on the host.

Local accounts#

- **system**: 4 local accounts
  password hashes do not carry between FreeBSD and Linux; the installer sets the console
  and web UI passwords

Create a Wheelhouse account per person, with the lowest role that works, on Administration → Users — Add an operator. The router's own shell accounts are separate and are covered in The console account and its SSH keys.

Virtual IPs#

Extra addresses the old router carried. Add them as additional addresses on the interface, from the interface panel:

set interfaces ethernet eth1 address 198.51.100.5/32

If they were a CARP pair rather than plain aliases, that is VRRP, not an address.

Interfaces that are not Ethernet ports#

Tunnel and VPN interfaces are configured by their own service. See the plugin table above.

Anything that was disabled#

Disabled interfaces, disabled forwards and disabled routes are skipped and reported. That is usually what you want; if one of them was disabled by accident, re-enable it on the old router and re-run the import rather than hand-editing the commands.

Rules on an interface that is not part of the import#

- **firewall**: rule on 'opt1' (guest to internet)
  that interface is not part of this import

Map that interface with --map and re-run, or re-create the rules by hand once the port exists on the new box.

Check it worked#

You have read the report when you can answer these without looking again:

• How many port forwards came across, and does that match the old router?
• Which interface is the LAN on the new box?
• What is on the Not translated list that your network actually uses?

Turn the third answer into a list, and work through it after the new box is up. A migration is not finished when the box boots; it is finished when that list is empty.

See also#

• Turn a config.xml into VyOS commands
• Build a seed that installs the replacement
• Check a running router against the configuration it should have
• Harden a router that faces the internet — do this once the new box is up, before it takes traffic

Checked against tools/opnsense-import.py · docs/apps.md · ui/src/pages/Openvpn.tsx · ui/src/pages/Daemons.tsx