UniFi OS Server auf dem Pi 5 - Migration vom Network Server

UniFi OS Server auf dem Raspberry Pi 5 - Migration vom Network Server

Mein UniFi Network Server lief als ganz normaler Dienst auf einem Raspberry Pi 5. Weil Ubiquiti die eigenständige Network-Version auslaufen lässt, habe ich ihn auf den UniFi OS Server umgezogen. Der Umzug selbst dauerte keine 20 Minuten, die Nacharbeiten haben mich länger beschäftigt. Hier findest du alle Schritte, die Stolpersteine und das, was danach nicht mehr funktioniert.

DarkWolfCave.de

ℹ️ Voraussetzungen: Ein Raspberry Pi 5 mit 64-Bit-Raspberry-Pi-OS auf Basis von Debian 13 (Trixie), ein laufender UniFi Network Server mit aktuellem Backup und ein Gateway, das der UniFi OS Server verwalten kann. Das ist ein Gateway der UXG-Serie oder ein Router eines anderen Herstellers, aber keine Dream Machine und kein Cloud Gateway. Alle Befehle sind auf einem Pi 5 mit 16 GB RAM gelaufen.

Warum der Umstieg auf den UniFi OS Server ansteht

Ubiquiti nennt den UniFi OS Server in der eigenen Self-Hosting-Doku den neuen Standard für selbst gehostetes UniFi. Der bisherige Network Server läuft dort nur noch unter “legacy”. Beim Login in meinen alten Network Server erschien außerdem der Hinweis “Upgrade to UniFi OS Server”. Darin steht direkt im ersten Satz, dass der Network Server kommende Network-Versionen nicht mehr unterstützen wird.

Network 11 setzt UniFi OS 6 voraus, und die eigenständig gehostete Network Application fällt weg, wie unter anderem Borns IT-Blog zusammenfasst. Für den Network Server ist damit bei Version 10.6 Schluss. Auch das alte USG wird von Network 11 nicht mehr unterstützt. Ich hatte es zum Glück schon gegen ein UniFi Gateway Max getauscht.

Der UniFi OS Server steht aktuell bei Version 5.1.42, und mir hat er als neueste Network-Version 10.6.109 angeboten. Network 11 bekommst du also auch nach dem Umzug noch nicht. Der Umzug lohnt sich trotzdem jetzt, weil neue Network-Versionen nur noch für UniFi OS erscheinen und du die Umstellung in Ruhe machen kannst, statt unter Zeitdruck.

UniFi OS Server, Podman und 16K-Kernel kurz erklärt

Wenn du die drei Begriffe schon kennst, spring direkt zur Vorbereitung.

Was ist der UniFi OS Server?

Der alte Network Server ist eine Java-Anwendung mit eigener MongoDB. Er läuft als systemd-Dienst unifi, die Oberfläche erreichst du auf Port 8443.

Der UniFi OS Server bringt dagegen das komplette UniFi OS mit. Laut Ubiquiti bekommst du damit dieselbe Verwaltung wie auf Cloud Keys und Cloud Gateways. Die Network-App ist darin nur noch eine Anwendung unter mehreren. Im Container laufen bei mir neben der Network-App auch unifi-core, PostgreSQL 14, RabbitMQ und eine MongoDB 3.6. Die Benutzerverwaltung übernimmt jetzt UniFi OS und nicht mehr die Network-App.

Was ist Podman?

Podman ist eine Container-Software wie Docker. Die Befehle sind weitgehend gleich, aus docker ps wird podman ps. Der größte Unterschied: Podman braucht keinen zentralen Hintergrunddienst, und Container können ohne Root-Rechte unter einem normalen Benutzer laufen (rootless).

Der UniFi OS Server setzt auf diese Variante. Der Installer legt den Benutzer uosserver an, und der Container läuft unter diesem Benutzer. Ein einfaches sudo podman ps zeigt ihn deshalb nicht an. Du musst den Befehl als uosserver ausführen:

# Auf dem Pi per SSH: Container des UniFi OS Servers anzeigen (läuft unter dem User uosserver)
sudo -u uosserver XDG_RUNTIME_DIR=/run/user/$(id -u uosserver) podman ps

In der Statusspalte sollte (healthy) stehen. Zwei weitere Begriffe tauchen beim Installer auf. pasta verbindet den Container ohne Root-Rechte mit dem Netzwerk des Hosts, der Installer bringt dafür eine eigene Version mit. linger sorgt dafür, dass die Dienste des Benutzers uosserver laufen, ohne dass sich jemand anmeldet. Beides richtet der Installer selbst ein.

