UniFi OS Server unter Rocky Linux 10 installieren und bestehenden Network Server migrieren

Einleitung

Ich hatte UniFi Network bisher als klassische selbst gehostete Network Application in einem kleinen Ubuntu-LXC unter Proxmox laufen. Das funktioniert hervorragend, Ubiquiti weist inzwischen aber recht deutlich darauf hin, dass UniFi OS Server der neue Standard für Self-Hosting ist und die klassische Network-Server-Variante langfristig ersetzt.

Der neue Aufbau bringt die UniFi-OS-Control-Plane auch auf einen eigenen Linux-Server. Unter Linux verwendet UniFi OS Server dafür Podman und pasta. Das klingt zunächst ein wenig nach „Container in VM, weil einfach auch noch eine Schicht dazwischen passt“, hat aber einen praktischen Vorteil: Die neue Installation lässt sich sauber parallel zum bisherigen Controller aufbauen und testen.

Dieser Artikel beschreibt die bei mir getestete Migration von:

Proxmox Ubuntu LXC
└── UniFi Network 10.4.57

auf:

Proxmox VM
└── Rocky Linux 10
    ├── SELinux Enforcing
    ├── firewalld
    ├── Podman / pasta
    └── UniFi OS Server 5.1.37
        └── UniFi Network 10.6.101

Die Installation bleibt dabei Local-Only. Ein UI.com-Account oder Cloud-Management ist nicht erforderlich. Ubiquiti unterstützt ausdrücklich auch lokale beziehungsweise vollständig air-gapped betriebene Installationen. Und beim Netzwerk-Management stehe ich auf Privatspäre.

Alle IP-Adressen in diesem Artikel stammen aus den Dokumentationsnetzen 192.0.2.0/24 und 198.51.100.0/24 und müssen an die eigene Umgebung angepasst werden.

Verwendete Versionen

Stand: 1. September 2026

Komponente	Verwendete Version / Konfiguration
Hypervisor	Proxmox VE 9.2.11
Betriebssystem	Rocky Linux 10.2
SELinux	Enforcing
Firewall	firewalld
Container Runtime	Podman aus den Rocky-Repositories
Netzwerk-Backend	`pasta` aus dem Paket `passt`
Zusätzliche Rootless-Komponente	`slirp4netns` 1.2 oder neuer
UniFi OS Server	5.1.37 Official
Mit UniFi OS Server 5.1.37 ausgeliefertes Network	10.5.67
Ausgangsversion	UniFi Network 10.4.57
Zielversion nach Update	UniFi Network 10.6.101
Remote Management	deaktiviert / Local-Only

UniFi OS Server 5.1.40 war zum Zeitpunkt der Migration noch Release Candidate. Die Version enthält unter Linux unter anderem Verbesserungen an Datei- und Verzeichnisrechten. Da 5.1.37 bei der hier beschriebenen Rocky-Installation weder SELinux- noch Berechtigungsprobleme zeigte, bin ich mal auf dem stabilen 5.1.37-Release geblieben. Einen RC einzubauen, nur weil er neuer ist, ist bei Infrastruktur selten ein Qualitätsmerkmal ...

Anforderungen von UniFi OS Server

Ubiquiti unterstützt für Linux ausdrücklich Ubuntu 24.04 oder neuer, Debian 13 oder neuer sowie andere moderne Linux-Distributionen, sofern mindestens folgende Anforderungen erfüllt sind:

systemd
libc >= 2.31
Podman >= 4.9.3 mit pasta-Networking
slirp4netns >= 1.2
x86-64 CPU
mindestens 2 GiB RAM
mindestens 10 GiB freier Speicher

Rocky Linux 10 erfüllt diese Anforderungen. pasta wird unter Rocky über das Paket passt bereitgestellt; für SELinux gibt es zusätzlich das Paket passt-selinux.

