Digi International Inc. is moving to a new operating system, called Digi Accelerated Linux (DAL), for the WR54, WR64 and LR54 platforms.
Please read the Digi WR54 / WR64 / LR54 Migration Release Notes for information on the considerations, best practices and options on how to migrate devices before attempting to migrate any devices.
This knowledge base article is to help diagnose any failures experienced during the migration and recover the device back to xOS if necessary.
Migration process
The migration is done in 3 phases
- Configuration
- Firmware
- Bootloader
Configuration
Digi strongly recommends that you use the DAL backup file migration method if possible, and that you test the DAL configuration prior to the migration. This guarantees that the device will be migrated with a specific, verified configuration.
During the configuration phase, the device will attempt to migrate the device’s xOS configuration to the equivalent DAL configuration where possible. The migration can be performed in one of two ways:
- Using a DAL configuration backup file.
- Automated configuration migration.
Either method can be used when the migration is performed from the following tools:
- Digi Remote Manager
- Local Web UI
- CLI
Using a DAL configuration backup file
Digi strongly recommends that you use the DAL backup file migration method if possible, and that you test the DAL configuration prior to the migration. This guarantees that the device will be migrated with a specific, verified configuration.
When performing a migration using a DAL configuration backup file, the device will use the DAL configuration stored in the DAL backup file and will not use the existing xOS configuration.
If you do not have a device to take a backup file from, Digi provides a copy of a backup-archive.bin file that can be used. Note that this file will factory default any LR54, TX54, and TX64 device if used for the converstion to DAL. To keep needed settings, your own backup-archive.bin file will need to be used instead. The Digi provided file is found here.
It is unlikely that this will fail unless there is a problem with the DAL backup file, or if the file is not named exactly backup-archive.bin (with lowercase lettering) when loaded onto the xOS device.
Automated configuration migration
When using the automated configuration migration, the device will attempt to migrate the existing Digi xOS configuration file to the equivalent DAL configuration.
It is possible for the migration to fail due to incompatibility between the xOS configuration and the DAL configuration. See the Diagnosing migration failures section for more information.
Firmware
During the firmware phase, the two firmware banks will be updated with the DAL firmware.
If the update of the first bank fails, the device will reboot back to the Digi xOS firmware using its existing configuration.
If the update of the second bank fails, the device will not be able to boot up. The WR54 and LR54 platforms can be recovered using the recovery process. For options on how to recover a WR64, please contact Technical Support.
LR54 Only: If the LR54 is failing to migrate to the DAL firmware, ensure that the device is on xOS firmware version 4.8.6.6 or later, and try the migration process again. If your LR54 is on firmware older than 4.3.2.24, you must first upgrade to 4.3.2.24 before being able to upgrade to 4.8.6.6 or later, or to be able to migrate to the DAL OS. See the LR54 Support page for the necessary firmware files.
Bootloader
The final phase of the migration is to update the device’s bootloader.
This phase should take a fraction of a second to complete and should only fail if the power to the device is lost at this point. If the update does fail, it can leave the device in an indeterminable state and it may not boot up. If this happens, please contact Technical Support
Diagnosing Migration Failures
migration.log File
Digi strongly recommends that you use the DAL backup file migration method if possible, and that you test the DAL configuration prior to the migration. This guarantees that the device will be migrated with a specific, verified configuration to avoid potential migration issues.
If the migration fails, and aborts the migration, the device will attempt to reboot back to the Digi xOS firmware using its existing configuration.
The reasons for the failure can be found in the migration.log file which can be found in the user directory on the device.
Using the Web UI, the migration.log file can downloaded via the System > File System menu. Select the migration.log file and click on the Download button.
Using the CLI, the migration.log file can read using the more command
digi.router> dir
File Size Last Modified
------------------------------------------------------
ssh_host_rsa_key.pub 382 Thu Sep 27 17:22:28
migration.log 3918 Fri Mar 20 11:56:12
ipsec.debug 55708 Tue Mar 10 15:42:55
config.da0 2254 Thu Feb 13 15:02:01
config.fac 1173 Thu Mar 14 10:46:25
Remaining User Space: 102,703,104 bytes
digi.router> more migration.log
not migrated: wan 1 activate-after 10
port-forward:1:_migrate_protocol: 'badproto' not supported - disabling rule
port-forward:1:_migrate_protocol: 'badproto' not supported - disabling rule
Fatal migration error: XAuth 'server' role not supported
digi.router>
Information in the migration.log File
The migration log will contain information about any configuration item that could not be migrated to the DAL configuration.
- If the unmigrated configuration item is critical to the operation of the device (for example, if it prevent an interface or VPN tunnel from coming up), then the migration will be aborted with an appropriate message in the migration.log file.
- If the configuration in question is not deemed critical to the operation of the device, then the non-migration is logged and the migration will continue.
Fatal Migration Error
You should review the migration.log file for messages beginning with Fatal migration error. You should then try to change the device’s configuration to remove the configuration item that is causing the migration to fail, then retry to the migration.
The configuration items that can cause a fatal migration error are:
- A firewall rule that is using an interface option.
- An IPsec tunnel is using IKE or ESP ciphers that are not supported in DAL. These are the AES GCM ciphers.
- An IPsec tunnel is configured as a Xauth server.
- An admin user either does not exist or is not enabled.
Incomplete Configuration
Another cause of migration failures can be that the migration fails because it is unable to handle specific conditions within a configuration. This is particularly the case if there is incomplete configuration for various components, such as a LAN interface, a Wi-Fi Access Point, or an IPsec tunnel. Incomplete configurations for these components can occur if you have previously used the Web UI to delete or remove a configuration item, which can result in fragments of the configuration item remaining even after it has been deleted.
If this happens, you will see something like the following in the migration.log file:
args.fail_if_no_admin_user)
File "migrate-xos-config.py", line 144, in _migrate
_merge_xos_config(xos_config_filename, dal_config)
File "migrate-xos-config.py", line 128, in _merge_xos_config
group_modules[module].update_dal_config(dal_config)
File "/firmware/migrate-to-dal/groups/wifi-ap.py", line 172, in update_dal_config
_migrate_wifi_ap(xos, instance, dal_config)
File "/firmware/migrate-to-dal/groups/wifi-ap.py", line 161, in _migrate_wifi_ap
_assign_enable(xos, instance, dal_config, wifi_ap)
File "/firmware/migrate-to-dal/groups/wifi-ap.py", line 142, in _assign_enable
or device_in_enabled_lan(long_ap_name, dal_config))
File "/firmware/migrate-to-dal/groups/wifi-ap.py", line 121, in device_in_enabled_lan
if device_name == lan["device"] and lan["enable"]:
KeyError: 'enable'
If this occurs, attempt to remove the non-conforming configuration items by using the appropriate CLI commands. See the Digi WR Routers User Guide for command instructions.
Another cause of migration failures can be that the generated DAL configuration is incomplete. This could be for something like a missing IP address on a LAN Interface or a WAN interface that is not using DHCP, or if there is no interface assigned to a LAN or WAN.
If this happens, you will see something like the following in the migration.log file
config[205]: network.interface.lan2.device: required value
config[205]: network.interface.lan2.ipv4.address: required value
config[205]: validation failed
If this occurs, try adding the required configuration or removing old configuration using the appropriate CLI commands if it is no longer needed.
EOF (End of File) Message
It is possible that a EOF (End of File) message may show up as an error in the migration.log file. An example is below:
ipsec 1 description "To 166.149.45.178": not migrated
ipsec 1: Migrate interfaces: Multiple interfaces specified, so using 'default route' for the local endpoint
config[174]: parse error: premature EOF
(right here) ------^
config[174]: parse error: premature EOF
(right here) ------^
config[174]: network.wifi.ap.digi_ap2.encryption.key_psk2: required value
config[174]: network.wifi.ap.digi_ap2.ssid: required value
config[174]: validation failed
These messages can be safely ignored, and are not actually error messages in regards to the configuration migration.
Other Migration Issues
If you continue to face problems with the migration, please save the migration.log file and contact Technical Support.
Local WebUI Fails to Load Firmware
In rare occasions, the local WebUI may fail to load the firmware with one of the following messages:
- Firmware update failed: Failed to download firmware - <html><title>403: not authorized</title><body>403: not authorized</body></html>
- Firmware update failed: apply firmware failed
- Firmware update failed: Failed to download firmware – Unknown error
If any of these errors occur, either the CLI or Digi Remote Manager methods will need to be used to upgrade the specific device displaying the error.
Last updated:
Sep 26, 2024