Ubiquiti bietet den UniFi OS Server übrigens bewusst nicht als einzelnes Docker- oder Podman-Image an. Laut FAQ braucht er Dienste direkt auf dem Host, etwa für die Geräteerkennung und die automatischen Updates. Podman und Docker vertragen sich aber auf demselben Pi: Bei mir laufen alle bestehenden Docker-Container unverändert weiter.

Was hat es mit dem 16K-Kernel auf sich?

Linux verwaltet den Arbeitsspeicher in Seiten (Pages). Auf den meisten Systemen ist eine Seite 4 KB groß. Raspberry Pi OS startet auf dem Pi 5 standardmäßig den Kernel kernel_2712.img, der auf den Pi 5 optimiert ist und 16-KB-Seiten nutzt. Manche Programme kommen damit nicht klar, deshalb liefert Raspberry Pi OS zusätzlich einen 4K-Kernel mit. Den aktivierst du bei Bedarf mit kernel=kernel8.img in /boot/firmware/config.txt.

Weil im Container eine ältere MongoDB 3.6 steckt, hatte ich genau hier Bedenken. Die waren unbegründet: Der UniFi OS Server läuft bei mir mit dem 16K-Kernel ohne Änderungen. Welcher Kernel bei dir aktiv ist, siehst du so:

# Auf dem Pi per SSH: Seitengröße prüfen (16384 = 16K-Kernel, 4096 = 4K-Kernel)
getconf PAGESIZE

Bei mir liefert der Befehl auf dem Host und im Container 16384, und das MongoDB-Log ist frei von Fehlern. Langzeitwerte habe ich noch keine. Sollte sich daran etwas ändern, ergänze ich es hier.

Vorbereitung: Mindestanforderungen, Backup und Inventur

Ubiquiti nennt für Linux konkrete Mindestanforderungen. Eine davon erfüllt der Pi nicht: Offiziell verlangt Ubiquiti einen x86-64-Prozessor. Es gibt aber einen offiziellen Installer für Linux ARM64, und der läuft auf dem Pi 5.

Für kleine Installationen bis 25 Geräte empfiehlt Ubiquiti 2 Kerne, 2 GB RAM, 2 GB Swap und 50 GB Speicher. Podman 5.4.2 und slirp4netns 1.2.1 kommen bei Trixie direkt aus den Paketquellen.

Vor dem Umzug habe ich vier Dinge erledigt:

1. Backup herunterladen. Laut Ubiquiti-Anleitung findest du das .unf-Backup im alten Network Server unter Settings > Control Plane > Backups. Lade es herunter und auf einem anderen Rechner speichern.
2. SSH-Zugangsdaten der Geräte notieren. Ubiquiti empfiehlt, sie vorher unter Devices > Device Updates & Settings > Device SSH Settings zu kopieren. Falls sich ein Gerät später nicht von allein verbindet, brauchst du sie für set-inform.
3. Alte Autobackups wegkopieren. Die Dateien aus /var/lib/unifi/backup/autobackup/ kommen beim Restore nicht mit. Wer sie behalten will, kopiert sie vorher weg.
4. Inventur der API-Nutzer. Alles, was auf die alte API zugreift, funktioniert nach dem Umzug nicht mehr. Dazu gehören eigene Skripte, Exporter, Monitoring und Integrationen.

Für die Inventur reicht oft eine Suche nach dem alten Port und den alten Pfaden. Führe die Suche auf jedem Rechner aus, auf dem Skripte oder Monitoring auf UniFi zugreifen, nicht nur auf dem Pi. Die Pfade passt du an deine Umgebung an:

# Auf jedem Rechner mit UniFi-Skripten oder Monitoring: Skripte und Cronjobs nach Zugriffen auf die alte UniFi-API durchsuchen
grep -rnE --exclude-dir=node_modules --exclude-dir=.cache ':8443|/api/login|/api/s/' ~/ /etc/cron* /opt 2>/dev/null
crontab -l | grep -iE 'unifi|8443'

/api/login kommt auch in anderen Web-Anwendungen vor, schau dir die Treffer deshalb kurz an. Jeder Treffer, der zu UniFi gehört, ist eine Datei oder ein Cronjob, den du nach dem Umzug anpassen musst. Schreib dir die Liste auf und arbeite sie nach dem Restore ab. Was genau sich ändert (Port, Login, API-Pfade, Benutzer), steht im Abschnitt Skripte und Monitoring auf die neue API umstellen. Ohne Treffer greift auf diesem Rechner nichts auf die alte API zu.

Plane außerdem, dass der Pi seine IP-Adresse behält. Dann melden sich die Geräte später ohne Umweg beim neuen Server.