Für eine kleine private UniFi-Installation wie meine reichen die Mindestanforderungen von Unifi eigentlich aus. Ich werde das noch mal beobachten und später - bei Engpässen - ggf. nach oben erweitern:

2 vCPU
2 GiB RAM
32 GiB Systemdisk
VirtIO-Netzwerk
QEMU Guest Agent

Die VM ist absichtlich eine normale virtuelle Maschine und kein LXC. UniFi OS Server betreibt selbst eine containerisierte Umgebung. Podman innerhalb eines privilegierten LXC funktioniert zwar grundsätzlich, eine VM liefert hier aber die sauberere Isolationsgrenze (man würde einen privilegierten LXC benötigen) und erspart unnötiges Container-Nesting.

Proxmox-Snapshots für die Migration sind unproblematisch. Eine bereits eingerichtete UniFi-OS-VM sollte dagegen nicht einfach als allgemeines Template geklont werden. Ubiquiti warnt davor, weil geklonte Instanzen identische Remote-Access- beziehungsweise Fabric-Tokens enthalten können. Für einen neuen Server besser immer eine frische Installation verwenden.

Zielarchitektur

Für die Migration wird die neue Instanz zunächst mit einer temporären IP-Adresse parallel betrieben:

Komponente	Beispiel
Alter UniFi Network Server	`192.0.2.20`
Neue UniFi-OS-VM während der Migration	`192.0.2.21`
Spätere produktive Adresse	`192.0.2.20`
UniFi OS Webinterface	`https://192.0.2.21:11443`
Device Inform	`8080/tcp`
STUN	`3478/udp`

Der alte Controller bleibt bis zum eigentlichen Cutover unangetastet. Das macht den Rückweg angenehm langweilig: neue VM aus, alter LXC wieder an.

Rocky Linux vorbereiten

Nach einer minimalen Rocky-Linux-Installation wird das System zunächst aktualisiert:

sudo dnf upgrade -y
sudo systemctl reboot

Danach kontrollieren:

cat /etc/rocky-release
getenforce
sudo firewall-cmd --state
timedatectl

Erwartet werden insbesondere:

SELinux: Enforcing
firewalld: running
System clock synchronized: yes

SELinux wird nicht vorsorglich abgeschaltet. Wenn später etwas blockiert wird, wird der konkrete AVC analysiert. setenforce 0 ist Diagnose, keine Konfiguration.

Benötigte Pakete installieren

Für UniFi OS Server werden Podman, pasta und slirp4netns benötigt. Zusätzlich installieren wir den QEMU Guest Agent und einige Werkzeuge für die spätere Diagnose:

sudo dnf install -y \
    podman \
    slirp4netns \
    passt \
    passt-selinux \
    qemu-guest-agent \
    curl \
    wget \
    audit \
    policycoreutils-python-utils

Den QEMU Guest Agent anschließend aktivieren:

sudo systemctl enable --now qemu-guest-agent

Versionen prüfen:

podman --version
slirp4netns --version
pasta --version
ldd --version | head -n1

Zusätzlich sollte Podman selbst ohne Fehler initialisieren:

podman info

firewalld vorbereiten

Zunächst die aktive Zone bestimmen:

sudo firewall-cmd --get-active-zones

Im Beispiel heißt sie public:

ZONE=public

Für die erste Inbetriebnahme reichen in einer typischen Umgebung zunächst folgende eingehenden Ports:

sudo firewall-cmd --zone="$ZONE" --add-port=11443/tcp
sudo firewall-cmd --zone="$ZONE" --add-port=8080/tcp
sudo firewall-cmd --zone="$ZONE" --add-port=3478/udp

Bedeutung:

Port	Funktion
`11443/tcp`	Weboberfläche/API des UniFi OS Servers
`8080/tcp`	Kommunikation zwischen Network Application und UniFi-Geräten / Inform
`3478/udp`	STUN für Adoption und Gerätekommunikation
`10001/udp`	lokale Device Discovery während der Adoption

