Wednesday, April 8, 2026

UniFi Console Migration Guide

UniFi Console Migration Guide:

Dream Machine Upgrade or Migration: Including Cloud Account Claiming, Cellular WAN Failover, SSH Credential Capture & Orphaned Device Recovery

This guide covers migrating all adopted UniFi devices (APs, switches, cameras) from a Dream Machine (UDM) to a Dream Machine Pro (UDM-Pro) with minimal disruption. It assumes you are replacing the UDM entirely and the UDM-Pro will take the same network role.

This guide has been updated with real-world field experience from an actual UDM → UDM-Pro migration, including the cloud account claiming procedure, Mesh AP tweaks required post-restore, and cellular WAN failover configuration using a designated LAN port as WAN3.


PHASE 1: PRE-MIGRATION PREP

Complete all steps while the old UDM is still live and Do NOT make any changes to the existing network yet.


Step 1: Record the Current UDM's LAN IP Address

This is the single most critical piece of information for a seamless migration.

  1. Log into the UniFi Network app on the current UDM.
  2. Navigate to Settings → System → Network.
  3. Note the LAN IP address (commonly 192.168.1.1 or 10.0.0.1).
  4. Write it down; the NEW UDM-Pro must be assigned this exact IP.

CRITICAL: If the UDM-Pro ends up on a different IP, adopted devices will lose contact with the controller and require manual re-pointing. Same IP = devices never know the hardware changed.

Step 2: Capture SSH Credentials (Device Authentication)

UniFi devices store SSH credentials set at adoption time. These must match what the new console presents, or adoptions will fail.

Step 2a: Locate Credentials in the UniFi Console

  1. In the UniFi Network app, go to Settings and search for "SSH"
  2. Select "Device SSH Authentication"
  3. Scroll to the Device Authentication section of any Unify device details panel.
  4. Record the SSH Username and SSH Password exactly as shown.
  5. If an SSH Key is configured, copy the full public key string as well.

NOTE: Write these credentials on paper or in a secure password manager before proceeding. Do not rely on memory or a screenshot alone. These passwords are case-sensitive.

Step 2b: Verify SSH Access to at Least One Adopted Device

  1. From your laptop or a machine on the same LAN, open a terminal.
  2. Find the IP of any adopted AP or switch (UniFi → Devices → click a device → Properties).
  3. Run: ssh [SSHUSERNAME]@[DEVICE-IP]
  4. Enter the SSH password from Step 2a. 
  5. A shell prompt = success!! Type exit to disconnect.
  6. If login fails, double check the SSH credentials again for any errors or mistakes.
  7. Rinse and repeat until you can successfully SSH into an existing Unifi device on the current network setup.

Step 3: Take a Full System Backup

  1. In UniFi OS (not just UniFi Network), navigate to UniFi OS → System → Backup.
  2. Click "Backup Now" and then Click on "Download Backup" and save the file to your laptop.
  3. Note the UniFi OS version and Network application version currently running.

IMPORTANT: This must be a UniFi OS-level backup, not just a Network application backup. The full OS backup includes device auth keys, SSH credentials, site config, and adoption records. Cloud backup is also acceptable; see Phase 2 for the cloud restore procedure.

Step 4: Inventory All Adopted Devices

Document every device so you can verify they all reconnect post-migration.

  • Access Points: Hostname, IP address, MAC address, location
  • Switches: Hostname, IP address, MAC address, VLAN config notes
  • Cameras: Hostname, IP address, any NVR config
  • Other UniFi devices: Hostname, IP, role

In UniFi → Devices, you can export the current Unifi device list or you can simply screenshot each device's details panel.


PHASE 2: SET UP THE NEW DEVICE

CRITICAL: The new/replacement Ubiquiti device must be claimed to your Ubiquiti account BEFORE attempting any backup restore.


Step 5: Claim the UDM-Pro to Your Ubiquiti Account