UniFi OS Server auf dem Raspberry Pi 5 installieren

Die Installation besteht aus fünf Schritten im Terminal. Den größten Teil der Einrichtung übernimmt der Installer selbst. Alle Befehle in diesem Abschnitt führst du per SSH auf dem Pi aus, auf dem der Network Server läuft.

Schritt 1: Podman installieren

# Auf dem Pi per SSH: Podman und Netzwerk-Hilfen installieren
sudo apt-get update
sudo apt-get install -y podman slirp4netns uidmap

Ubiquiti nennt in der Anleitung podman und slirp4netns. Das Paket uidmap liefert die Werkzeuge, die Container ohne Root-Rechte brauchen. Bei mir kamen 24 neue Pakete dazu, darunter podman, netavark, aardvark-dns, passt und fuse-overlayfs. Entfernt oder aktualisiert wurde nichts, Docker blieb unberührt.

Schritt 2: Den alten Network Server stoppen

Ubiquiti schreibt ausdrücklich, dass der Network Server vor der Installation beendet sein muss. Hier lag mein erster Stolperstein: systemctl stop unifi beendet die eingebettete MongoDB nicht. Sie lief bei mir einfach weiter.

# Auf dem Pi per SSH: alten Network Server stoppen und Autostart abschalten
sudo systemctl stop unifi
sudo systemctl disable unifi

# Läuft die eingebettete MongoDB noch?
pgrep -u unifi -a mongod

Taucht hier ein mongod-Prozess auf, beendest du ihn sauber mit SIGTERM:

# Auf dem Pi per SSH: MongoDB sauber beenden, PID aus der Ausgabe oben einsetzen
sudo kill -TERM MONGOD_PID

# Muss jetzt leer sein
pgrep -u unifi

Ob die MongoDB sauber beendet wurde, siehst du im Log. Die letzte Zeile mit Now exiting muss einen Zeitstempel von gerade eben tragen:

# Auf dem Pi per SSH: prüfen, ob die MongoDB sauber beendet wurde
sudo grep "Now exiting" /usr/lib/unifi/logs/mongod.log | tail -1

Das ist auch der richtige Moment für ein Kalt-Backup des Datenverzeichnisses. Mein erstes tar lief noch mit laufender MongoDB und war damit nur eine Heißkopie, auf die ich mich nicht verlassen würde. Mit gestoppter Datenbank sieht das so aus:

# Auf dem Pi per SSH: Kalt-Backup des alten Datenverzeichnisses anlegen und prüfen
sudo tar -C /var/lib -czf unifi-kalt-backup.tar.gz unifi
tar -tzf unifi-kalt-backup.tar.gz > /dev/null && echo "Archiv OK"

Die zweite Zeile liest das komplette Archiv einmal durch. Steht danach Archiv OK da, ist es vollständig lesbar. Kopiere es dann auf einen anderen Rechner oder ein NAS. Es enthält die alte Datenbank mit den Passwort-Hashes der alten Admins, lass es also nicht offen herumliegen.

Schritt 3: Ports prüfen

Der UniFi OS Server braucht eine Reihe von Ports auf dem Host. Die Liste stammt aus der portmap.json im Installer:

# Auf dem Pi per SSH: prüfen, ob die benötigten Ports frei sind
sudo ss -tulpn | grep -E ':(3478|5514|5671|6789|8080|8444|888[0-2]|9543|10003|11084|11443|28082)\b'

Keine Ausgabe heißt: alles frei. Port 8443 taucht in der Liste nicht mehr auf, die Weboberfläche zieht auf 11443 um. Der Installer prüft die Ports zwar auch selbst, ich wollte Konflikte mit meinen Docker-Containern aber vorher sehen.

Schritt 4: Installer laden und prüfen

Den Installer lädst du direkt vom Update-Server von Ubiquiti, so habe ich es auch gemacht. Der folgende Block fragt dort den Download-Link und die SHA256-Prüfsumme der aktuellen ARM64-Version ab, lädt den Installer herunter und prüft ihn. Du kannst ihn komplett kopieren und einfügen, anpassen musst du nichts:

# Auf dem Pi per SSH: Link und Prüfsumme der aktuellen ARM64-Version abfragen
API="https://fw-update.ui.com/api/firmware-latest?filter=eq~~product~~unifi-os-server&filter=eq~~channel~~release&filter=eq~~platform~~linux-arm64"
URL=$(curl -s "$API" | python3 -c 'import json,sys; print(json.load(sys.stdin)["_embedded"]["firmware"][0]["_links"]["data"]["href"])')
SHA=$(curl -s "$API" | python3 -c 'import json,sys; print(json.load(sys.stdin)["_embedded"]["firmware"][0]["sha256_checksum"])')
echo "$URL"

