How to migrate an existing self-hosted UniFi Network legacy server to the new UniFi OS Server for Linux — on the same box, with no second server, no DNS changes and no site-by-site rebuild.

There are a few ways to do this. This is the fastest one we have found: everything adopts automatically, so there is no need to change set-inform or SSH into each device, and none of the pain of migrating one site at a time.

Check the server is up to spec

The minimum recommended is an x86/64 CPU (ideally 2 cores), 2GB RAM, 100Mbps internet and 20GB storage.

If you are unsure, or you are refreshing a VM from somewhere like IONOS or Digital Ocean, go with 4 vCores, 4–8GB RAM and 40GB or more of SSD. That should comfortably carry at least 50 SME-sized sites.

What you gain

Once the sites land on the new server, your UI.com Site Manager populates with a lot of additional information, and you get access to Site Magic — site-to-site VPN with automatic connection.

UniFi OS Server updates also run from the web console rather than over SSH, as on the old system.

The process at a glance

Back up properly and have a restore method in case of failure.
Note the legacy OS version, UniFi Network version, UI.com account details and server SSH credentials.
Export a full network settings backup (.unf) from the legacy web interface.
Wipe the server and install Ubuntu 24.04 LTS.
Check the hardware firewall rules are correct.
Run updates, then run the UniFi OS Server installer.
Log in to the new server on port 11443.
Complete the wizard without restoring from backup, signing in with your existing UI.com details.
Start a Network server application and let it install.
In the new Network app, go to Settings / System / Backups and restore from the backup file.
All sites, devices and clients adopt into the new server automatically within a few minutes.
Once everything settles, run all control plane updates and device updates, then take a fresh backup.

Before you wipe anything

Snapshot, back up and note your credentials

Ideally make a working image or snapshot of the existing server, so you can restore it fully if anything goes wrong.
Log in to the legacy UniFi Network server and go to Settings / System / Backup. Download a settings-only, server-wide backup — do not skip this step — and optionally a 7-day backup as a second file if you want some historical data. Busy servers rarely seem to complete longer backups such as 30 days.
Optionally, and not recommended for this same-server method, you can export each site individually under Settings / System / Site Management using Export Site. This is only worth the pain if you plan to migrate to a different server instead. Once each file downloads, do not continue through the wizard — close it and move to the next site.
Note down the legacy OS version, the UniFi Network version, your UI.com account details and the server SSH credentials.

Fresh OS

Wipe the server and install Ubuntu 24.04 LTS

Do a full, fresh install of Ubuntu 24.04 LTS. You do not need desktop access, only SSH server access. You can try to avoid the reinstall by stopping and removing all the legacy software first, but this is a good moment to move to a current OS and start from a clean slate.
Set a strong root password with passwd.

Firewall

Open the right ports

Adjust the hardware firewall rules to match Ubiquiti's required ports reference. Get the TCP and UDP settings right, and check that article for any additional ports your setup needs.

Port	Protocol	Purpose
11443	TCP	UniFi OS Server web UI (GUI/API)
8080	TCP	Device inform. The primary port devices use to phone home to the server, and the guest portal.
3478	UDP	STUN. Used for NAT traversal to help devices find the server.
10001	UDP	Device discovery. Used to find devices on L3 networks for adoption.
10003	UDP	New port for UniFi OS Server [Unknown use]
1900	UDP	L2 discovery [Not required on UniFi OS Server — legacy Network server port]
443	TCP	Remote access. For connecting your server to unifi.ui.com and for secure WebSockets.
8881	TCP	Guest portal (HTTP)
8882	TCP	Guest portal (HTTP)
8843	TCP	Guest portal (HTTPS) [Currently not in the release candidate listing]
8444	TCP	Secure guest portal (HTTPS)
8880	TCP	New port for UniFi OS Server [Unknown use]
6789	TCP	UniFi mobile app speed test
5005	TCP	New port for UniFi OS Server [Unknown use]
9543	TCP	New port for UniFi OS Server [Unknown use]
11084	TCP	New port for UniFi OS Server [Unknown use]
Lock down
22	TCP	SSH — locked to your admin IP. Don't expose this to the world.
Optional
5514	UDP	Remote syslog capture
27117	TCP	Local database comms [Not listed as a required port]

Install

Install UniFi OS Server for Linux

First, updates and dependencies:

Terminal

sudo apt-get update && sudo apt-get install podman slirp4netns
(reboot if required)

