Migrate OPNsense to New Hardware using the Configuration Importer during Installation

Dustin Casto
November 18, 2022
Routers
OPNsense

If you have you an existing bare metal OPNsense installation and you wish to migrate to new hardware, you have the option of exporting your current configuration and importing the configuration during the installation of OPNsense on a new system. The import process can save you a lot of time since you do not need to configure your router from scratch. However, the process may not get you 100% migrated over to your new hardware depending on the plugins you have installed as I will discuss in more detail later.

The overall process is a bit more involved than I had originally anticipated. I am glad I tried migrating to a new firewall before I had any real hardware or software issue(s) on my existing firewall because I discovered there is more to the process than simply importing the configuration. In fact, it has caused me to re-evaluate running OPNsense in a VM instead of bare metal in order to have an easier restore process and the added benefit of remapping the network interfaces.

If I decided to run OPNsense in a VM, I would definitely still run OPNsense on its own hardware separate from my main Proxmox server so that any tinkering or updates I have to do on that server will not take down my network. I would store backups on my dedicated Proxmox Backup Server for both my router and my Proxmox server. I know I could run Proxmox in high availability mode, but I like the idea of keeping my router/network infrastructure separate and not have any dependencies with other systems. Also, sometimes I just need more time to properly research and implement a solution that will serve my needs well. My goal is to manage complexity in order to minimize troubleshooting and downtime.

OPNsense is stable enough that I have performed in place upgrades for 5 years on the same hardware without any major issues so even if there is a small inconvenience of getting back up and running 100% from a configuration backup for a bare metal installation, I do not have to do it very often (assuming the hardware does not fail).

Even though I focusing this guide on migrating physical hardware, you may follow a similar process for VMs, which may be helpful if you want to migrate from a bare metal installation to a virtual machine installation.

Export Configuration from Current OPNsense System

On your current system, export the configuration by visiting the “System > Configuration > Backups” page. If you do not wish to backup the RRD data (which is the network traffic data), you can check the box. This makes your configuration file much smaller. Click “Download configuration” to save a copy of the configuration XML file.

There are a couple of gotchas that I ran into that I would like to mention. I am putting them in warning boxes below because they are important considerations. Learn from my struggles or mistakes! The first issue has to do with the root user:

Before you export your configuration file, ensure that the root user is not disabled. My root user was disabled since I use a different administrator account. Generally, it is best practice to not use the root account directly but rather a user with administrator privileges since the root account has all of the keys to the kingdom. However, I noticed that I could not proceed with the configuration import when the root user was disabled. It would not accept my password.

If you prefer, you could simply remove the <disabled>1</disabled> line out of the configuration file under the root user section of the XML.

The next gotcha has to do with encrypted configuration files:

Do not encrypt the configuration because the import process during the OPNsense installation does not currently support encrypted backups. Only configuration imports through the web interface support encryption. I actually had a brief discussion with the OPNsense team on Twitter which eventually led to filing a feature request on GitHub to allow this possibility. It was suggested that perhaps a separate file containing the password used to decrypt the configuration file could be stored on a USB disk along with the encrypted configuration file. This would allow unattended/automated installs to still function properly in addition to manual installations.

If this feature gets implemented, the issue will no longer be considered a ‘gotcha’.

Zenarmor users: You will need to make a separate backup of the Zenarmor configuration in order to restore its settings.

Determine Interface Names on Your New Hardware (if Different)

If your new hardware is using different types of interfaces or the interfaces are mapped differently, you will need update the interface names in your configuration file so the configuration will work properly on your new hardware.

You will not be able to use an encrypted backup if you need to modify the interface names.

Sometimes the interface names are provided by the manufacturer such as with Protectli systems. Such documentation is very convenient. Otherwise, you may have to boot up the OPNsense installer on the new hardware in order to know the names of interfaces.

Edit Interface Names in the Configuration File

For all the interface changes mentioned below, you should be safe to do a “find all and replace” in your favorite text editor. Be sure to skim through all the matches to make sure nothing is incorrectly replaced.

Find the WAN interface by searching for <wan>, which is located in the <interfaces> tag. It should be found toward the beginning of the XML file. In the <if> tag, replace the igb0 (or whatever your interface is called) to the new interface such as igc0.

<interfaces>
    <wan>
      <if>igc0</if>
      ...
    </wan>
</interfaces>

If you have VLANs and your configuration is older, you may need to replace the first part of the VLAN interface name because it contains the parent interface name as shown below. The newer VLAN configuration does not include the parent interface (such as vlan02) so .

<interfaces>
    <wan>
      <if>igc1_vlan10</if>
      ...
    </wan>
</interfaces>

