Einleitung

Die UniFi Controller Management-Schnittstelle ermöglicht die Verwaltung von UniFi-Geräten und die Anzeige von Netzwerkstatistiken. Die Software wird häufig auf einem Windows- oder Mac-PC installiert, bietet aber keine solide Basis für einen dauerhaften Betrieb. Da FreeBSD Jails so schön schlank sind und FreeBSD auch von Ubiquiti unterstützt wird, bietet sich eine Installation dort an. Wenn wir es schon machen, dann richtig.

unifi1

Ziele

Ziel dieser Anleitung ist der Betrieb eines Unifi Controllers auf Basis von TrueNAS oder FreeBSD. Ohne Jail genügt ein pkg install unifi8 und das Thema ist durch. Um es aber noch perfekter zu machen, insbesondere was die Unabhängigkeit der Einstellungen von der Jail angeht, gehen wir hier nochmal genauer darauf ein.

NEU: Für ganz ungeduldige habe ich einen Konsole only Abschnitt. Da gibts nur Befehle, keine Erklärungen.

Letzte Aktualisierung:

  • 18.01.2026: Überarbeitung. Entfernung von TrueNAS und umschreiben auf reines FreeBSD. Jails mit Bastille.
  • 04.02.2024: Finale Version, kleinere Anpassungen
  • 23.01.2024: Initiale Version

Grundbedingungen

Generell sollten solche Dienste in einer eigenen Umgebung eingerichtet werden. Das macht nicht nur die Sicherheit, sondern auch die Wartung wesentlich einfacher. Jails können relativ einfach gesichert werden und es sind nur die Pakete installiert, die absolut notwendig sind.

Diagramm

Damit sieht das Setup lokal so aus:

                    ┌──────────────────────┐
                    │   FreeBSD            │
                    │ ┌──────────────────┐ │
                    │ │ jail/unifi       │ │
LAN: 0.0.0.0:8443 ──┼─┼─► unifi          │ │
                    │ └──────────────────┘ │
                    └──────────────────────┘

Jail erstellen

Es wird ein eigenes Jail benötigt. Hier nehmen wir unifi als Jail Namen und es wird auf jeden Fall die Option allow_sysvipc benötigt.

Unifi lässt sich exzellent aus einer Backup (unf-)Datei wiederherstellen.

Jail einrichten

Entweder mit bastile console unifi eine Konsole in das erstellte Jail starten, oder es erfolgt ein Login per SSH (wenn aktiviert) mit ssh USERNAME@IP oder ssh USERNAME@HOSTNAME, um dann mit su root Rechte zu erlangen.

Paketquelle anpassen

Paketquellen sollten angepasst werden, siehe separater Artikel.

Pakete installieren & Dienste aktivieren

Nun die Paketquelle mit pkg update aktualisieren und dann die benötigten Pakete mit pkg install -y unifi9 installieren.
Dienst mit service unifi enable aktivieren, damit dieser beim Start des Jails automatisch startet.

Unifi

Konfiguration erstellen

Hurra, es wird keine Konfiguration benötigt, beim ersten Start wird alles automatisch erstellt.

Dienste starten

Damit sind wir nun am Ende der Vorbereitungen angelangt und Unifi wird mit service unifi start gestartet.

Registrierung

Nun erfolgt der erste Aufruf von Unifi, in dem die Netzwerkeinrichtung erfolgt.
Hierzu mit dem Lieblingsbrowser nun die IP oder Hostname des Gitea Jails aufrufen:
https://IP:8443 oder http://HOSTNAME:8443

unifi

Backup

Backups werden automatisch einmal pro Woche von der UNIFI-Software durchgeführt.
Diese sind in dem Ordner /usr/local/share/java/unifi/data/backup gespeichert.

Konsole

Link zum Code aufGithub, ich freue mich immer über Verbesserungsvorschläge!

Voilá