# Installer herunterladen (rund 770 MB) und als uos-installer speichern
curl -fL -o uos-installer "$URL"

# Prüfsumme vergleichen: muss "uos-installer: OK" ausgeben
echo "$SHA  uos-installer" | sha256sum -c -

# Installer ausführbar machen
chmod +x uos-installer

Die Zeile mit echo "$URL" zeigt dir den Download-Link, darin steht auch die Versionsnummer (bei mir 5.1.42). Meldet sha256sum statt OK ein FAILED, ist die Datei beschädigt. Dann lösche sie und lade sie neu.

Schritt 5: Installer ausführen

# Auf dem Pi per SSH: Installer ohne Rückfragen starten, Weboberfläche auf Port 11443
sudo ./uos-installer --non-interactive --web-port 11443

Ohne --non-interactive fragt der Installer vor dem Start noch einmal nach. Ich habe den Port ausdrücklich auf 11443 gesetzt, den nennen auch andere Berichte als Standard. Mit --web-port kannst du einen anderen Port zwischen 1024 und 65535 wählen. Auf meinem Pi 5 dauerte die Installation 1:40 Minuten, nach etwa einer weiteren Minute meldete der Container healthy. Die Ausgabe sieht gekürzt so aus:

Checking ports...
Adding uosserver user and group...
Adding user 'DEIN_USER' to 'uosserver' group...
Initializing podman conf...
Allowing raw socket execution...
Creating systemd services...
Loading container image...
Starting container...
Starting uosserver systemd service...
!!! INSTALLATION COMPLETE !!!
UniFi OS Server is running at: https://PI_IP:11443/

Der Installer legt den Benutzer uosserver an und nimmt deinen eigenen Benutzer in dessen Gruppe auf. Er richtet die Podman-Konfiguration und linger ein, erlaubt per sysctl Raw-Sockets und erstellt die systemd-Dienste uosserver.service und uosserver-updater.service. Steuern lässt sich der Server laut Ubiquiti mit den bekannten Befehlen:

# Auf dem Pi per SSH: UniFi OS Server stoppen, starten, Autostart an- oder abschalten
sudo systemctl stop uosserver
sudo systemctl start uosserver
sudo systemctl enable uosserver
sudo systemctl disable uosserver

Einrichtung im Browser: erst updaten, dann restoren

Die Oberfläche erreichst du jetzt unter https://PI_IP:11443. Die Zertifikatswarnung des Browsers kannst du ignorieren. Ein eigenes Zertifikat kannst du laut Ubiquiti später unter Settings > Control Plane > Console > Certificates hinterlegen.

Den Restore-Link im Setup überspringen

Gleich auf der ersten Seite des Setups steht unten links “Restore From Backup”. Den habe ich bewusst nicht genommen.

Der Grund steckt im Installer. Der UniFi OS Server 5.1.42 bringt Network 10.5.67 mit. Mein Network Server lief zu dem Zeitpunkt schon auf 10.6.109, das Backup war also neuer als die Network-App im neuen Server. Ubiquiti nennt in der Migrations-Anleitung als ersten Schritt ohnehin, die neue Network-App auf den aktuellen Stand zu bringen.

⚠️ Wichtig: Vergleiche vor dem Restore die Network-Version deines Backups mit der Version im neuen Server. Ist das Backup neuer, schließe das Setup erst ohne Restore ab und aktualisiere die Network-App.

Mit oder ohne UI-Konto

Danach fragt das Setup nach einem UI-Konto. Wenn du eins anlegst, achte auf den Newsletter-Haken, der ist vorausgewählt. Ich habe unten links “Proceed Without a UI Account” gewählt. Der folgende Dialog “Skip Account Setup?” listet auf, was dir ohne Konto fehlt:

• Fernzugriff (Remote Management)
• Multi-Faktor-Authentifizierung
• Push-Benachrichtigungen
• Cloud-Backups
• Teleport und Site Magic VPN

Mit “Continue Anyway” geht es weiter, danach legst du einen lokalen Admin als Owner an. Weil ohne Konto keine Multi-Faktor-Authentifizierung möglich ist, sollte die Oberfläche nur aus dem eigenen Netz erreichbar sein.

Network-App aktualisieren

Nach dem Setup landest du in einer leeren Network-App, unten links steht die Version 10.5.67. Unter Settings > Control Plane > Updates zeigt der Server bei der Network-App direkt “Update to 10.6.109” an.

Das Update dauerte keine Minute. Der UniFi OS Server lädt die Network-App als eigenes Paket nach. Wie alt die Version im Installer ist, spielt deshalb keine große Rolle. Der Pi braucht dafür allerdings Internetzugang.