Die Regeln werden zunächst absichtlich nur zur Runtime hinzugefügt. Nach erfolgreichem Test können sie dauerhaft übernommen werden:

sudo firewall-cmd --runtime-to-permanent

Wer verschiedene Management- und UniFi-Netze verwendet, sollte die Regeln später über Rich Rules auf die tatsächlich notwendigen Quellnetze begrenzen. Beispiel:

sudo firewall-cmd --zone="$ZONE" --remove-port=11443/tcp
sudo firewall-cmd --zone="$ZONE" \
  --add-rich-rule='rule family="ipv4" source address="198.51.100.0/24" port protocol="tcp" port="11443" accept'

Für 8080/tcp und 3478/udp werden entsprechend die Netze freigeschaltet, in denen die UniFi-Geräte liegen.

Nicht alle von Ubiquiti dokumentierten UniFi-Ports müssen pauschal für jedes Netz geöffnet werden. Für lokale Discovery nennt die allgemeine Network-Portreferenz zusätzlich 10001/udp; bei einer Migration bereits adoptierter Geräte über einen bekannten Inform-Host ist dieser Port normalerweise nicht erforderlich. Hotspot, Syslog, Speedtest und weitere Zusatzfunktionen bekommen ebenfalls nur dann Regeln, wenn sie tatsächlich verwendet werden. Im Zweifel zeigt ss -tulpn, was die installierte UOS-Version auf dem Host tatsächlich bindet.

Bei Nutzung eines Captive Portals ist außerdem wichtig: Beim UniFi OS Server verwendet das Secure Portal 8444/tcp; beim alten Network Server wurde dafür 8843/tcp verwendet.

UniFi OS Server installieren

Die aktuelle Linux-x64-Version wird direkt von Ubiquiti heruntergeladen. Den Download-Link holt man sich aus der offiziellen UniFi-OS-Server-Release-Seite oder dem Ubiquiti Download-Bereich.

Beispiel:

mkdir -p ~/uos-install
cd ~/uos-install

UOS_URL='HIER-DEN-AKTUELLEN-LINUX-X64-DOWNLOAD-LINK-EINTRAGEN'

curl -fLO "$UOS_URL"
ls -lh

Anschließend die heruntergeladene Datei ausführbar machen und starten:

chmod +x ./<installer-datei>
sudo ./<installer-datei>

Ubiquiti liefert dafür bewusst einen eigenen Installer. UniFi OS Server sollte nicht eigenmächtig als selbst gebauter Docker- oder Podman-Stack nachgebaut werden; für die offizielle Installation werden auch Dienste auf dem Host eingerichtet.

Nach Abschluss:

sudo systemctl status uosserver --no-pager
sudo systemctl enable uosserver # wenn nicht bereits enabled!

Listener prüfen:

sudo ss -lntup | grep -E ':(11443|8080|3478|10001|8444|6789)\b'

Die Control Plane ist anschließend über folgende Adresse erreichbar:

https://192.0.2.21:11443

Eine Zertifikatswarnung beim ersten Aufruf ist bei Verwendung des mitgelieferten Zertifikats normal.

Local-Only statt Cloud Management

Remote Management über unifi.ui.com ist optional. Für eine rein lokale Installation wird es nicht aktiviert beziehungsweise nach dem Setup deaktiviert.

Ubiquiti beschreibt Local Management ausdrücklich auch für vollständig air-gapped Umgebungen. Lokale Administratoren lassen sich ohne UI.com-Account anlegen.

Der gewünschte Aufbau bleibt damit:

Admin-PC / VPN
      |
      v
UniFi OS Server im lokalen Netz
      |
      v
APs, Switches und ggf. UXG

und nicht:

Admin -> Ubiquiti Cloud -> eigener Controller

SELinux nach der Installation prüfen

Direkt nach der Installation wird kontrolliert, ob SELinux irgendwelche Zugriffe des UniFi OS Servers blockiert:

