Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedConfiguration~30 min

Break/Fix: Backup Restored To Wrong Hardware Leaves Interfaces Mismatched

Reported symptoms

  • ●After restoring config.xml, the firewall has no connectivity on any interface
  • ●Interfaces → Assignments shows the WAN/LAN assignments unbound or missing
  • ●The backup was taken on different hardware (or a different VM) than the target

Evidence

  • · /conf/config.xml lists "ix0" as WAN but the new box has "igc0" as its first NIC
  • · ifconfig shows the physical NICs renamed (driver difference between source and target)
  • · No default route is installed because no WAN gateway is bound
Diagnosis and resolutionclick to reveal

Root cause

config.xml contains hard references to interface names (ix0, em0, vtnet0, etc.). If the new hardware uses different driver names, those references dangle. OPNsense has an interface re-mapping wizard, but it only fires if invoked explicitly.

Remediation

1. Connect via console. 2. Run option 1 (Assign interfaces) to manually remap each interface to its physical NIC. 3. Reassign WAN/LAN/VLANs as needed. 4. Verify each interface has the correct IP and the gateway is back. 5. Confirm the firewall has outbound connectivity.

Verification

All interfaces show their expected IPs; default route is present; outbound connectivity works; LAN clients can reach the GUI.

Prevention

Restore backups only to identical or carefully prepared hardware. For VM-to-VM migrations, use OPNsense's import/export flow that intentionally walks through the interface mapping. Document the source hardware's NIC layout in your change record. Keep a hardware profile (driver names, NIC order) per firewall.

Scenario

You are migrating an OPNsense installation to new hardware (or a new VM). The following symptoms appear:

  • After restoring config.xml, the firewall has no connectivity on any interface
  • Interfaces → Assignments shows the WAN/LAN assignments unbound or missing
  • The backup was taken on different hardware (or a different VM) than the target

Available evidence:

  • /conf/config.xml lists “ix0” as WAN but the new box has “igc0” as its first NIC
  • ifconfig shows the physical NICs renamed (driver difference between source and target)
  • No default route is installed because no WAN gateway is bound

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XL:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Connect via console. 2. Run option 1 (Assign interfaces) to manually remap each interface to its physical NIC. 3. Reassign WAN/LAN/VLANs as needed. 4. Verify each interface has the correct IP and the gateway is back. 5. Confirm the firewall has outbound connectivity.

Verification

All interfaces show their expected IPs; default route is present; outbound connectivity works; LAN clients can reach the GUI.

Rollback

If mapping is unclear, boot from a known-good backup and start over with a fresh config.

Prevention

Restore backups only to identical or carefully prepared hardware. For VM-to-VM migrations, use OPNsense’s import/export flow that intentionally walks through the interface mapping. Document the source hardware’s NIC layout in your change record. Keep a hardware profile (driver names, NIC order) per firewall.