Backup einspielen

Jetzt passt die Version, und das Backup kann rein. Unter Settings > Control Plane > Backups klickst du auf “Upload & Restore” und wählst die .unf-Datei aus. Der Dialog warnt, dass alle aktuellen Daten durch das Backup ersetzt werden. Bei einer frischen Installation ist das egal.

Nach rund einer Minute stand im Log Backup restored successfully. Restarting the server to apply changes. Danach startet die Network-App neu, bis ich wieder arbeiten konnte, vergingen zwei bis drei Minuten. Der lokale Owner aus dem Setup bleibt erhalten. Gateway und Switch waren rund 1:45 Minuten nach dem Restore wieder online, der Access Point nach 2:45 Minuten. Neu adoptieren musste ich nichts.

Das lag daran, dass die IP-Adresse des Pi gleich geblieben ist. Wenn du auf einen anderen Rechner oder eine neue IP umziehst, setzt du laut Ubiquiti im alten Network Server “Override Inform Host” auf die neue Adresse. Alternativ stellst du die Geräte per SSH um:

# Auf dem UniFi-Gerät per SSH: neuen Controller eintragen
set-inform http://NEUE_PI_IP:8080/inform

Erscheint ein Gerät danach als “Managed by Another Console”, bleibt laut Ubiquiti nur der Reset und eine neue Adoption.

Ubiquiti beschreibt für Linux außerdem einen Umzug über das Site-Export-Tool. Bei meiner einzelnen Site hat der normale Restore gereicht.

Direkt nach dem Restore zeigte mir die neue Oberfläche ein Firmware-Update für das Gateway an, laut Beschreibung unter anderem mit zurückgezogenen Zertifikaten der Zertifizierungsstelle eMudhra. Die alte Oberfläche hatte mir das nicht angezeigt, obwohl das Update in ihrem Log schon auftauchte. Schau nach dem Umzug also auch in die Updates.

Admins und Benutzer neu anlegen

Nach dem Restore wollte sich mein Readonly-User für das Monitoring anmelden und scheiterte. Die API antwortete mit 403 und AUTHENTICATION_FAILED_INVALID_CREDENTIALS. Die alten Network-Admins stehen zwar nach dem Restore wieder in der Datenbank der Network-App, anmelden können sie sich aber nicht. Das passt dazu, dass unter UniFi OS das Betriebssystem die Logins verwaltet. Alle Admins musst du deshalb neu anlegen, auch reine Lese-Zugänge.

Wo die Admins jetzt stecken

Unter Settings > System suchst du vergeblich. Laut Ubiquiti-Anleitung findest du die Admins in der Network-App über die linke Navigationsleiste. Gemeint ist das Personen-Symbol ganz unten. Dort klickst du auf “Create New”.

Readonly-User für Skripte anlegen

Für Skripte und Monitoring reicht ein Benutzer mit Leserechten. So legst du ihn an:

1. “Create New” und dann “Create New User” wählen.
2. Den Haken bei “Admin” setzen. Ohne den Haken entsteht nur ein Identity-User ohne Login.
3. “Restrict to Local Access Only” ist ohne UI-Konto automatisch gesetzt.
4. Benutzername und Passwort eintragen.
5. “Use a Predefined Role” abwählen. Als vorgefertigte Rolle gibt es nur Super Admin.
6. Bei Network “View Only” wählen, bei der Benutzerverwaltung “None”.
7. Mit “Create” speichern.

Wenn du denselben Benutzernamen und dasselbe Passwort wie beim alten Readonly-User nimmst, musst du in deinen Skripten nur URL, Pfade und bei POST-Anfragen den CSRF-Header anpassen. Mein WAN-IP-Skript lief vorher übrigens mit dem Haupt-Admin. Jetzt nutzt es den Readonly-User, denn es liest nur die WAN-IP aus. Skripte sollten grundsätzlich nicht mit Admin-Rechten laufen.

Skripte und Monitoring auf die neue API umstellen

Direkt nach dem Umzug scheiterte mein Skript zur Erkennung einer neuen WAN-IP schon beim Verbindungsaufbau, weil es Port 8443 nicht mehr gibt. Der Fehler sah so aus:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='PI_IP', port=8443): Max retries exceeded with url: /api/login

Mein Grafana-Exporter lieferte ebenfalls keine Daten mehr, bis ich ihn umgestellt hatte. Die Unterschiede zur alten API sind überschaubar:

Das Präfix /proxy/network gilt auch für die neueren v2-Pfade, etwa /proxy/network/v2/api/site/default/....