getenforce
sudo ausearch -m AVC -ts recent

Etwas gezielter:

sudo ausearch -m AVC -ts recent | \
    grep -Ei 'uos|unifi|podman|pasta|passt'

Bei der hier beschriebenen Installation gab es keine SELinux-AVCs. Entsprechend war auch keine zusätzliche lokale Policy notwendig.

Falls doch Denials auftauchen:

sudo ausearch -m AVC -ts recent | audit2why

Erst danach wird entschieden, ob ein falsches Label, ein vorhandener Boolean oder tatsächlich eine kleine lokale Policy die richtige Lösung ist. audit2allow blind über das gesamte Audit-Log laufen zu lassen, produziert schnell eine sehr großzügige Policy – und Großzügigkeit ist bei MAC-Systemen eher selten das Ziel.

Alten UniFi Network Server sichern

Vor der Migration wird auf der alten Network-10.4.57-Instanz ein lokales Network-Backup erzeugt:

Settings
-> Control Plane
-> Backups

Das Ergebnis ist eine Datei mit der Endung:

*.unf

Bei der hier durchgeführten Migration enthielt das Backup 365 Tage Statistikdaten und war etwa 60 MiB groß.

Zusätzlich sollten die Device-SSH-Zugangsdaten notiert beziehungsweise gesichert werden:

Devices
-> Device Updates & Settings
-> Device SSH Settings

Ubiquiti empfiehlt das ausdrücklich, falls einzelne Geräte nach der Migration manuell auf den neuen Inform-Host gesetzt werden müssen.

Vor dem Restore ist außerdem ein Proxmox-Snapshot der neuen VM sinnvoll. Der alte LXC bleibt vollständig erhalten.

Damit existieren gleich mehrere Rückfallebenen:

altes .unf-Backup
+
alter UniFi-LXC
+
Snapshot der neuen Rocky-VM

Backup auf dem UniFi OS Server wiederherstellen

Die neue UniFi-OS-Instanz wird zunächst vollständig eingerichtet. Danach erfolgt der Restore innerhalb der neuen Control Plane:

Settings
-> Control Plane
-> Backups
-> Restore

Dort wird das .unf der alten Network-10.4.57-Installation eingespielt.

Nach dem Restore werden mindestens folgende Bereiche verglichen:

Sites
Devices
Networks und VLANs
WLANs
Port Profiles
Device SSH Settings
RADIUS, falls verwendet
Syslog und SNMP, falls verwendet
historische Statistiken

Fallstrick: „Backup Restoration Partially Complete“

Bei der hier beschriebenen Migration meldete die UniFi-OS-Control-Plane nach dem Restore:

Backup Restoration Partially Complete

An error occurred while restoring 'UniFi Network'.
Please try again or continue without restoring the application.

Das klang zunächst ziemlich eindeutig nach „hat nicht funktioniert“. Nach Auswahl von Continue und anschließendem Start der Network Application waren allerdings sämtliche importierten Einstellungen vorhanden. Der Restore war also offensichtlich weiter gekommen, als es der Assistent zugeben wollte.

Bei dieser Meldung würde ich deshalb nicht sofort mehrfach auf „Try Again“ klicken. Zuerst:

Setup mit Continue abschließen.
Network Application starten.
Prüfen, ob Sites, Geräte, Netze, WLANs und Einstellungen vorhanden sind.
Erst bei tatsächlich fehlenden Daten einen weiteren Restore versuchen.

Parallel helfen folgende Prüfungen:

sudo systemctl status uosserver --no-pager
sudo journalctl -u uosserver -n 200 --no-pager
sudo ausearch -m AVC -ts recent

In meinem Fall gab es weder SELinux-Fehler noch Hinweise auf einen Berechtigungsfehler. Das Problem war damit eher der Status des Restore-Assistenten als der tatsächliche Import. Jeder der Unifi schon etwas länger benutzt kennt diese kleinen Dinge ja sicherlich ...