REAL-WORLD LESSON: An Isolated WAN Connection is Required for Cloud Claiming!
The UDM-Pro must have a direct, dedicated internet connection to reach Ubiquiti's cloud servers during the initial claiming process. Use a modem or ONT port that is not connected to your existing network.

  1. Connect the UDM-Pro's WAN port directly to a dedicated modem port or isolated ONT; NOT behind the existing LAN.
  2. Connect your laptop directly to a LAN port on the UDM-Pro via Ethernet.
  3. Power on the UDM-Pro and complete the initial setup wizard.
  4. Log into unifi.ui.com or use the UniFi mobile app.
  5. The UDM-Pro will appear as an unclaimed device; adopt and assign it to your account.
  6. Once claimed, do NOT restore the backup yet. Proceed to Step 6 first.

NOTE: If the UDM-Pro is registered to another account, you must first release it. 

  • Log into unifi.ui.com under the original owner's account → Devices → Release the device. 
  • If the original owner is unavailable, a factory reset will clear the association.
  • To reset a Unifi device, hold the reset button for approximately 10 seconds until the LEDs cycle.

Step 6: Match the UniFi Software Version

Restoring a backup to an older firmware version can cause corruption or a failed restoration.

  1. On the UDM-Pro, go to UniFi OS → System → Updates.
  2. Update UniFi OS and the Network application to match or exceed the version on the old UDM.
  3. Allow all updates to complete fully before proceeding.


PHASE 3: THE MIGRATION CUTOVER

This is the active downtime window. Work quickly and have your notes ready.

Step 7: Take the Old UDM Offline

  1. Inform users of the maintenance window.
  2. Power off the old UDM. Do NOT factory reset it; keep it as a fallback.
  3. Disconnect all LAN and WAN cables from the old UDM.

SAFETY NET: Keep the old UDM powered off but intact until all devices have confirmed to the new console. If something goes catastrophically wrong, you can reconnect it.

Step 8: Restore the Backup on the UDM-Pro

FIELD-VERIFIED: Cloud Backup Restore
If you ran a cloud backup on the old UDM immediately before migration, you can restore it directly from unifi.ui.com without needing a local .unf file. In UniFi OS on the UDM-Pro → System → Backup → select the cloud backup from the list and restore. Allow approximately 10 minutes for the restoration to complete and the system to reboot.

  1. In UniFi OS on the UDM-Pro, go to System → Backup.
  2. Choose either Cloud Restore (select backup from list) or Local Restore (upload .unf file from Step 3).
  3. Initiate the restore and wait for completion.
  4. The system will reboot automatically.
  5. Allow approximately 10 minutes for full restoration.
    Do not interrupt power during this process!
  6. After reboot, verify in Settings → System → Advanced that the SSH credentials match what you recorded in Step 2.

Step 9: Connect the UDM-Pro to the Network

  1. Move the UDM-Pro to its permanent location.
  2. Plug in the primary WAN connection (ISP modem/ONT) to WAN1.
  3. Connect all the same LAN switches and infrastructure that were connected to the old UDM.
  4. The UDM-Pro is now live on the same IP the old UDM used.

Step 10: Monitor Device Re-adoption

  1. In UniFi → Devices, watch as adopted devices come back online.
  2. Devices will inform to the same IP they always used and should auto-rejoin.
  3. Allow 10–15 minutes for all devices to check in. 
  4. Power cycle any that haven't appeared after 10 minutes.
EXPECTED OUTCOME: All previously adopted devices should reconnect automatically without factory resets or manual re-adoption because they are contacting the same IP with the same SSH credentials.

Step 10a: Mesh AP Post-Restore Tweaks (If Applicable)

REAL-WORLD LESSON: Mesh APs May Need Minor Adjustments.
After restoring a backup to the UDM-Pro, some Mesh APs may fail to fully reconnect due to Mesh Connect and Minimum RSSI settings. Mesh Parent can remain enabled. The fix is quick and non-disruptive.

If any Mesh AP Parent shows as disconnected or unstable after the restore:

  1. In UniFi → Devices, click the affected AP.
  2. Go to the AP's Configuration tab.
  3. Under Wireless Uplinks, disable Mesh Connect.
  4. Under RF settings, disable Minimum RSSI (if enabled).
  5. Mesh Parent can remain enabled; this is expected and normal.
  6. The Child Mesh AP's should re-associate and show Connected within 1–2 minutes.
  7. ONLY SET ETHERNET CONNECTED AP's TO MESH PARENT ONLY!! 