Reine GET-Anfragen funktionieren ohne CSRF-Header. Manche Abfragen der UniFi-API laufen aber per POST, obwohl sie nur Daten lesen, zum Beispiel Berichte unter stat/report. Ohne Header antwortet der Server darauf mit 403 Forbidden, auch beim Readonly-User. Das Token liefert der Login im Antwort-Header X-CSRF-Token. Es steckt außerdem im JWT des Cookies TOKEN, im Feld csrfToken.

Ein minimales Python-Beispiel mit requests sieht so aus. Es läuft auf jedem Rechner, der den Pi im Netz erreicht:

# Auf jedem Rechner, der den Pi im Netz erreicht (Python 3 mit requests)
import requests

BASIS = "https://PI_IP:11443"
s = requests.Session()
s.verify = False  # selbstsigniertes Zertifikat, besser: eigenes Zertifikat hinterlegen

# Anmelden: neuer Pfad unter UniFi OS
r = s.post(f"{BASIS}/api/auth/login", json={"username": "API_USER", "password": "API_PASSWORT"})
r.raise_for_status()

# CSRF-Token für spätere POST-Anfragen merken
s.headers["X-CSRF-Token"] = r.headers["X-CSRF-Token"]

# Network-Daten: alter Pfad mit dem Präfix /proxy/network
health = s.get(f"{BASIS}/proxy/network/api/s/default/stat/health").json()

# WAN-Eintrag über den Namen suchen, nicht über die Position in der Liste
wan = next(x for x in health["data"] if x["subsystem"] == "wan")
print(wan.get("wan_ip"))

# Abmelden: unter UniFi OS per POST mit CSRF-Header
s.post(f"{BASIS}/api/auth/logout")

Den WAN-Eintrag suche ich hier bewusst über subsystem == "wan". Das Skript aus meinem alten Artikel griff noch auf eine feste Position in der Liste zu (data["data"][1]). Die Reihenfolge hat sich bei mir zwar nicht geändert, verlassen würde ich mich darauf aber nicht.

Tools wie unpoller brauchen nach dem Umzug mindestens die neue URL mit Port 11443 und einen neu angelegten Benutzer. Mit unpoller selbst habe ich das nicht getestet.

💡 Tipp: Prüfe nach dem Umzug alle eigenen Skripte, Cronjobs, Monitoring-Checks und deine Notfall-Dokumentation auf Bezüge zu UniFi: Port 8443, /api/login, /api/s/ und alte Backup-Pfade. Denk dabei auch an selten genutzte Test- und Hilfsskripte. Die laufen nicht im Cron, sind nach dem Umzug aber genauso kaputt.

Backups, Rollback und Aufräumen

Wo die Backups jetzt liegen

Die Daten des UniFi OS Servers liegen in Podman-Volumes unter dem Home-Verzeichnis von uosserver. Das Prinzip kennst du vielleicht von Docker-Volumes. Die Liste der Volumes bekommst du so:

# Auf dem Pi per SSH: Volumes des UniFi OS Servers auflisten
sudo -u uosserver XDG_RUNTIME_DIR=/run/user/$(id -u uosserver) podman volume ls

Die Autobackups der Network-App landen künftig in diesem Verzeichnis:

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

Das alte /var/lib/unifi/backup wird nicht mehr beschrieben, und das neue Verzeichnis ist nach dem Restore leer, denn der Restore übernimmt nur die Einstellungen.

⚠️ Wichtig: Wer seine UniFi-Backups per rsync --delete auf ein NAS spiegelt und nur den Quellpfad auf das neue, leere Verzeichnis umstellt, löscht beim nächsten Lauf sein komplettes altes Backup-Archiv auf dem NAS. Lege für den UniFi OS Server ein neues Zielverzeichnis an und lass das alte Archiv in Ruhe.

Noch offen ist bei mir der Zeitplan der Autobackups. Laut Datenbank ist er nach dem Restore aktiv und steht auf wöchentlich. In der Oberfläche finde ich die Einstellung aber nicht mehr. Die Suche in den Network-Einstellungen findet nichts, und unter Control Plane > Backups gibt es nur Download sowie Upload & Restore der System-Backups. Ob der Zeitplan trotzdem läuft, sehe ich erst nach dem nächsten geplanten Termin. Ich ergänze das Ergebnis hier. Bis dahin würde ich mich nicht auf die Autobackups verlassen und zusätzlich manuell ein Backup unter Control Plane > Backups herunterladen.

Rollback, falls etwas schiefgeht

Der alte Network Server ist bei mir nur gestoppt und deaktiviert. Pakete, MongoDB-Paketquelle und /var/lib/unifi sind unverändert. Zurück ginge es so:

