New UniFi OS Server Lets You Self-Host the Full UniFi Experience
If you have been following the news lately, Ubiquiti just released something very exciting, UniFi OS Server. This will likely change how we self-host our Unifi controller and network application moving forward. Let’s take a deep dive into what this new offering is, what its capabilities are, and what we can use to self-host it in the home lab.
What is UniFi OS Server?
UniFi OS Server is a new self-hosted platform from Ubiquiti that brings the full UniFi OS experience. This was previously limited to UniFi Consoles like the Dream Machine or Cloud Key. However, now with this self-hostable software solution, it brings it to your own hardware. And, it gives you options on how and on what OS you self-host it, including Windows, macOS, or Linux. UniFi OS Server enables you to install and manage UniFi applications through the familiar UniFi OS interface.
At launch, it includes support for UniFi Network and InnerSpace. Keep in mind this is going to be a foundational piece of software that sets the stage for more UniFi apps to be added in the future. I think it will give home labbers and IT pros even more flexibility in how they deploy and manage UniFi environments.
Ubiquiti has built the software architecture in such a way that it is modular and can support additional applications in the future, so I would imagine this is going to be the “scaffolding” for all the Unifi apps moving forward.
How UniFi OS Server compares to standalone UniFi Network
Ok, so I know the first question from most will have (and I did too), is what is the difference between Unifi OS Server and the standalone Unifi Network application. For years now, I have self-hosted the Unifi Network application directly in a Docker container.
But that setup with only the network application lacks many of the features that make UniFi OS so powerful.
Here’s what you get with UniFi OS Server that you don’t with the legacy controller:
- Full UniFi OS dashboard – with this you get the same interface as UDM and Cloud Key users, including the navigation, application cards, and a central settings area
- Future app support – Because it runs the full OS, you’ll be able to install additional UniFi apps as they’re released for the platform
- Automatic updates – You can manage both the OS and application updates from a single place. Typically, you have to handle the updates yourself like I do with Watchtower, Portainer, or a CRON job of sorts to schedule pulling a new container image
- Cross-platform flexibility – It’s not tied to a specific OS. You can run UniFi OS Server on Windows, Linux, or macOS
Apps that are included
As of version 4.2.23, UniFi OS Server includes:
- UniFi Network 9.3.43
- InnerSpace (currently in early access)
This is just the beginning though. Protect, Talk, and other applications aren’t yet included, but the architecture is clearly designed to support them in a future release.
System requirements for Unifi OS Server
The system requirements are light, making it accessible for nearly any lab or IT setup.
- Disk Space At least 20 GB of free space is required
- Software Dependencies – O
- On Linux: Podman 4.3.1 or higher
- On Windows: WSL2 is installed automatically during setup
- macOS support is also available, although details are still developing
- Make sure the following ports are open: 3478, 5005, 5514, 6789, 8080, 8444, 8880, 8881, 8882, 9543, 10003, 11443
The installer includes or helps you configure the necessary dependencies, depending on the operating system.
Getting your hands on it
You can start the process to get your hands on it here:
No LXC containers for this one 🙁
If you are like me when you first started thinking about how you would architect the installation of this in your lab, my first thought was an LXC container in Proxmox. However, I quickly ran into problems with this during the installation. There are hard blockers that prevent the UOS installer from functioning properly inside an LXC environment.
Here are the main issues you will find with trying to install this in an LXC container:
- Kernel modules can’t be loaded in LXC. UOS requires macvlan, which the installer tries to load via modprobe. This fails in containers because they don’t have access to the host kernel module loader.
- Sysctl settings can’t be modified. The installer attempts to set multiple system-level kernel parameters using sysctl, which fails in LXC due to a read-only /proc/sys and other enforced restrictions.
- Podman-based networking features fail silently or partially. Even if Podman and slirp4netns are installed, their functionality is limited or broken under containerized isolation, which breaks the networking setup that you need and that UOS expects.
Below is a look at the output I saw when trying to install Unifi OS Server in an LXC container:
root@unifi-os:~# ./8b93-linux-x64-4.2.23-158fa00b-6b2c-4cd8-94ea-e92bc4a81369.23-x64
Checking compatible podman runtime available...
Checking slirp4netns available...
You are about to install UOS Server version 4.2.23. Proceed? (y/N): y
Installing UOS Server 4.2.23...
Checking ports...
Adding uosserver user and group...
Creating /var/lib/uosserver dir...
Creating /var/lib/uosserver/logs dir...
Setting up /usr/local/bin/uosserver binary...
Setting up /var/lib/uosserver/discovery binary...
Setting up /usr/local/bin/uosserver-purge binary...
Initializing containers.conf...
Creating file /var/lib/uosserver/containers.conf...
Checking macvlan module enabled...
enabling macvlan...
modprobe: FATAL: Module macvlan not found in directory /lib/modules/6.8.12-11-pve
persisting macvlan...
Persisted macvlan module in /etc/modules-load.d/macvlan.conf
Allowing raw socket execution...
sysctl: setting key "kernel.apparmor_restrict_unprivileged_userns", ignoring: Read-only file system
sysctl: setting key "kernel.printk", ignoring: Read-only file system
sysctl: setting key "kernel.kptr_restrict", ignoring: Read-only file system
sysctl: setting key "kernel.sysrq", ignoring: Read-only file system
sysctl: setting key "vm.max_map_count", ignoring: Read-only file system
sysctl: setting key "kernel.yama.ptrace_scope", ignoring: Read-only file system
sysctl: setting key "vm.mmap_min_addr", ignoring: Read-only file system
sysctl: setting key "kernel.pid_max", ignoring: Read-only file system
sysctl: setting key "fs.protected_fifos", ignoring: Read-only file system
sysctl: setting key "fs.protected_hardlinks", ignoring: Read-only file system
sysctl: setting key "fs.protected_regular", ignoring: Read-only file system
sysctl: setting key "fs.protected_symlinks", ignoring: Read-only file system
sysctl: setting key "net.ipv4.ping_group_range": Invalid argument
root@unifi-os:~# Even if you pre-load the macvlan module on the Proxmox host and try to bind-mount configs, UOS will still throw errors or silently misbehave. For now, a full VM is the only supported and stable environment.
After installing it in a virtual machine
It was easy enough to spin up the new Unifi OS Server in an Ubuntu Server virtual machine. One of the first things I did was install podman. You can do that with the command:
sudo apt install -y podman
Then, you can use the wget command to pull down the file that is presented on the download links after you have signed up for early access.
Make the file executable:
chmod +x <installation file>Then just run the file:
sudo ./<installation file>
After the installation finishes, you should see an output that looks similar to the below with the address of your server running on port 11443.
When you browse to the port listed, you will see the initial dashboard splash screen for Unifi OS Server setup. Click Next.
One thing I like is that if you already have a UI account, you can just use this to get things setup initially, which I do.
After you either create a login or use an existing login, the setup will complete successfully and ask to take you to the dashboard.
And here we see the Network application by default, which should look familar.
Known issues (Early Access)
Because UniFi OS Server is still in early access, there are some current issues to be aware of if you are spinning up the EA release:
- Doesn’t work with an LXC container – again as mentioned above, this is a bummer but hopefully this will be something that may be worked through in the future
- Linux updates are not currently working – On Linux systems, OS and app updates currently do not work when initiated from the control plane or app menu.
- Temporary setup message – The UniFi Network app may show a “setup” status for up to a minute even when it’s running correctly.
- Windows upgrade requires admin – On Windows, upgrades triggered through Site Manager require the application to be launched with Administrator privileges.
I am hoping the LXC container issue will be something that we can find a way to resolve in the future, but the other issues will likely be taken care of in due time.
Why the Unifi OS Server is a step forward in the right direction
This Unifi OS Server release provides the benefits of a UniFi console without the hardware limitations that we have had previously. You can now run a full UniFi stack inside a VM or container on your Proxmox or VMware host or other hypervisor. Want to manage multiple sites or test future UniFi apps before rolling them out to clients? UniFi OS Server is your playground. It also means you can self-host a more production-grade UniFi instance for free, while still benefiting from official updates and features that previously required a hardware purchase.
Wrapping up
Granted this Unifi OS Server release is very early on so it is expected there will be some quirks with it. However, I think this gives us a glimpse of where Unifi is headed on the software side and especially for self-hosting and MSPs looking to manage multiple environments in a single management instance. For many, UniFi OS Server might just become the go-to way to deploy and manage UniFi environments without needing a UDM Pro or Cloud Key. I am for now still going to be self-hosting in the Docker container environment I have setup for the Unifi network application. But, this could very well be the way I go once things are GA and stabilize. What about you? What do you think about this new Unifi OS Server?