Fallstrick: Podman als uosserver-Benutzer aufrufen

Für Diagnosezwecke kann die Podman-Umgebung des UniFi-OS-Dienstbenutzers interessant sein. Wird der Befehl allerdings aus einem privaten Home-Verzeichnis eines anderen Benutzers gestartet, kann folgende Meldung erscheinen:

cannot chdir to /home/<adminuser>: Permission denied

Das ist kein SELinux-Fehler und kein Defekt von UniFi OS Server. Der Benutzer uosserver darf schlicht nicht in das aktuelle Home-Verzeichnis wechseln.

Vorher in ein allgemein zugängliches Verzeichnis wechseln:

cd /
sudo -u uosserver -H podman ps -a

oder beispielsweise:

(cd / && sudo -u uosserver -H podman ps -a)

Nicht jede interne UOS-Komponente muss für den normalen Betrieb per Podman-CLI angefasst werden. Für die erste Diagnose sind systemctl, journalctl und die SELinux-Audit-Logs meistens die sinnvolleren Einstiegspunkte.

Network Application aktualisieren

UniFi OS Server 5.1.37 wurde mit Network 10.5.67 installiert. Nach erfolgreichem Restore wurde vor dem produktiven Cutover auf Network 10.6.101 aktualisiert.

Das ist ein günstiger Zeitpunkt für das Update: Der alte 10.4.57-Controller läuft noch unverändert, die neue VM ist noch nicht produktiv und ein Proxmox-Snapshot erlaubt einen schnellen Rücksprung.

Vor dem Update:

Einstellungen des Restores prüfen.
Optional ein neues Backup aus der restaurierten 10.5.67-Instanz erzeugen.
Proxmox-Snapshot erstellen.

Danach Network über die lokale UniFi-OS-Control-Plane aktualisieren.

Nach dem Update:

sudo systemctl status uosserver --no-pager
sudo systemctl --failed
sudo ausearch -m AVC -ts recent

In der Network Application erneut stichprobenartig kontrollieren:

Sites
Networks / VLANs
WLANs
Devices
Port Profiles
Device SSH Settings
Statistik-Historie

Zum Zeitpunkt dieses Artikels befindet sich Network 10.6.101 im Official-Kanal mit stufenweisem Rollout. Bei Ubiquiti können Detailseite und Release-Übersicht während einer Promotion kurzzeitig unterschiedliche Kanalangaben anzeigen.

Warum UniFi OS Server 5.1.37 und nicht 5.1.40 RC?

UniFi OS Server 5.1.40 enthielt zum Zeitpunkt der Installation insbesondere folgende für Linux interessante Änderung:

Improved Linux directory and file permissions.

Das wäre ein guter Grund gewesen, 5.1.40 zu testen, wenn unter Rocky 10 tatsächlich Datei-, Ownership- oder SELinux-Probleme aufgetreten wären.

Genau das war aber nicht der Fall:

SELinux: Enforcing
keine relevanten AVC-Denials
UOS startet sauber
Network-Restore vorhanden

Damit gab es keinen technischen Vorteil, die Control Plane kurz vor dem Cutover auf einen Release Candidate anzuheben. Network 10.6.101 kann unabhängig davon aktualisiert werden. Das Update hole ich dann nach, wenn der RC Status weg ist.

Produktiver Cutover

Wenn die neue Instanz vollständig geprüft ist, kann der eigentliche Wechsel erfolgen. Am einfachsten ist es, wenn die neue VM anschließend die bisherige IP-Adresse des alten Controllers übernimmt.

Ausgangslage:

alter LXC: 192.0.2.20
neue VM:   192.0.2.21

Ziel:

alter LXC: AUS
neue VM:   192.0.2.20

Der alte Network Server wird sauber heruntergefahren und bleibt zunächst erhalten. Die Geräte werden dort nicht auf „Forget“ gesetzt. Dadurch bleibt ein einfacher Rollback möglich.