PHASE 4: DUAL-WAN FAILOVER CONFIGURATION

The UDM-Pro has two WAN ports, but WAN2 is SFP+ only. LTE/cellular and other LAN based WAN failovers, require a dedicated LAN port to be configured as the needed failover 'WAN' port.

REAL-WORLD LESSON: WAN2 can be SFP+ Only on enterprise level networking equipment!
The UDM-Pro's second WAN port (Port 10) is SFP+ only, so there is no RJ45 WAN2. If your cellular or secondary ISP failover device has an Ethernet (RJ45) connection, you cannot plug it into WAN2 directly. The solution is to designate a standard LAN port (e.g., Port 8) as a WAN interface within UniFi.

Step 11: Configure a LAN Port as WAN3 for WAN Failover

Step 11a: Designate a Port as WAN3 in UniFi

  1. Go to UniFi Network → Settings → Internet.
  2. Click Add New Internet Connection.
  3. Select the physical LAN port you are using (e.g., Port 8) as the WAN source.
  4. Name it 'WAN3' or 'WAN Failover' for clarity.
  5. Set the connection type based on how the failover gateway presents its connection (typically DHCP but sometimes can require a static IP to be setup for connectivity).

Step 11b: Assign a Static IP for the Failover WAN Gateway's LAN Connection

FIELD NOTE: The cellular gateway typically has two ports; a WAN port (facing the cell network) and a LAN port (facing your UDM-Pro). The LAN port of the gateway connects to the UDM-Pro port you designated as WAN3. Assign a static IP on this connection to ensure reliable failover detection.

  1. On the failover gateway's admin interface, navigate to its LAN settings.
  2. Assign a static IP to the LAN port of the failover gateway.
  3. Connect the failover gateway's LAN port to the designated WAN3 port on the UDM-Pro.
  4. Connect the failover gateway's WAN (cell network) connection as required by the device.

Step 12: Configure Failover Priority

  1. Go to Settings → Internet → WAN Failover in UniFi Network.
  2. Set WAN1 (primary ISP) as the highest priority.
  3. Set WAN2 (SFP, if connected) as secondary.
  4. Set WAN3 / Secondary ISP/Connection as tertiary failover.
  5. Configure failover ping targets: recommend 8.8.8.8, 1.1.1.1, and 9.9.9.9 for redundancy.
  6. Tune failover ping interval and retry thresholds as needed; Defaults work but trigger slowly.

TIP: Test failover by manually disconnecting WAN1 and confirming traffic routes through the cellular connection. Verify failback when WAN1 is restored.


PHASE 5: TROUBLESHOOTING ORPHANED DEVICES

If any device shows as Pending Adoption, Disconnected, or simply doesn't appear after 15 minutes, work through the following steps in order.

Troubleshooting Step A: Verify the IP Assignment

  • Confirm the UDM-Pro is actually using the same LAN IP as the old UDM.
  • Run: ping [OLD-UDM-IP] (should respond from the UDM-Pro)
  • If the IP is wrong, correct it in Settings → Network → LAN, then reboot all affected devices.

Troubleshooting Step B: Manually Re-Point the Inform URL

If a device appears as 'Pending Adoption' or is stuck being adopted by the new controller, SSH into that 'Pending' device directly and manually send it to the new controller.

  • Find the device IP from the DHCP lease table or your inventory list from Step 4.
  • SSH into the device:
    ssh admin@[DEVICE-IP]
  • Run:
    set-inform http://[UDM-PRO-IP]:8080/inform
  • Back in the UniFi console, the device should now appear; click Adopt.

TIP: You may need to run set-inform twice on some devices; once to trigger the adoption request, then again after clicking Adopt in the console.

Troubleshooting Step C: SSH Credential Mismatch

  • If the SSH login itself is failing, there is a credential mismatch.

