Unifi unter TrueNAS installieren

English version here

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:

  • 04.02.2024: Finale Version, kleinere Anpassungen
  • 23.01.2024: Initiale Version

Voraussetzungen

  • TrueNAS Core oder reiner FreeBSD Server
    • Ein Jail (z.B. mit dem Namen unifi) ist eingerichtet
    • IP Adresse des UNIFI Jails ist bekannt (z.B. 192.168.178.104)
    • Hostname des UNIFI Jails ist bekannt (z.B. unifi.domain.local) und per internem DNS erreichbar

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:

                          ┌───────────────────────────────────────────┐
                          │ TrueNAS                                   │
                          │   192.168.1.100        Optional:          │
                          │ ┌──────────────────┐  ┌─────────────────┐ │
                          │ │ Jail: unifi      │  │ tank/jail_data  │ │
                          │ │ 192.168.178.104  │  │                 │ │
                          │ │                  │  │                 │ │
      LAN: 0.0.0.0:8443  ─┼─┼─► unifi  ────────┼──┼─► unifi/data    │ │
                          │ └──────────────────┘  └─────────────────┘ │
                          └───────────────────────────────────────────┘

Optional externe Datenverzeichnisse

Das Datenverzeichnis /usr/local/share/java/unifi/data kann in ein eigenes Dataset außerhalb des Jails abgelegt werden. Damit sind diese Daten unabhängig vom Jail gespeichert. Wenn das Jail aus irgendeinem Grund beschädigt oder gelöscht wurde, sind wir so in der Lage, die vorherige Konfiguration und Daten mit minimalem Aufwand wiederherzustellen. Auch werden die erzeugten Backups außerhalb des Jails gespeichert. Wie das (generisch) erreicht werden kann, habe ich hier beschrieben und kann mit den folgenden Informationen umgesetzt werden.

└── /mnt/tank/jails_data
    └── unifi
        └── data  # Ablage für die MongoDB Datenbank und Konfiguration (im Jail: /usr/local/share/java/unifi/data)
  • QUELLVERZEICHNIS = /mnt/tank/jails_data/unifi/data
  • ZIELVERZEICHNIS = /mnt/tank/iocage/jails/unifi/root/usr/local/share/java/unifi/data
  • Name des Unifi Benutzers = unifi
  • ID des Unifi Benutzers = 975

Dies ist eher für fortgeschrittenen Anwender gedacht, die schon etwas Erfahrung besitzen. Da im Detail drauf einzugehen, würde den Rahmen hier etwas sprengen. Das wichtigste ist aber: Es wird ein neues Verzeichniss (Dataset) benötigt, welches alles UNIFI relevante beinhaltet. Es spricht aber auch nichts dagegen es ohne dieses Schritt zu tun. Unifi lässt sich alternativ exzellent aus einer Backup (unf-)Datei wiederherstellen.

JAIL starten

Die Webshell in TrueNAS ist ausreichend für die simple Konfigurationen, daher bleibt SSH diesmal deaktiviert.

  • Jail starten: TrueNAS / Jails / unifi / Start
  • Jail Shell öffnen: TrueNAS / Jails / unifi / Shell

Paketequelle anpassen

Zuvor passen wir die Paketquellen auf die latest an, damit auch wirklich die neueste Pakete bezogen werden

Pakete installieren & Dienste aktivieren

Nun die Paketquelle mit pkg update aktualisieren und dann die benötigten Pakete mit pkg install -y unifi8 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://UNIFIIP:8443 oder http://UNIFIHOSTNAME: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.

Wiederherstellung

  • Jail erstellen
  • OPT: Datenverzeichnisse einbinden, sollte das data Verzeichnis ausserhalb liegen
    • z.B. /mnt/tank/jails_data/unifi/data nach /mnt/jails/iocage/jails/unifi/root/usr/local/share/java/unifi/data
  • Jail starten
  • Paketquelle anpassen
  • Unifi installieren pkg install -y unifi8
  • Unifi aktivieren und starten service unifi enable && service unifi start

Damit startet der Unifi Dienst und greift auf die bereits vorhandenee Konfiguration und Datenbank in /usr/local/share/java/unifi/data zu.
Ohne das externe Verzeichnis kann beim ersten Start eine zuvor gesicherte unifi.unf Datei wieder eingelesen werden. Das geht auch sehr gut.

Konsole

tank = Der Name des ZFS Pools, bitte anpassen

iocage create -b -n "unifi" -r 13.2-RELEASE vnet="on" bpf="on" dhcp="on"

# OPTIONAL
zfs create -p tank/jails_data/unifi/data
iocage exec -f unifi "install -d -g 975 -o 975 /usr/local/share/java/unifi/data"
iocage stop unifi
iocage fstab -a unifi /mnt/tank/jails_data/unifi/data /usr/local/share/java/unifi/data nullfs rw 0 0

iocage console -f unifi
mkdir -p /usr/local/etc/pkg/repos
sed -e 's|quarterly|latest|g' /etc/pkg/FreeBSD.conf > /usr/local/etc/pkg/repos/FreeBSD.conf
pkg install -y unifi8
service unifi enable
service unifi start
exit

Voilá