Now install the new UniFi OS Server on the fresh Ubuntu box. Visit ui.com/download and copy the latest blue Download link for UniFi OS Server for Linux (x64) — at the time of writing, version 4.3.6.

Run the curl command below, replacing the URL with the one you just copied:

Download

curl -O https://fw-download.ubnt.com/data/unifi-os-server/2f3a-linux-x64-4.3.6-be3b4ae0-6bcd-435d-b893-e93da668b9d0.6-x64

Make the file executable, again matching the file name from your own download:

Make executable

chmod +x 2f3a-linux-x64-4.3.6-be3b4ae0-6bcd-435d-b893-e93da668b9d0.6-x64

Then install it. Note the leading ./ and the trailing install:

Install

./2f3a-linux-x64-4.3.6-be3b4ae0-6bcd-435d-b893-e93da668b9d0.6-x64 install

Give it a few minutes, then open the setup wizard in a browser. The address will look something like https://myowncustomunifiserver.com:11443/setup.

The wizard

Do not restore from backup during setup

This is the step that makes the whole method work. Restoring here instead of later is what forces a slow, site-by-site migration.

Don't choose to restore from backup at this point.
Sign in to your UI.com cloud account. It should also ask for your 2FA details.
Don't choose to restore from backup here either — choose Continue Without Backup.
Complete the wizard and launch a Network application.
You should now reach your new UniFi OS Server with no sites installed, at :11443/network.

Restore

Restore the .unf file and let everything adopt

In the Network web interface, go to Settings / System / Backups, choose Restore, and select the single server-wide .unf file from the legacy server. This may take four to eight minutes and will restart the server automatically. Be patient.

After a few minutes, check that all of your sites, devices and clients are logging in. They should be — if not, retrace the steps above.

Finish up

Updates, then a fresh backup

Once everything has re-appeared, run the device updates — but don't run the control plane updates at the same time. Wait for the devices to finish first.
Take a new backup under Settings / System / Backups on the new UniFi OS Server.
That's the migration done.

Optional

Add a swap file

Swap file and swappiness

sudo swapon --show
### Use above command to check for any swap files - if no output then there is no swap file - so continue###

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
sudo swapon --show

free -h

##Now we need to make it permanent###

sudo nano /etc/fstab

###When nano opens the fstab then add the following line and then save it###

/swapfile none swap sw 0 0

###Now tune the swap behavior - default is 60###
cat /proc/sys/vm/swappiness

###
sudo sysctl vm.swappiness=20

###Now edit sysctl.conf###
nano /etc/sysctl.conf

###Add this to the end of the file###
vm.swappiness=20

###Done###

Same server, same DNS, every site adopted automatically.

What you get in Site Manager

With all sites on the new server, your UI.com account fills out considerably. These are the pages worth bookmarking:

https://unifi.ui.com/All sites visible
https://unifi.ui.com/sd-wan/hub-spoke/newSet up a hub and spoke or mesh — Site Magic
https://unifi.ui.com/isp-viewerOverview of all site performance
https://unifi.ui.com/update-manager/uosUniFi OS Server updates
https://unifi.ui.com/update-manager/appsApplication updates
https://unifi.ui.com/update-manager/devicesDevice updates
https://unifi.ui.com/admins-listAdministrator list

Auto-backup path

/home/uosserver/.local/share/containers/storage/volumes/uosserver_var_lib_unifi/_data/backup/autobackup

Benchmarking the server

CPU benchmark

apt-get install sysbench
sysbench cpu run
sysbench --threads="$(nproc)" cpu run

Too daunting to take on yourself?

If you are an individual or another IT company, give us a call and we can perform this migration for you.

Get in touch

References

Self-hosting UniFihelp.ui.com
Required ports referencehelp.ui.com
UniFi release notescommunity.ui.com
Backups and migration in UniFihelp.ui.com
Setting up SD-WAN with UniFi Site Magichelp.ui.com
UniFi OS Server SSL importAdd a Let's Encrypt SSL certificate to the server

There is also a YouTube walkthrough (watch?v=kL1kqhVNji8) covering UniFi OS Server setup. It isn't a migration method like this one, but it touches on using Cloudflare and a software firewall setup.

Looking for the UniFi OS Server health monitoring software?

Our monitoring script keeps an eye on the server once the migration is done. Read about the health monitoring script and software, or see our wider Ubiquiti work and network installation services.