UniFi OS Server installieren – Proxmox LXC Debian 13 – Tutorial

UniFi OS Server installieren – Proxmox LXC Tutorial

In diesem Tutorial erkläre ich Ihnen, wie Sie UniFi OS Server installieren, und zwar in einem Proxmox LXC Container mit Debian 13. UniFi OS Server ist der offizielle Nachfolger des bisherigen UniFi Network Servers (früher «UniFi Controller») und bietet dieselbe Oberfläche wie eine Cloud Key oder ein Cloud Gateway. Die Software ist kostenlos und läuft bei Ihnen zu Hause, ganz ohne Ubiquiti-Hardware.

Falls Sie noch den alten Controller verwenden: Die Anleitungen Proxmox Unifi Controller installieren und Unifi Controller installieren Version 7 beschreiben noch die bisherige Variante.

  • Getestet im November 2026 mit UniFi OS Server 5.1.42 und Debian 13 in einem Proxmox LXC Container.
  • UniFi OS Server läuft nur in einem privilegierten Container. In einem unprivilegierten Container bricht die Installation ab (siehe «Häufige Fehler»). Ein privilegierter Container ist weniger stark vom Proxmox-Host abgeschottet. Wer das nicht möchte, verwendet eine Debian 13 VM. Die Schritte ab Punkt 3 sind dort gleich.
  • Ubiquiti empfiehlt für bis zu 25 Geräte: 2 Kerne, 2 GB RAM, 2 GB Swap und 50 GB Speicher. Ich empfehle 4 GB RAM, im Test belegte UniFi OS Server direkt nach dem Start bereits rund 1,3 GB.

1. LXC Container erstellen

Erstellen Sie in Proxmox über «Create CT» einen neuen Container. Wie das genau geht, zeigt das Tutorial Proxmox Container installieren – LXC in 10 Schritten. Wichtig sind folgende Einstellungen:

  • Unprivileged container: nicht anhaken
  • Nesting: aktivieren (unter «Features»)
  • Template: Debian 13
  • Ressourcen: 2 Kerne, 4096 MB RAM, 2048 MB Swap, 50 GB Speicher

2. TUN-Gerät freigeben

UniFi OS Server benötigt für sein Netzwerk das Gerät /dev/net/tun. Führen Sie dazu folgenden Befehl auf dem Proxmox-Host aus. Ersetzen Sie 100 durch die ID Ihres Containers.

pct set 100 --dev0 /dev/net/tun

Starten Sie den Container danach neu, damit das Gerät verfügbar ist.

pct reboot 100

3. Updates und Podman installieren

Melden Sie sich nun per SSH oder über die Konsole am Container an. UniFi OS Server läuft selbst in einem Container und benötigt dafür Podman. Aktualisieren Sie zuerst das System.

apt update && apt upgrade -y

Installieren Sie anschliessend Podman und slirp4netns.

apt install podman slirp4netns -y

4. UniFi OS Server herunterladen

Den aktuellen Download-Link finden Sie auf der Download-Seite von Ubiquiti unter «UniFi OS Server». Wählen Sie die Linux-Version für x64 und kopieren Sie den Link mit Rechtsklick → «Link-Adresse kopieren». Für Version 5.1.42 lautet der Befehl:

wget https://fw-download.ubnt.com/data/unifi-os-server/5172-linux-x64-5.1.42-12e9e3cf-8f8b-4e54-928c-76b80a10c8a4.42-x64

Optional können Sie prüfen, ob die Datei vollständig heruntergeladen wurde. Die SHA256-Prüfsumme von Version 5.1.42 lautet f6111e9396a42c74016f5dde9b01fbef486a6fe69efe137935e6e38b7c22f94d.

sha256sum 5172-linux-x64-5.1.42-12e9e3cf-8f8b-4e54-928c-76b80a10c8a4.42-x64

5. UniFi OS Server installieren

Machen Sie die Datei ausführbar.

chmod +x 5172-linux-x64-5.1.42-12e9e3cf-8f8b-4e54-928c-76b80a10c8a4.42-x64

Starten Sie dann die Installation und bestätigen Sie die Frage «Proceed? (y/N)» mit y. Die Installation dauert einige Minuten.