# Auf dem Pi per SSH: zurück zum alten Network Server
sudo systemctl stop uosserver
sudo systemctl disable uosserver

# Ports müssen frei sein: keine Ausgabe, erst dann weiter
sudo ss -tulpn | grep -E ':(8080|11443)\b'

sudo systemctl enable --now unifi

Zeigt die Port-Prüfung noch einen Treffer, wartest du ein paar Sekunden und führst sie erneut aus. Da die IP-Adresse gleich bleibt, sollten sich die Geräte danach wieder beim alten Server melden. Änderungen, die du in der Zwischenzeit im UniFi OS Server gemacht hast, wären dann allerdings weg.

Aufräumen nach einer Woche

Läuft der UniFi OS Server rund eine Woche stabil, kannst du den alten Network Server entfernen. Bis dahin bleibt er als Rückfallebene liegen. Eine weitere Sicherung brauchst du dafür nicht, solange das Kalt-Backup aus Schritt 2 auf einem anderen Rechner oder NAS liegt. Es enthält das alte Datenverzeichnis, und daran hat sich seit dem Stoppen nichts mehr geändert.

Zuerst schaust du, welche Pakete der alte Server mitgebracht hat:

# Auf dem Pi per SSH: installierte UniFi-, MongoDB- und Java-Pakete anzeigen
dpkg -l | grep -E 'unifi|mongodb|openjdk'

Bei mir waren das unifi, mehrere mongodb-org-Pakete und Java (openjdk-25-jre-headless). MongoDB und Java können auf deinem Pi aber auch von anderen Projekten genutzt werden. Bevor du sie entfernst, prüfst du das:

# Auf dem Pi per SSH: nutzt außer UniFi noch etwas MongoDB oder Java?
systemctl is-active mongod
sudo ss -tlnp | grep ':27017\b'
ps -eo user:20,cmd | grep -E '[j]ava|[m]ongod' | grep -vE '^[0-9]+ '

Die erste Zeile sollte inactive melden, die zweite und dritte nichts ausgeben. Der alte Server ist ja gestoppt. Der neue UniFi OS Server bringt zwar ebenfalls MongoDB und Java mit, seine Prozesse laufen aber im Container und erscheinen in ps mit einer Nummer statt eines Benutzernamens. Die filtert der letzte Teil der dritten Zeile heraus. Zeigt sie trotzdem einen Prozess an, gehört er zu einem anderen Projekt.

Achtung: apt purge unifi löscht auch das alte Datenverzeichnis /var/lib/unifi und die alten Logs. Prüfe vorher, dass dein Kalt-Backup aus Schritt 2 auf einem anderen Rechner oder NAS liegt.

Entferne MongoDB und Java natürlich nur, wenn du sie nicht noch woanders benutzt. Im Zweifel entfernst du nur unifi und lässt den Rest stehen. Nimm die Paketnamen aus deiner dpkg-Ausgabe:

# Auf dem Pi per SSH: alten Network Server und MongoDB entfernen
sudo apt purge unifi mongodb-org-server mongodb-org-shell mongodb-org-tools mongodb-org-database-tools-extra mongodb-database-tools

Java hat der Network Server mitgebracht. Ob noch ein installiertes Paket darauf angewiesen ist, zeigt diese Abfrage. Java-Programme, die du selbst von Hand oder als eigenen Dienst startest, erkennt sie nicht, die musst du selbst kennen. Setze die Java-Version aus deiner dpkg-Ausgabe ein:

# Auf dem Pi per SSH: prüfen, welche installierten Pakete Java noch brauchen
apt-cache rdepends --installed openjdk-25-jre-headless

Steht unter Reverse Depends: nichts mehr und nutzt du Java nicht selbst, entfernst du Java und räumst danach die übrig gebliebenen Abhängigkeiten ab. Steht dort noch ein Paket oder brauchst du Java selbst, lässt du es stehen und überspringst die erste Zeile:

# Auf dem Pi per SSH: Java entfernen und nicht mehr benötigte Pakete abräumen
sudo apt purge openjdk-25-jre-headless
sudo apt-get -s autoremove --purge

Die letzte Zeile ist nur eine Simulation. Sie zeigt, was autoremove entfernen würde. Bei mir standen dort neben den UniFi-Resten auch alte Kernel-Pakete. Das ist harmlos, solange du den aktuellen Kernel nutzt (uname -r). Passt die Liste, startest du den echten Lauf:

# Auf dem Pi per SSH: nicht mehr benötigte Pakete wirklich entfernen
sudo apt autoremove --purge

