UniFi Controller Installation auf einer Synology NAS

Bedingt durch den Umzug in ein Eigenheim inkl. Netzwerkverkabelung und neuer LAN/WLAN Infrastruktur habe ich meine Netzwerk-Komponenten vom Hersteller Ubiquiti (UniFi) bezogen. Damit die Komponenten miteinander interagieren benötigt man einen UniFi Netzwerk-Controller, entweder als kleine „Appliance“, als Cloud Lösung (https://unifi.ui.com) oder als Software. Ich habe mit für die letzte Lösung entschieden, um den Controller On-Premise zu halten.

Basis für meine Installation in diesem Beitrag ist der UniFi Controller 6.0.43 und Synology DSM 6.2.3.

Docker Installation

Falls noch nicht geschehen, muss zuerst Docker auf der Synology installiert werden. Dazu öffnet man in DSM das Package Center und sucht nach Docker zur Installation. Nachdem die Installation beendet ist, lässt sich Docker direkt über das Package Center öffnen oder über das DSM Menü.

Package Center
UniFi Container Installation

In der Docker Konsole lade ich mir als erstes das UniFi Image herunter. Dazu wechsle ich in den Menüpunkt Registry und suche im Search Fenster nach „unifi“. Eines der Ergebnisse lautet jacobalberty/unifi. Dieses Image lade ich jetzt herunter.

Docker Registry

Ist der Download abgeschlossen, wechsle ich in den Menüpunkt Image und starte einen neuen Container mit Launch.

Docker Image

Nun öffnet sich das Konfigurationsfenster für den neuen Container. Hier gebe ich dem Container einen Namen und limitiere die Ressourcen-Nutzung (je nach Modell kann hier natürlich etwas mehr RAM zugewiesen werden). Für die weitere Konfiguration klicke ich auf den Button Advanced Settings.

Docker Image

Als erstes sorge ich im Reiter Advanced Settings dafür, dass der Container nach einem Neustart der Synology auch automatisch wieder mitgestartet wird.

Docker Image

Im Reiter Volume verbinde ich jetzt einen Ordner und mounte ihn in den Container als /unifi. In diesem Ordner werden persistente Container-Daten gespeichert, damit auch nach einem Versionsupdate (siehe später) die Konfiguration des Controllers erhalten bleibt.

Docker Image

Im Reiter Network wähle ich die Option Use the same network as Docker Host aus. Möchte man die Ports des UniFi Controllers auf alternative Ports ändern (z.B. die Web GUI), wählt man in diesem Fenster statt der Checkbox das bridge Netzwerk aus und konfiguriert das Mapping der Local Ports und der Container Ports für die UniFi Ports, die weiter unten im Beitrag genannt sind.

Docker Image

Jetzt wechsle ich noch auf den letzten Reiter Environment und ändere die 2 Parameter BIND_PRIV und RUNAS_UID0 von true auf false.

Docker Image

Danach ist die Container Konfiguration beendet und kann mit Apply abgeschlossen werden. Den Container starte ich automatisch, wenn der Wizard beendet ist.

Docker Image

Ist der Container fertig hochgefahren, lässt sich das Webinterface des Controllers erreichen über die URL https://<Synology-IP>:8443.

Sonstige Anpassungen

Ports

Falls auf der Disk Station die Firewall aktiv ist, müssen im aktiven Profil folgende Ports freigeschaltet werden:

  • TCP/8443: Web GUI
  • TCP/8080: Device/Controller Communication
  • TCP/8880: HTTP Portal Redirection
  • TCP/8843: HTTPS Portal Redirection
  • TCP/6789: UniFi Mobile Speed Test
  • UDP/3478: STUN (optional, für UniFi VoIP Telefone)
  • UDP/10001: Device Discovery
  • UDP/1900: Layer 2 Network Discovery
  • UDP/5514: Remote Syslog Capture (optional)

Zudem dürfen die Ports natürlich nicht anderweitig bereits in Verwendung sein (z.B. durch andere Synology Packages oder andere Docker Container). Prädestiniert für Konflikte sind besonders die Ports 8080 und 8443, die werden als alternative HTTP/HTTPS Ports auch gerne durch andere Produkte verwendet. Sollte der Container nicht starten oder unerwartet sofort wieder stoppen, ist dies das häufigste Problem.

Geräte-Registrierung

Im Normalfall läuft der Controller nach der Einrichtung zwar problemlos, man wird aber feststellen, dass sich keine Geräte am Controller melden. Grund hierfür ist, dass sich die Geräte werksseitig bei der URL http://unifi:8080/inform melden, die NAS aber in den seltensten Fällen den Hostnamen UNIFI hat.

Die am häufigsten gefundene Methode im Internet ist es, sich auf das jeweilige Gerät per SSH zu verbinden und die Registrierungs-URL wie folgt zu ändern:

set-inform http://<Synology-IP/-Hostname>:8080/inform

Funktioniert das: Yepp!
Ist das charmant: Nope!
Geht das besser: Klaro!

Stellt euch vor, ihr habt eine etwas größere UniFi Umgebung mit 100 oder mehr Geräten. Will man sich wirklich auf unzähligen Geräten händisch einloggen, um die Registrierungs-URL anzupassen? Eher nicht. Wer eine entsprechend große Anzahl an Geräten hat, hat sicher auch eine weitergehende IT-Infrastruktur in Betrieb – inkl. einem eigenen internen DNS-Server.

Dieser kann entsprechend genutzt werden, um den Hostnamen UNIFI im Netzwerk verfügbar zu machen. Hierzu gibt es 2 Optionen:

  • CNAME-Record UNIFI mit Alias auf den Hostname der Synology NAS
  • A-/AAA-Record UNIFI mit der IPv4-/IPv6-Adresse der Synology NAS

Ist der Hostname UNIFI im Netzwerk verfügbar und auflösbar klappt’s auch mit dem automatischen Deployment von UniFi Geräten ohne manuelle Anpassungen.

Versionsupdate

Da der UniFi Controller jetzt ein Docker Image ist, lässt sich kein Update direkt in der UniFi Web UI durchführen. Stattdessen muss der Container selbst getauscht werden. Das funktioniert ähnlich wie die Neuinstallation und ist recht einfach:

  • aktuelles (neues) Image für UniFi herunterladen
  • UniFi Controller Konfiguration über die Web GUI sichern und herunterladen (zur Sicherheit)
  • laufenden Container stoppen
  • Container auswählen und mit Action -> Clear (seit DSM 7: Reset) alle Daten löschen (die Konfiguration bleibt erhalten durch den gemounteten Ordner!)
  • Container wieder starten

Danach ist die UniFi Version des Containers aktualisiert.

Update 19.07.2021 – Geräteregistrierung

Nachdem einer meiner USW-Flex-Mini Switche den Geist aufgegeben, habe ich ein Austauschgerät bekommen und versucht es in meine Infrastruktur einzubinden. Was bisher mit dem DNS-Eintrag für den Controller geklappt hat, ging mit dem neuen Gerät ums Verrecken nicht. Habe alles ausprobiert, inkl. Firmware-Recovery – ohne Erfolg. Letzten Endes hat nur die Nutzung einer DHCP Adresszuweisung inkl. Option 43 funktioniert. Dazu habe ich in meinem DHCP Server (meine Fortigate Firewall) folgenden Eintrag für den DHCP-Scope gesetzt:

Code: 43
Typ: HEX
Value: 0104C0A80001

Wie setzt sich der Wert für Option 43 zusammen:

01 -> Vendor Code (01 für Ubiquiti)
04 -> Länge des Payloads (Single IP, daher: 4)
C0A80001 -> HEX-Code für die IP UniFi Controller IP (in diesem Beispiel 192.168.0.1)

Update 11.10.2021 – Geräteregistrierung (Teil 2)

Eventuell konnte das Problem der nicht mehr funktionierenden Registrierung der Geräte per DNS gelöst werden. Ich hatte im Vorfeld des Problems den Container umgestellt von host-Network auf ein bridge-Network. Das o.g. Austauschgerät habe ich erst nach dieser Umstellung versucht zu registrieren. Ich konnte das noch nicht verifizieren, habe aber meinen Container wieder auf host-Network umgestellt. Aktuell warte ich (seit 3 Monaten!!!) auf ein anderes Austauschgerät; sobald das da ist, probiere ich aus, ob das jetzt wieder ohne die DHCP Option 43 funktioniert. Falls von euch Lesern jemand die Möglichkeit hat, das Verhalten zu testen, ist Feedback jederzeit willkommen.

Update 28.01.2022 – Geräteregistrierung (Teil 3)

Inzwischen konnte ich durch ein Austauschgerät selbst testen, ob das Problem mit der Geräteregistrierung per DNS an den Netzwerkeinstellungen des Containers liegt und es scheint so zu sein. Nachdem ich ja wieder auf host-Network zurückgestellt habe, konnte das Gerät auch ohne die DHCP-Option wieder den Controller finden und ich konnte es adopten.


Quellen:
https://help.ui.com/
https://registry.hub.docker.com/r/jacobalberty/unifi/

32 Antworten

  1. Hans-Georg sagt:

    Ein super Tutorial und es funktioniert alles wie beschrieben, nur bin ich mir nicht sicher wie ich die Switche und Accesspoints auf den „neuen“ Controller bringe … was, wenn mir bei der Anwendung des Vorschlags mittels SSH ein Tippfehler unterläuft, finde ich dann meine Geräte nicht mehr, weder mit dem alten noch mit dem neuen Controller?
    Außerdem zeigt mir der neue Controller im Docker Container folgendes an: „Remote Access requires 64-bit Java Runtime Environment“, wie und wo genau muß ich Java installieren?
    Mein System ist ein MacBook mit MacOS 11.6.1

    • Hallo Hans-Georg
      Alternativ zur Änderung per SSH kannst du auch über den alten Controller die IP des neuen Controllers pushen. Da kannst du auf jeden Fall vor dem Speichern nochmal genau prüfen, ob du dich verschrieben hast ;-).
      Bzgl. Java kann ich dir keine Info geben, ich verwende kein MacOS.
      Gruß
      Andreas

  2. Arnold sagt:

    hab riesen Ärger nach IP Umstellung (neue Diskstation) mit einem switch. Der wird im controller jetzt immer als disconnected/adopting angezeigt. Auch resetten und neu adopten half nicht. Sah dann, dass die inform-adresse (ssh –> ‚info‘) weiterhin auf die alte IP zeigte… warum, keine Ahnung – aber auch nach reset und neu adopt — das finde ich schon mal ein starkes Stück von Unifi, dass der Reset das nichtmal behebt.

    set-inform http://192.168.1.XXX:8443/inform returniert zwar, dass es geht, tut es aber nicht. Ist der Port das Problem. Controller an alter IP via zweitem NIC realisiert erreichbar und schon geht’s, daher ist der port wohl nicht das Problem.

    bekomme es nicht hin die inform IP des Switches zu ändern, Ideen?

    • Hallo Arnold
      Ich würde dir empfehlen, statt die IPs des Controllers direkt zu ändern, mit einem „alten“ und einem „neuen“ Controller zu arbeiten. Also temporär auf irgendeinem Client den Controller installieren, IP der Diskstation ändern, IP des Clients auf die alte IP der Diskstation ändern, Backup wiederherstellen. Dadurch hast du 2 Controller mit alter und neuer IP. Danach testen, ob der Push der neuen IP über den Controller mit der alten IP funktioniert.
      Natürlich muss auch ggf. der „unifi“ DNS Eintrag geändert werden, falls du hierfür einen A-Record verwendest.
      Gruß
      Andreas

  3. Philip Etter sagt:

    Hallo Andreas

    Ich habe vor ca. 1.5 Jahren dank deiner tollen Anleitung den UniFi Controller auf meiner eher betagten Sysnology NAS installiert und zum Laufen gebracht. Kürzlich kam mir mal in den Sinn, dass es wohl angebracht ist den UniFi Controller zu aktualisieren. Hierzu habe ich deine Anleitung „Versionsupdate“ gelesen. Wie schon erwähnt, hast du eine super Anleitung gemacht, aber ich habe doch etwas Hemmungen das Versionsupdate durchzuführen vor allem weil ich im Prinzip ein Laie bin in solchen Dingen. Daher möchte ich dich zur Sicherheit an dieser Stelle fragen, ob ich dein Vorgehen zu „Versionsupdate“ richtig verstehe:

    1. Wie unter „UniFi Container Installation“ beschrieben nach dem aktuellsten UniFi Image suchen. Verstehe ich das richtig, dass das aktuellste Image nicht zwingend „jacobalberty/unifi“ heissen muss? Wenn ja, ist es auch für Laien wie mich ersichtlich welches das aktuellste Image ist?
    2. Back-up UniFi Controller via Web –> d.h. via „https://ui.com/“ das Back-up durchführen. Verstehe ich das richtig?
    3. Auf Docker Konsole in Register „Container“ den laufenden Container stoppen. Korrekt?
    4. Auf Docker Konsole in Register „Container“ den gestoppten Container auswählen und mit Action -> Clear (seit DSM 7: Reset) alle Daten löschen. Korrekt?
    5. Auf Docker Konsole in Register „Image“ die bei 1. heruntergeladene Imagedatei wählen und einen neuen Container mit „Lauch“ starten und Anleitung befolgen (ab Bild 4 gemäss deiner Anleitung)? Kann man den bestehenden Container Name für den neuen Container wiederverwenden

    Danke dir im voraus für deine Unterstützung

    • Hallo Philip
      Danke für deinen Kommentar.
      Deine Fragen vollständig und allgemein zu beantworten, würde den Rahmen sprengen.
      Daher versuche ich sie zu beantworten unter der Prämisse, dass du immmer den „latest“ Tag des Images „jacobalberty/unifi“ verwendest.
      1. Das Image heißt immer „jacobalberty/unifi:latest“. Welche Controller-Version gerade im „latest“-Image verarbeitet ist, findest du ggf. auf der Docker Seite von Jacob Alberty.
      2. Nein. „Backup über Web“ bedeutet über das Webinterface des Controllers, über Settings -> Backup.
      3. Ja.
      4. Ja.
      5. Nein. Über den Register „Image“ und „launch“ würde einen neuen Container erstellen. Stattdessen über den Register „Container“ den bestehenden Container starten. Durch das Clear/Reset in Punkt 4 werden jetzt die neuen Image-Daten beim Start geladen -> Update fertig!
      Gruß
      Andreas

      • Philip Etter sagt:

        Hallo Andreas

        Besten Dank für deine schnelle und verständliche Antwort. Ich denke, dass ich mit diesem „Rüstzeug“ das Versionsupdate hinkriege.

        Viele Grüsse
        Philip

  4. Peter1984 sagt:

    Hallo zusammen, ich habe das Thema mit den (bereits durch andere Container belegte) Ports so gelöst, dass ich eine virtuelle Synology-Instanz auf meiner 920+ installiert habe, und dort den Docker-Container installiert habe. Durch den A-Eintrag auf UNIFI in der Fritz!Box funktioniert alles wie gewollt. Traumhaft 🙂

  5. clfberlin sagt:

    Vielen Dank! Mein Cloud Key hatte sich nach einem Stromausfall verabschiedet und war nicht mehr auffindbar. Habe dann die Synology genommen und es funktioniert soweit prima. Vermutlich bleibe ich jetzt auch bei dieser Lösung

  6. Diego sagt:

    Hoi Andreas. Danke für deine Anleitung, funktioniert bestens, obwohl ich in Environment die Parameter nicht auf False gesetzt habe 😬. Ich brauche auch noch nicht die neuste Controller-Version. Es funktioniert soweit fast alles, auch mit einem VLAN. Was ich nicht hinkriege ist die Funktion der Gaststeuerung. Diese wird nicht geöffnet und laut anderen Mitteilungen braucht es ein Zugang zum Controller (bei mir 192.168.1.222) und im WLAN heisst es „keine Internetverbindung“. Wo müsste ich dies einstellen? Besten Dank für ein Tipp!!

    • Hallo Diego.
      Deine Frage kann ich dir leider nicht beantworten. Ich nutze als Gastzugang ein Captive Portal an meiner Fortigate Firewall, sodass ich das Gast-Feature des UniFi Controllers nicht brauche; das Gäste-VLAN ist bei mir daher aus UniFi Sicht ein „normales“ VLAN.
      Gruß
      Andreas

  7. Michael sagt:

    Hallo Andreas

    Vielen Dank für die tolle Anleitung!

    Betreffend Versionsupdate für UniFi Controller:
    Nach dem Container-Reset musste ich das Docker-Image via „Registry“ Tab neu herunterladen (das bestehende Image nicht löschen!).
    Sobald der Download des neuen Images abgeschlossen war, konnte ich den Container wieder starten und war ab dann mit der neusten Controller-Version unterwegs. 🙂

    mfg
    Michael

  8. Dominik sagt:

    Herzlichen Dank für die tolle Anleitung!

Schreibe einen Kommentar

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

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.