I am not sure if it is recommended to change to the new VLAN naming convention because the old convention still seemed to work when I imported to new hardware running the latest OPNsense version. To be safe, you may just want to replace the first part of the VLAN name to be consistent with configuration that you know works properly. There are other places where the VLAN interface name is referenced such as described below.

In the <vlans> tag, you will need to update all of the parent interface names in the <if> tag. You will also need to change the VLAN interface name in the <vlanif> tag if you had to change it if you have older configuration.

<vlans version="1.0.0">
    <vlan uuid="209df8f4-a6b8-48c8-8349-70819b5c1ed9">
      <if>igc1</if>
      <tag>10</tag>
      <pcp>3</pcp>
      <descr>DMZ</descr>
      <vlanif>igc1_vlan10</vlanif>
    </vlan>
    ...
</vlans>

Do not forget to save your changes before continuing. I recommend saving a new copy of the original file in case something does not work properly.

Put Configuration File on a USB Drive

Because of the UFS filesystem used by the OPNsense USB installer and the fact that the OPNsense installer expects a FAT filesystem for configuration file imports, you cannot simply copy your configuration file to the same USB drive as the OPNsense installer. Therefore, you will need to use a second thumb formatted to FAT32 using either a MSDOS or GPT partition table.

Create a folder called conf and rename the configuration file to config.xml in order for the installer to properly import the configuration file. Plug in both of your USB drives before booting up the OPNsense installer.

Import Configuration during Installation

After the OPNsense logo is displayed in ASCII text, the very first prompt in the installer is if you wish to import a configuration file. Press any key to start the configuration import process. Enter the name of the disk with the configuration file. On my system, I had to enter da0 for the device. My OPNsense installer was on device da1. You may have to guess if you have two USB drives from the same vendor like I do since there is no easy way to know which one is the proper one.

Once you enter the proper device, you should see the configuration loading. You will know it is working properly when you reach the end and you see all of your interfaces displayed with their assigned IP address ranges.

I have noticed if you do not map the interfaces to valid interfaces the installer will default to the normal WAN/LAN interfaces. If you only see the WAN/LAN interfaces displayed you may have something wrong with your configuration (unless you only had those two interfaces configured on your old hardware).

An Alternate Boot Process

Interestingly, when I tested this process on the Protectli VP2410, I was not prompted to important any configuration files or any other installation prompts. I was simply dropped to a login prompt. I do not know if the boot process behaves differently because that system has the coreboot firmware installed. I will demonstrate this process in case you have a similar boot experience depending on the hardware/firmware you are using.

If you use installer as the user and opnsense as the password (which is the default for new installations), you will have the option to import the configuration before continuing with the installation.

After choosing the default keyboard layout, you will see a menu which has an option called “Import Config”. Select it and press “Enter”.

Choose the USB disk containing the configuration file. It may be something like da0 as I have mentioned earlier.

You will know if the configuration file import was successful when you see the “Configuration import completed” message. Otherwise, you will see an error message.

Continue with the Normal Installation Process

Once the configuration has finished importing, you will arrive at the prompt to run OPNsense in live mode or to install it to the disk. You will need to use the installer user like you normally would to install OPNsense. However, for the password, you must enter the root user password that is stored in the configuration file you imported instead of the default password of opnsense. If you had two factor authentication enabled, you do not need to use the OTP + the password. You only need to use the password. As mentioned in the beginning, the password will not work if the root user is disabled.

At this point, you simply continue the installation process as you normally would. I am assuming if you are migrating from an older system to a newer one that you do not need instructions for installation, but in case you may find them useful, you could refer to my OPNsense installation guide. One difference is that you will not need to set up the interfaces since that has been done already with the configuration file import.

Reinstall Plugins and Reconfigure Them (if Necessary)

If all goes well and everything was mapped to the new interfaces properly, you should have OPNsense nearly operational. I say ’nearly’ because you will have to reinstall all of your plugins. The plugins will show up as missing on the “System > Firmware > Plugins” page so they will be easy to identify. Many of the settings for the plugins should persist from the configuration file but you should verify that is true after installing the plugins.

One notable exception is for Zenarmor. You will need to restore the settings from a Zenarmor backup file you generated from a previous installation.

Potential Issues

One potential issue I happened to notice: if you had WireGuard installed in a previous OPNsense installation and do not have the first interface of your firewall plugged into your network before booting after importing the configuration, WireGuard will show up as assigned to the first physical interface rather than a virtual interface, which interferes with making any interface changes and may cause other issues. I have not fully confirmed the issue. However, a Reddit user also noticed a similar issue when migrating his firewall. I wanted to mention this in case you encounter a similar situation.