Replace a UniFi Security Gateway with a Cloud Gateway
The UniFi Security Gateway has reached the end of the line. Network 10.6 is the last version to support it, and Network 11 removes it altogether. [1] This guide moves a USG and its controller, whether that's a Cloud Key or software on a computer, onto a Cloud Gateway, which does both jobs in one box. You'll back up the site, restore it on the new gateway, check it, swap the cables, and rebuild what didn't come across.
Outcome and equipment
By the end, your site will be running on a Cloud Gateway with the same networks, WiFi and rules, your firewall will be on zone-based policies, and the USG will be retired.
- A Cloud Gateway. Choose the right UniFi Cloud Gateway for your nbn plan will help you pick one.
- Admin access to your current controller.
- Your ISP's connection details, including any PPPoE username and password.
- A computer with a network port, and a spare cable.
- A quiet time. Allow a couple of hours for the restore, the swap and your checks.
Keep the USG and the old controller until the new gateway has run well for a week or two. They're your way back.
Choose the right replacement
A Cloud Gateway runs its own controller, while most people with a hosted or self-hosted controller pair it with a UXG gateway. [2] That decides which path suits you.
| Your setup | Replace it with | Why |
|---|---|---|
| A USG with a Cloud Key, or software on a computer, at one site | A Cloud Gateway | One box replaces both |
| A hosted or central controller that you want to keep | A UXG gateway | It works with your existing controller [2] |
The rest of this guide covers the Cloud Gateway path. If you're on the standalone Network software, also note that Network 11 replaces it with UniFi OS Server. [1] The Network 11 upgrade guide covers that change and the other USG notes.
Know what comes across
A restore brings across your Network settings and device configurations. [3] Ubiquiti doesn't publish a list of what a restore onto new hardware leaves out, so use this table as a checklist and test each item.
| Item | What to expect |
|---|---|
| Networks, VLANs, DHCP reservations and WiFi | Restored |
| Port forwards and static routes | Restored, but check each one |
| Firewall rules | Compare every custom rule with your screenshots, especially if the new gateway is already on zone-based firewall |
config.gateway.json customisations |
Plan to rebuild them in the interface (see below) |
| VPN client setups | Test each one, and set it up again if needed |
| RADIUS and 802.1X secrets | Test a sign-in, and enter them again if it fails |
| Local-only admins and SSH keys | Check them, and create any that are missing |
Prepare the old system
- Update the controller to the newest 10.6 release, not Network 11. Network 11 removes USG support. [1] Turn off automatic Network updates until the swap is finished, and note the version number. Ubiquiti's migration steps start by bringing the new Network application up to date, so make sure the new gateway runs that version or newer before you restore. [3]
- Record your settings. Take screenshots of your WAN settings, networks, port forwards, VPNs, static routes and firewall rules. You'll compare against these later.
-
Save your custom files. If you use
config.gateway.json, copy it somewhere safe. - Copy the device SSH details. Find them at Devices › Device Updates & Settings › Device SSH Settings. They can help you recover a device that doesn't reconnect. [3]
-
Download a backup. Use Settings › Control Plane › Backups. On a Cloud Key, this gives a System Config Backup, which moves device management to the new gateway. On a self-hosted Network server, it gives a
.unffile. [3] The menu may read differently on an older controller. If your controller runs several sites, Ubiquiti has a Site Export option for moving just one. [3]
Prepare the new gateway
Do this alongside your working network, so the site stays online and you can take your time.
- Connect its WAN to your current network. Plug the new gateway's WAN port into a spare LAN port on your switch or USG, so it can reach the internet. Ubiquiti's setup guide asks you to check the console's internet connection, and recommends updating to the latest version. [4] If your nbn service uses PPPoE, this also lets you update the gateway without moving the service.
- Finish the setup. Use the UniFi app, or connect a computer to a LAN port. [4] Sign in with the UI account that should own this site.
- Update it. Go to Settings › Control Plane › Updates and update UniFi OS, then Network. [5] This step matters: UniFi OS 5.1.35 for Dream Machines, for example, bundles Network 10.5.67, so a new gateway can be behind a controller on 10.6 until you update the Network app. [6]
- Restore the backup. Go to Settings › Control Plane › Backups, choose Restore and upload the backup file. [3]
- Expect it to lose internet. After the restore, the new gateway's LAN can use the same address range as the network its WAN is plugged into, which can stop its WAN from working. Connect your computer directly to one of its LAN ports for the next step.
- Check the restored settings. Compare networks, WiFi, DHCP reservations, port forwards and firewall rules with your screenshots. Look closely at network isolation, and test that isolated networks still can't reach each other.
Swap the hardware
- Unplug the USG. Don't leave two gateways live on one network.
- Move the cables. Connect the nbn box or modem to the new gateway's WAN port, and your main switch to one of its LAN ports. Connect any cable you added for the updates back to where it was, or remove it.
- Check the WAN. Open Settings › Internet and confirm the connection type and any VLAN tag, static IP or PPPoE details, because the restored settings may not suit the new gateway. [7]
- Restart the nbn box or modem if the WAN doesn't come up. Cable modems in particular may need a restart to work with a new device.
- Leave the old controller running. Wait for your switches and access points to appear online. [3]
- Bring back any stragglers. If a device stays offline or shows Managed by Another Console, turn on Override Inform Host on the old controller and enter the new gateway's IP address. If that fails, factory reset the device and adopt it. [3] Fix an offline UniFi AP or failed adoption has more detail.
- Shut down the old controller. Do this only after every device shows Online on the new gateway. [3]
- Remove the USG. If it shows up in the device list, open its settings and choose Forget in the Manage section. Ubiquiti says this unmanages a device and restores it to factory defaults. [8]
Move to the zone-based firewall
If your site still uses the older firewall rules, convert them now, once the site has settled. On Network 11, the conversion happens automatically. [1] If the gateway is already on zone-based firewall, there's no Upgrade step to run, so compare its policies with your screenshots and rebuild anything that's missing.
- Download a backup first. Restoring a backup takes you back to a previous, stable configuration. [3]
- Run the upgrade. On Network 10, go to Security › Traffic & Firewall Rules and choose Upgrade. It takes seconds, and traffic keeps flowing. [9] Rules for the old LAN_LOCAL chain become rules in the Internal or VPN zone to the Gateway zone. [9]
- Clean up the result. Look for policies that are redundant or have no effect. Ubiquiti converts rules conservatively so they work the same as before, and that can leave extras. [9]
- Test what matters. Check VPNs, mDNS, network isolation and port forwards. Once testing shows which policies work, you can remove the redundant ones. [9]
Build a UniFi zone based firewall policy explains how to tidy up the policies from there.
Rebuild what didn't come across
-
Custom gateway settings: Ubiquiti doesn't document a
config.gateway.jsonequivalent for Cloud Gateways, so rebuild each setting in the interface where you can. Ubiquiti's BGP article lists the Dream Machine Pro, SE and Pro Max, the Dream Wall and the Enterprise Firewall, and has you upload the configuration as a text file in FRR format. [10] Check your spec sheet first: the Cloud Gateway Fiber lists OSPF only. [11] - VPNs: this is a good time to leave L2TP behind. Ubiquiti recommends Teleport or WireGuard instead. [12] See Set up UniFi Teleport remote access and WireGuard vs Teleport, then set up each client again.
- RADIUS and 802.1X: test a sign-in, and enter the shared secrets again if it fails.
- Admins: recreate any local admin accounts and SSH keys. Secure a UniFi Cloud Gateway from day one shows how to do that safely.
- Addresses: if your gateway's or a server's address has changed, firewall rules that use a fixed IP will need updating.
- Backups: your old automatic backups won't carry on by themselves. Tick System Backups at Settings › Control Plane › Backups. [3]
Verification
- Every switch and access point shows as Online and adopted.
- A wired speed test is close to your plan speed. On a faster gateway, you may see an improvement.
- A device on each VLAN gets the right address and can reach what it should, and nothing more.
- DHCP reservations give servers and printers their usual addresses.
- Port forwards work from a phone on mobile data.
- VPN clients connect and reach what they need.
- Guest and IoT networks still can't reach your main network.
- After a restart, everything returns by itself.
- A new backup appears, and you've downloaded a copy.
Troubleshooting and recovery
| Problem | Likely cause | What to do |
|---|---|---|
| The backup won't restore | The new gateway's Network app wasn't brought up to date first [3] | Update Network on the gateway, then try again. |
| The gateway has no internet after the swap | Restored WAN settings that don't fit, such as a VLAN tag, static IP or PPPoE details [7] | Check Settings › Internet, then restart the nbn box or modem. |
| Devices stay offline | They're still connecting to the old controller [3] | Set the inform host override, or reset and adopt them. |
| A device says Managed by Another Console | The old controller still holds it [3] | Turn on Override Inform Host, or factory reset it and adopt it. |
| Devices that were isolated can now talk | An isolation setting or policy is missing | Recreate it, then test both directions. |
| Something stops working after the firewall upgrade | A converted policy has no effect, or sits in the wrong order [9] [13] | Check the policy order. On Network 10, you can restore your pre-upgrade backup. [3] On Network 11, every site is migrated automatically, so fix the policies instead. [1] |
| A custom route or setting is missing | It lived in config.gateway.json
|
Rebuild it in the interface. |
| A VPN client won't connect | Its server settings or address changed in the move | Set it up again. |
If the new setup isn't working and you need to get back online, unplug the new gateway, reconnect the USG and restart the old controller if you've shut it down. Any device that has already moved may need a factory reset and adoption on the old controller. Back up and migrate a UniFi gateway has more on keeping a way back.
Sources:
- [1] Ubiquiti Community, UniFi Network Application 11.0.83 release notes.
- [2] Ubiquiti Help Center, Choosing the Right UniFi Control Plane.
- [3] Ubiquiti Help Center, Backups and Migration in UniFi.
- [4] Ubiquiti Help Center, How to Set Up UniFi.
- [5] Ubiquiti Help Center, UniFi Updates.
- [6] Ubiquiti Community, UniFi OS - Dream Machines 5.1.35.
- [7] Ubiquiti Help Center, WAN Failover, Load Balancing and Port Remapping on UniFi Gateways.
- [8] Ubiquiti Help Center, How to Reset UniFi Devices to Factory Defaults.
- [9] Ubiquiti Help Center, Migrating to Zone-Based Firewalls in UniFi.
- [10] Ubiquiti Help Center, UniFi - Border Gateway Protocol (BGP).
- [11] Ubiquiti Tech Specs, Cloud Gateway Fiber.
- [12] Ubiquiti Help Center, UniFi Gateway L2TP VPN Server.
- [13] Ubiquiti Help Center, Zone-Based Firewalls in UniFi.