Jetzt fehlen noch die Paketquellen von UniFi und MongoDB und ihre Schlüssel. Die erste Zeile zeigt dir die Dateien der Paketquellen, die zweite die Schlüssel:

# Auf dem Pi per SSH: Paketquellen und Schlüssel von UniFi und MongoDB finden
grep -lE 'ubnt|ui\.com|mongodb' /etc/apt/sources.list.d/*
ls /etc/apt/keyrings/* /etc/apt/trusted.gpg.d/* | grep -iE 'unifi|ubnt|mongo'

Diese Dateien und Schlüssel löschst du. Hast du MongoDB oben stehen lassen, bleiben auch deren Paketquelle und Schlüssel. Bei mir hießen sie so, bei dir können die Namen abweichen:

# Auf dem Pi per SSH: Paketquellen und Schlüssel löschen, danach apt prüfen
sudo rm /etc/apt/sources.list.d/100-ubnt-unifi.list /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo rm /etc/apt/keyrings/unifi-repo.gpg /etc/apt/trusted.gpg.d/unifi-repo.gpg /etc/apt/keyrings/mongodb-server-7.0.gpg
sudo apt update

apt update muss ohne Fehler durchlaufen. Das alte Datenverzeichnis hat apt purge unifi schon gelöscht. Ob noch etwas übrig ist, siehst du so:

# Auf dem Pi per SSH: prüfen, ob vom alten Datenverzeichnis noch etwas da ist
ls -d /var/lib/unifi /usr/lib/unifi

Meldet ls für beide “No such file or directory”, ist alles weg. Sonst löschst du die Reste mit sudo rm -rf und dem angezeigten Pfad.

Zur Kontrolle meldet der erste Befehl, dass der Dienst unifi nicht mehr gefunden wird. Der zweite gibt nichts aus, weil die alten Ports 8443 und 27117 frei sind. Beim dritten steht der UniFi OS Server weiter auf (healthy):

# Auf dem Pi per SSH: prüfen, dass der alte Server weg ist und der neue läuft
systemctl status unifi
sudo ss -tlnp | grep -E ':(8443|27117)\b'
sudo -u uosserver XDG_RUNTIME_DIR=/run/user/$(id -u uosserver) podman ps

Mein Stand nach der Migration

So sieht mein Setup nach dem Umzug aus:

Der Container braucht damit etwa so viel RAM wie der alte Network Server, obwohl PostgreSQL, RabbitMQ und unifi-core mitlaufen. Ein Pi mit 4 GB sollte reichen, wenn darauf nicht viel anderes läuft. Mit 2 GB wird es eng, auch wenn Ubiquiti 2 GB als Minimum nennt.

podman stats --no-stream zeigte mir direkt nach dem Start 92 Prozent CPU, eine halbe Minute später 77 Prozent. Laut top lag die tatsächliche Last zu dem Zeitpunkt bei rund 8 Prozent eines Kerns. Für die aktuelle Last nutze ich deshalb top.

Die Zeiten aus meinem Umzug zur Orientierung:

Netz und WLAN liefen die ganze Zeit weiter. Die Geräte arbeiten ohne Controller mit ihrer letzten Konfiguration, nur Änderungen und Statistiken pausieren.

Die Stolpersteine im Überblick

Der Umzug selbst war nach rund 17 Minuten erledigt. Diese Punkte würde ich mir beim nächsten Mal vorher anschauen:

1. Die Network-Version im Installer kann älter sein als dein Backup. Erst die Network-App aktualisieren, dann restoren.
2. systemctl stop unifi beendet die eingebettete MongoDB nicht. Prozess prüfen und per SIGTERM beenden.
3. Die alten Admins funktionieren nicht mehr. Neu anlegen, das Menü liegt hinter dem Personen-Symbol in der Network-App.
4. Port 8443 ist weg. Jedes Skript, das die alte API nutzt, ist sofort kaputt.
5. Alte Autobackups kommen nicht mit, der Backup-Pfad ändert sich. Vorsicht mit rsync --delete.
6. Der Zeitplan der Autobackups ist in der Oberfläche nicht zu finden. Bis zur Klärung manuell sichern.
7. Ohne UI-Konto gibt es keine Multi-Faktor-Authentifizierung. Die Oberfläche gehört dann nur ins eigene Netz.

Wie viel Arbeit der Umzug macht, hängt vor allem an deinen eigenen Skripten. Wer nur die Oberfläche nutzt, ist mit dem Umzug und einem neuen Admin weitgehend durch. Wer wie ich Monitoring und Skripte an der API hängen hat, sollte sich für die Nacharbeiten zusätzlich Zeit nehmen.