Option 1 ~ Update the Console to Match the Devices:

  • In UniFi → Settings → System → Advanced → Device Authentication, update the SSH credentials to match the old UDM. 
  • Push updated credentials via Update → Force Provision.

Option 2 ~ Try Default Credentials on the Device:

  • Run: ssh [SSHUSERNAME]@[DEVICE-IP]
  • Enter the SSH password recorded earlier.
  • Once in, run the set-inform command from Step B above.

Troubleshooting Step D: Device Won't Accept SSH

  • Physically check the device: is it powered on and showing a connected LED?
  • Check the DHCP lease table on the UDM-Pro to confirm it has a valid IP.
  • Run a layer 2 scan if the device doesn't appear in DHCP: nmap -sn 192.168.1.0/24
  • If reachable by ping but SSH is refused: try a power cycle.
  • If completely unreachable after a power cycle: a factory reset may be unavoidable for that unit only.

Troubleshooting Step E: Factory Reset (Last Resort, Single Device)

Only if all other steps have failed for a specific device. This does not affect other devices.

  • Locate the reset button on the device (usually a small pinhole).
  • With the device powered on, hold the reset button for 10 seconds until the LED flashes.
  • The device will reboot to factory defaults and appear as Pending Adoption in UniFi.
  • Click Adopt
  • The UDM-Pro will push all config back to the device.

NOTE: A factory reset clears device-level config but UniFi will re-apply the site config (SSID, VLANs, port profiles, etc.) automatically when re-adopted. You should not lose any network configuration.


PHASE 6: POST-MIGRATION VERIFICATION CHECKLIST

  • All devices appear Connected in UniFi → Devices
  • Client devices have internet access
  • VLANs are routing correctly
  • SSH credentials confirmed in Settings → System → Advanced
  • Mesh APs connected (Mesh Connect / Min RSSI adjusted if needed)
  • Dual-WAN / WAN3 failover configured and tested
  • Failover tested: WAN1 disconnected, traffic routed via cellular
  • Failback tested: WAN1 restored, primary connection re-established
  • Firmware on all APs and switches up to date
  • Old UDM powered off and stored as spare
  • Cloud backup run on new UDM-Pro to establish new restore point


QUICK REFERENCE: SSH COMMANDS

ssh [SSHUSERNAME]@[DEVICE-IP]
Connect via SSH using recorded credentials 

ssh ubnt@[DEVICE-IP] (pw: ubnt)
Connect via SSH using factory default credentials 

set-inform http://[UDM-PRO-IP]:8080/inform
Re-point device to new controller 

info
Display device status, firmware, inform URL 

exit
Disconnect SSH session


LESSONS LEARNED "In The Field"

  1. Cloud Claiming Requires Isolated WAN The UDM-Pro must have a direct, dedicated internet path (not behind existing LAN) to authenticate with Ubiquiti's cloud during initial setup.

  2. Cloud Backup Restore Works Well Running a cloud backup immediately before migration and restoring via unifi.ui.com is reliable. Restoration completes in approximately 10 minutes.

  3. Mesh APs May Need Tweaks Disable Mesh Connect and Minimum RSSI on affected APs post-restore. Mesh Parent can remain on. Devices reconnect within 1–2 minutes.

  4. WAN2 is SFP+ Only RJ45 secondary WAN devices (cellular gateways, LTE routers) cannot connect to WAN2. Use a designated LAN port configured as WAN3 instead.

  5. Static IP for Cellular Gateway Assign a static IP on the failover gateway's LAN port to ensure reliable failover detection by the UDM-Pro.

  6. Same LAN IP = Seamless Re-adoption Assigning the UDM-Pro the exact same LAN IP as the old UDM means adopted devices reconnect automatically with no manual intervention.



Created & Maintained by Pacific Northwest Computers



📞 Pacific Northwest Computers offers Remote & Onsite Support Across: 

SW Washington including Vancouver WA, Battle Ground WA, Camas WA, Washougal WA, Longview WA, Kelso WA, and Portland OR 


Posted by at
Labels: , , , , , , , , , , , , , , , , , , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)