Migration#
There is one migration path with tooling behind it: OPNsense. tools/opnsense-import.py
reads a config.xml and writes two files — a list of VyOS set commands and a report in
Markdown saying what came across, what came across differently, and what could not come
across at all. Nothing is applied by the importer. Feeding the commands to a router is a
separate, deliberate step.
That separation is the point. A migration you cannot read before you run it is a migration you find out about at 3am on a Tuesday.
The order#
- Turn a
config.xmlinto VyOS commands. Export the configuration from the router you are replacing, run the importer, choose the interface mapping. - Read the migration report. Every line under Not translated is work you still have to do. Do this before you boot anything.
- Build a seed that installs the replacement. One ISO carries the answers, the configuration and the passwords; the new box installs itself.
- Check a running router against the configuration it should have.
--check-againstcompares a live router with what the import expected and exits non-zero when something is missing.
What the importer covers, in one table#
Each row is a section of tools/opnsense-import.py. The detail — including the rule
numbers it chooses and the aliases it can and cannot resolve — is in
Turn a config.xml into VyOS commands.
| Area | Comes across |
|---|---|
| System | Host name, domain, resolvers, time zone, and SSH if it was enabled |
| Interfaces | Ethernet ports with their addresses, static or DHCP, and their descriptions |
| Routes | Static routes, with OPNsense gateway names resolved to their next hop |
| NAT | Outbound masquerade, and every enabled port forward with host and port aliases resolved |
| Firewall | A default-drop ruleset on both address families that admits exactly what the forwards need |
| DHCP | The pool, its options, the PXE handoff and every reservation |
| DNS | Forwarding with its listen address, its allowed source network and its static hosts |
| QoS | The upload pipe, as CAKE on the WAN's egress |
And what does not, in one list: FreeBSD-only plugins, UPnP, NAT reflection, wildcard DNS records, per-reservation resolvers, virtual IPs, local user accounts, anything that was disabled on the old router, and every VPN tunnel. Each of those is named in the report with the reason — see Read the migration report.
Where the tool lives#
| Where you are | The command |
|---|---|
| A checkout of the repository | tools/opnsense-import.py |
| A Wheelhouse router | wheelhouse-opnsense-import |
Both are the same script. It is Python 3 with no third-party imports, so it runs on a laptop with nothing installed.
Checked against tools/opnsense-import.py ·
tools/wheelhouse-seed.py ·
docs/unattended-install.md