Restore onto a different appliance — hardware replacement, configuration migration, IP changes

A different-appliance restore is the recovery procedure for a router that has been replaced (RMA, hardware failure, end-of-life) or a new router that takes over an old one’s role. The configuration from the old router is loaded onto the new router; the new router takes over.

The procedure is more complex than a same-appliance restore because the new router may have:

• Different interface names (eth0 vs eth1 vs ens3 vs enp0s3 depending on the platform).
• Different MAC addresses (the new router’s interfaces have new hardware addresses).
• Different IP addresses (if the new router replaces the old one in a different IP range).
• Different hardware capabilities (the new router may have different interface speeds, different number of ports, different cryptographic acceleration).

This lesson covers the hardware-replacement scenario, the configuration-migration scenario, the IP and interface changes that may be required, and the production failure modes where the migration goes wrong.

The hardware-replacement scenario

The original router fails (hardware failure, RMA). The operator receives a replacement router with the same model and interface layout. The operator’s goal: bring the replacement router up with the same configuration as the failed router.

flowchart LR
  OLD[Old router\nfailed] -->|config from Git| NEW[New router\nsame model]
  NEW -->|verify interfaces| CHECK{Interfaces\nmatch?}
  CHECK -->|yes| COMMIT[Commit and save]
  CHECK -->|no| FIX[Fix interface names]
  FIX --> CHECK
  COMMIT --> PRODUCTION[Production traffic]

The diagram shows the procedure: pull the configuration from Git; load it onto the new router; verify that the interface names match the new router’s hardware; commit and save. If the interface names do not match, the operator must edit the configuration to use the new names.

The configuration-migration scenario

A router is replaced with a different model (e.g. the old router is a 1U appliance with 4 ports; the new router is a 2U appliance with 8 ports). The operator’s goal: bring the new router up with the same logical configuration as the old router, but with interface names adapted to the new hardware.

flowchart LR
  OLD[Old router] -->|config from Git| NEW[New router\ndifferent model]
  NEW -->|identify interfaces| MAP[Map old names to new]
  MAP -->|edit config| ADAPT[Adapt interface names\nand IP addresses]
  ADAPT --> COMMIT[Commit and save]
  COMMIT --> TEST[Test in lab\nverify in production]

The diagram shows the migration procedure: pull the configuration from Git; identify the new router’s interface names; map the old names to the new; edit the configuration; commit and save; test in lab; verify in production.

Interface name mapping

Different hardware platforms use different interface naming conventions:

• Traditional NIC names — eth0, eth1, eth2. Used by older VyOS installations and some hardware platforms.
• Predictable NIC names — enp0s3, ens4. Used by newer Linux kernels and some VyOS installations.
• Bus-position names — eno1, eno2. Used by some server hardware.

The operator must identify the new router’s interface names and map them to the old router’s:

# Show the new router's interfaces
show interfaces

# Example output:
# Interface        IP Address        Status    Description
# lo               127.0.0.1/8       up
# eth0             -                 up
# eth1             -                 up
# eth2             -                 down
# eth3             -                 down

The new router has interfaces eth0, eth1, eth2, eth3. The old router’s configuration references eth0 and eth1. The mapping is direct.

A more complex mapping: the old router has eth0, eth1, eth2, eth3; the new router has eno1, eno2, eno3, eno4. The operator must edit the configuration to replace eth0 with eno1, eth1 with eno2, etc.

IP address changes

A different-appliance restore may require IP address changes if the new router is in a different IP range than the old router. For example:

• The old router had 192.0.2.1/24 on eth0. The new router is connected to the same network and uses the same IP.
• The old router had 192.0.2.1/24 on eth0. The new router is connected to a different network and uses 203.0.113.1/24.

In the first case, no IP changes are needed. In the second case, the operator must edit the configuration to use the new IP.

# Edit the interface to use the new IP
configure
set interfaces ethernet eth0 address 203.0.113.1/24
delete interfaces ethernet eth0 address 192.0.2.1/24
commit
save

The IP change cascades: the BGP neighbours reference the old IP; the OSPF neighbours reference the old IP; the firewall rules reference the old IP. The operator must update all of these to use the new IP.

The procedure

The different-appliance restore procedure:

1. Identify the new router’s interfaces — show interfaces on the new router.
2. Map old names to new — identify the mapping between the old router’s interface names and the new router’s.
3. Copy the configuration to the new router — scp from the Git repository or the off-box file server.
4. Edit the configuration — replace the old interface names with the new names; update IP addresses if required.
5. Load, verify, commit, save — the standard four-step procedure.
6. Test in lab — if possible, test the configuration in a lab environment before deploying to production.
7. Verify in production — after deployment, verify that all routing protocol sessions are established and that traffic flows correctly.

Failure modes

Interface name mismatch

The operator loads the configuration without checking the new router’s interface names. The commit fails with “interface eth0 does not exist”.

Diagnostic: the commit log shows the interface error.

Fix: identify the new router’s interface names; edit the configuration; reload; verify; commit.

IP address conflict

The operator keeps the old router’s IP address on the new router. The old router is still operational (the operator forgot to power it off); both routers have the same IP; ARP flapping and routing instability.

Diagnostic: the network sees duplicate ARP entries; the routing protocols flap.

Fix: power off the old router; clear the ARP cache on the neighbour; verify the new router’s IP is the only one in use.

Routing protocol session down

The new router’s IP is different from the old router’s; the peer’s configuration references the old IP; the session does not establish.

Diagnostic: show ip bgp summary shows the session as Idle (Active).

Fix: coordinate with the peer operator to update the peer’s configuration to reference the new IP. The session re-establishes.

Hardware capability mismatch

The new router has fewer interfaces than the old router. The configuration references interfaces that do not exist on the new router.

Diagnostic: show configuration shows the missing interfaces; the commit fails.

Fix: edit the configuration to remove the missing interfaces; reload; verify; commit.

Rollback

A different-appliance restore is reversible through the standard VyOS mechanisms:

• rollback N and commit to revert to the previous configuration revision.
• The old router’s configuration is in the Git repository; the operator can recover if the new router’s configuration is unrecoverable.

The VyOS commit validator catches invalid configurations; the restore is safe to run after the operator has verified the configuration.

Production discipline

Cross-course references

• LV-VyOS-Backup (vyos-lv-03-restore-same-appliance, the previous lesson) covers the same-appliance restore that the different-appliance restore extends.
• VII-VyOS-Interfaces (vyos-vii-01-ethernet-addressing) covers the interface addressing that the different-appliance restore operates on.
• IV-VyOS-Install (vyos-iv-01-iso-install) covers the installation that may precede a different- appliance restore (e.g. fresh install on the replacement router).

Quiz