./5172-linux-x64-5.1.42-12e9e3cf-8f8b-4e54-928c-76b80a10c8a4.42-x64

Am Ende erscheint «INSTALLATION COMPLETE» zusammen mit der Adresse der Weboberfläche.

UniFi OS Server installieren – Installation abgeschlossen

6. Status überprüfen

Mit folgendem Befehl sehen Sie, ob UniFi OS Server läuft. In der Spalte STATUS sollte «healthy» stehen.

uosserver status
UniFi OS Server installieren – uosserver status healthy

UniFi OS Server startet nach einem Neustart des Containers automatisch. Mit systemctl können Sie den Dienst auch manuell stoppen und starten.

systemctl restart uosserver

7. Weboberfläche einrichten

Öffnen Sie im Browser die Adresse aus der Installation, zum Beispiel https://192.168.1.50:11443. Der Browser warnt beim ersten Aufruf vor dem Zertifikat. Das ist normal, da UniFi OS Server ein selbst signiertes Zertifikat verwendet. Danach führt Sie ein Assistent durch die Einrichtung. Sie können sich mit einem UI-Konto anmelden, um den Server auch über unifi.ui.com zu verwalten.

UOS Server

Damit sich Access Points und Switches mit dem Server verbinden können, müssen die benötigten Ports erreichbar sein, unter anderem TCP 8080 und UDP 3478.

Umzug vom UniFi Network Server

Wenn Sie bisher den UniFi Network Server verwenden, erstellen Sie dort zuerst ein Backup und fahren den alten Server herunter. Laut Ubiquiti erfolgt der Umzug unter Linux über das Site-Export-Tool des alten Servers. Die Anleitung dazu finden Sie im Hilfe-Center von Ubiquiti. Das Captive Portal ist bei UniFi OS Server neu über Port 8444 statt 8843 erreichbar.

Häufige Fehler

Insufficient disk space for install

Die Installation prüft den freien Speicherplatz und verlangt allein für /home 15 GB. Mit einem 16-GB-Container bricht sie deshalb ab. Vergrössern Sie den Container auf dem Proxmox-Host, zum Beispiel auf 50 GB:

pct resize 100 rootfs 50G

sysctl: setting key «net.ipv4.ping_group_range»: Invalid argument

Diese Meldung erscheint in einem unprivilegierten Container. Die Installation setzt net.ipv4.ping_group_range auf «0 2147483647», ein unprivilegierter Container kennt aber nur die Gruppen-IDs 0 bis 65535. Erstellen Sie einen privilegierten Container (Schritt 1) oder verwenden Sie eine VM.

pasta failed: Failed to open() /dev/net/tun

Dem Container fehlt das TUN-Gerät. Führen Sie Schritt 2 aus, starten Sie den Container neu und wiederholen Sie die Installation.

Version matches the installed version. Use –force-install to override.

Ist eine frühere Installation abgebrochen, verweigert der Installer einen zweiten Versuch mit derselben Version. Starten Sie ihn in diesem Fall mit –force-install.

./5172-linux-x64-5.1.42-12e9e3cf-8f8b-4e54-928c-76b80a10c8a4.42-x64 --force-install

Warnung wegen fehlendem Swap

Hat der Container weniger als 2 GB Swap, gibt die Installation eine Warnung aus. Sie bricht deswegen nicht ab, Ubiquiti empfiehlt für einen stabilen Betrieb aber mindestens 2 GB. Den Swap können Sie auf dem Proxmox-Host anpassen:

pct set 100 --swap 2048

UniFi OS Server ist nun installiert und Sie können Ihre UniFi Geräte adoptieren.

Über ramhee 298 Artikel
Mein Name ist Ramon Heeb und das ist mein Technikmagazin. Ich liebe es Tutorials, Reviews und anderes zu schreiben und so anderen Menschen zu helfen. Ich bin seit einigen Jahren Technik-interessiert und habe technium.ch im Jahre 2019 gegründet.

Kommentar hinterlassen

Schreib einen Kommentar

Ihre E-Mail-Adresse wird nicht veröffentlicht.


*