Auf Rocky lässt sich die Adresse beispielsweise mit NetworkManager ändern. Zuerst den Connection-Namen ermitteln:

nmcli connection show

Danach beispielhaft:

sudo nmcli connection modify ens18 \
    ipv4.method manual \
    ipv4.addresses 192.0.2.20/24 \
    ipv4.gateway 192.0.2.1 \
    ipv4.dns "192.0.2.53"

sudo nmcli connection up ens18

Die SSH-Sitzung bricht dabei erwartungsgemäß ab.

Da der Inform-Port weiterhin 8080/tcp verwendet wird und die Geräte weiterhin dieselbe Controller-Adresse kennen, sollten sie sich anschließend selbstständig am neuen Server melden:

http://192.0.2.20:8080/inform

Ein set-inform, Factory Reset oder eine komplette Neu-Adoption ist bei unveränderter Controller-Adresse normalerweise nicht notwendig. Bei mir waren nach einiger Zeit alle Geräte in der neuen Network App online wie man es vorher auch gewohntr war.

Wenn ein Gerät nicht wieder online kommt

Zuerst Erreichbarkeit prüfen:

ping <device-ip>

Falls Device SSH aktiviert ist:

ssh <device-user>@<device-ip>

Auf vielen UniFi-Geräten zeigt:

info

unter anderem den aktuellen Controller-/Inform-Status.

Nur wenn das Gerät tatsächlich noch auf eine falsche Adresse zeigt, kann der Inform-Host korrigiert werden:

set-inform http://192.0.2.20:8080/inform

Ein Factory Reset ist der letzte Schritt, nicht der erste. UniFi-Geräte sind Netzwerkkomponenten, keine Drucker aus den Neunzigern.

Abschlussprüfung

Nach erfolgreichem Cutover:

sudo systemctl status uosserver --no-pager
sudo systemctl --failed
sudo firewall-cmd --list-all
getenforce
sudo ausearch -m AVC -ts recent

Zusätzlich die wichtigsten Listener prüfen:

sudo ss -tulpn | grep -E ':(11443|8080|3478|10001|8444|6789)\b'

Praktische Funktionstests:

lokal an der UniFi-OS-Control-Plane anmelden
alle Sites öffnen (bei mir ist das genau eine :D )
APs und Switches auf Online prüfen
ein WLAN mit einem Testclient verbinden
VLAN-Zuordnung und DHCP prüfen
mindestens eine Switch-Port-Konfiguration kontrollieren
historische Statistiken öffnen
lokale Administratoren und Remote-Management-Einstellung prüfen
neuen Network-/System-Backup-Stand erzeugen
Proxmox-/PBS-Backup der fertigen VM erstellen

Backup und Rollback

Nach erfolgreicher Migration werden zwei voneinander unabhängige Backup-Ebenen verwendet:

lokales UniFi Backup
+
Proxmox/PBS-Backup der gesamten VM

Den alten LXC werde ich noch mindestens einige Tage bis zwei Wochen behalten, aber seinen automatischen Start deaktivieren und das Netzwerkinterface auf disconnect stellen. Zwei Controller mit derselben IP-Adresse nach einem Hypervisor-Reboot wären zwar abwechslungsreich, aber nicht hilfreich.

Der Rollback bleibt dadurch sehr einfach:

1. neue Rocky-VM ausschalten
2. alten LXC einschalten
3. alte Controller-IP ist wieder vorhanden
4. Geräte verbinden sich wieder über Port 8080

Erst wenn die neue Installation einige Zeit stabil gelaufen ist und aktuelle Backups erfolgreich getestet wurden, kann die alte Instanz endgültig entfernt werden.

Weiterführende Informationen und Quellen

Zuletzt aktualisiert am 01.09.2026 · 3 Aufrufe

Installation

Konfiguration

Update

Forgejo sicher mit PostgreSQL und Reverse Proxy betreiben

Forgejo im Alltag betreiben