UniFi Network Controller unter Ubuntu

Sep 13, 2021 von Frank Stüber

Schlagwörter: Ubuntu Linux UniFi

Der UniFi Network Controller konfiguriert Geräte aus der UniFi-Produktfamile im Netzwerk. Dieser Blog-Artikel zeigt Euch, wie man den UniFi Network Controller unter Ubuntu Server 20.04 LTS installiert und mit Hilfe von nginx im Netzwerk verfügbar macht.

Der UniFi Network Controller

Ubiquiti ist ein amerikanischer Hersteller von Netzwerkkomponenten. Die WLAN-Produktfamilie (AccessPoints etc.) ist unter dem Namen UniFi zusammengefasst.

Zum Konfigurieren der UniFi-Produkte kommt eine Software namens UniFi Network Controller zum Einsatz. Diese webbasierte Java-Applikation kann kostenlos heruntergeladen und beispielsweise unter Windows, Linux oder macOS installiert werden.

Wir werden jetzt folgendes tun:

Die aktuelle Stable-Version des UniFi Network Controller unter Ubuntu Server 20.04 LTS mit all seinen Abhängigkeiten installieren.
Den Web-Server nginx installieren und so konfigurieren, dass er als Reverse-Proxy den UniFi Network Controller unter https://unifi.beispiel.de verfügbar macht.
Die Ubuntu-Firewall aktivieren und so konfigurieren, dass nur noch Aufrufe über unseren neuen Reverse-Proxy möglich sind.

UniFi Network Controller einrichten

Installieren

Wir beginnen zunächst damit, Abhängigkeiten zu installieren:

$ sudo apt update && sudo apt install ca-certificates apt-transport-https openjdk-8-jre-headless

Diese Befehlskette installiert:

Eine Liste von Zertifizierungsstellen (certification authority, CA) für die Authentizitätsüberprüfung von TLS-Verbindungen.
Unterstützung für apt-Repository-Zugriffe via HTTPS (apt-transport-https).
Die Open JDK Laufzeitumgebung in der Version 8 (neuere Versionen werden von UniFi noch nicht unterstützt).

Als nächstes wollen wir das apt-Repository von UniFi in unserem Ubuntu-Server registrieren:

$ echo 'deb https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

Anschließend wird der UniFi-Signaturschlüssel importiert. Dieser wird für die Überprüfung des Installationspakets aus dem soeben registrierten apt-Repository benötigt.

$ sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg

Ist es auch der richtige Signaturschlüssel?

$ sudo apt-key fingerprint 06E85760C0A52C50

Das Ergebnis sollte in etwa so aussehen:

pub   rsa2048 2011-02-01 [SC]
      4A22 8B2D 358A 5094 1782  85BE 06E8 5760 C0A5 2C50
uid           [ unknown] UniFi Developers <unifi-dev@ubnt.com>
sub   rsa2048 2011-02-01 [E]

So, jetzt sind die Vorbereitungen abgeschlossen. Wir können die eigentliche Installation von UniFi starten:

$ sudo apt update && sudo apt install unifi

Das dauert jetzt ein Weilchen. Aber am Ende sollte der UniFi Network Controller erfolgreich gestartet sein.

Testen

Zunächst überprüfen wir den Status des UniFi-Dienstes:

$ sudo systemctl status unifi

Die Antwort sollte folgende Info enthalten:

Starting unifi...
    * Starting Ubiquiti UniFi Controller unifi
    ...done.
Started unifi.

Der UniFi Network Controller ist eine Web-Anwendung mit eingebettetem Web-Server, die standardmäßig unter http://localhost:8080 und unter https://localhost:8443 zu erreichen ist.

Probieren wir es aus:

$ wget -S --spider localhost:8080

Es sollte eine Antwort wie diese erscheinen:

Spider mode enabled. Check if remote file exists.
--2021-09-02 12:22:39--  http://localhost:8080/
Resolving localhost (localhost)... ::1, 127.0.0.1
Connecting to localhost (localhost)|::1|:8080... connected.
HTTP request sent, awaiting response...
  HTTP/1.1 302
  Set-Cookie: unifises=TRZ1MEXrDvdnRAbqKAbVZeV3T5R6khS6; Path=/; Secure; HttpOnly
  Set-Cookie: csrf_token=ptcSrbmLrRT3KecTPFIq3sw8PSfpFSlN; Path=/; Secure
  Location: /setup/
  Transfer-Encoding: chunked
  Date: Thu, 02 Sep 2021 10:22:39 GMT
  Keep-Alive: timeout=5
  Connection: keep-alive
Location: /setup/ [following]
Spider mode enabled. Check if remote file exists.
--2021-09-02 12:22:39--  http://localhost:8080/setup/
Connecting to localhost (localhost)|::1|:8080... connected.
HTTP request sent, awaiting response...
  HTTP/1.1 200
  Set-Cookie: unifises=xjOE0xeiyYrSVJxphKR42gnLOKwgMRVW; Path=/; Secure; HttpOnly
  Set-Cookie: csrf_token=22qGm4MqmSPniqPLCF74hrHqfbzdmaG4; Path=/; Secure
  X-Frame-Options: SAMEORIGIN
  Accept-Ranges: bytes
  ETag: W/"478-1622117545000"
  Last-Modified: Thu, 27 May 2021 12:12:25 GMT
  Content-Type: text/html;charset=ISO-8859-1
  Content-Length: 478
  Date: Thu, 02 Sep 2021 10:22:39 GMT
  Keep-Alive: timeout=5
  Connection: keep-alive
Length: 478 [text/html]
Remote file exists and could contain further links,
but recursion is disabled -- not retrieving.

Für einen externen Test öffne die URL http://unifi.beispiel.de:8080 in Deinen Web-Browser. Das Ergebnis sollte (nach Bestätgung der Sicherheitsabfrage, aufgrund des unsicheren TLS-Zertifikats) wie folgt aussehen:

Du kannst jetzt beginnen, Deinen UniFi Controller einzurichten und mit Deiner Netzwerkumgebung zu verbinden.

Troubleshooting

Konfiguration anpassen

Die wenigen Einstellungsmöglichkeiten für den eingebetteten Web-Server des UniFi-Controller finden sich hier:

sudo nano /usr/lib/unifi/data/system.properties

Ressourcen-Limits umgehen

Sollte der UniFi-Controller nicht ordnungsgemäß starten, dann erhältst mit Abschluss der Installation vielleicht eine Meldung wie diese hier:

Job for unifi.service failed because a timeout was exceeded.
See "systemctl status unifi.service" and "journalctl -xe" for details.

Es bietet sich ein Blick in die Log-Datei an:

$ sudo nano /usr/lib/unifi/logs/server.log

Finden sich dort Einträge wie diese hier

std::exception::what(): Resource temporarily unavailable

dann hast Du sehr wahrscheinlich Probleme mit Ressourcen-Limits auf Deinem Ubuntu-System. Die Kennzahl hier ist die maximal erlaubte Anzahl von Prozessen (Option TasksMax) für eine Prozessgruppe wie Unifi. Den aktuellen Wert erhältst Du durch folgenden Aufruf:

$ systemctl show unifi.service | grep TasksMax

Unter Ubuntu beträgt dieser Wert standardmäßig 15% der Maximalanzahl aktiver Prozesse im System. Kostengünstige virtuelle Linux-Server in der Cloud haben oft einen sehr kleinen Wert (60 ist bisher der kleinste, der mir begegnet ist).

Du kannst den Wert erhöhen (z.B. auf 1024):

$ sudo systemctl set-property unifi.service TasksMax=1024

Oder Du kannst die Grenze ganz aufheben:

$ sudo systemctl set-property unifi.service TasksMax=infinity

Starte anschließend den UniFi-Dienst neu:

$ sudo systemctl restart unifi

UniFi-Dokumentation

Folgende Artikel aus dem Ubiquiti Support and Help Center sind interessant:

Reverse-Proxy mit nginx einrichten

Der UniFi-Controller ist direkt im Netzwerk erreichbar. Das ist nicht optimal, da wir es hier mit einem eingebetteten Web-Server zu tun haben, dessen Konfigurationsmöglichkeiten doch arg eingeschränkt sind.

Besser ist folgende Strategie:

Wir installieren einen Reverse-Proxy, der die Kommunikation mit der Außenwelt übernimmt. Ein Reverse-Proxy nimmt Anfragen aus dem Internet bzw. Netzwerk entgegen und leitet sie an den passenden internen Serverdienst weiter. Der Serverdienst selbst, in unerem Fall der UniFi Network Controller, muss somit nicht direkt im Internet erreichbar sein. Der Reverse-Proxy agiert als sein Stellvertreter und übernimmt die gesamte Komunikation mit externen Clients (z.B. einem Web-Browser).

Das hat folgende Vorteile:

Die Kommunikation nach außen kann mit einem dedizierten WebServer wie nginx oder Apache durchgeführt werden, der nach allen Regeln der Kunst konfiguriert und mittels https abgesichert werden kann.
Die lokale Kommunikation zwischen Reverse-Proxy und UniFi dagegen erfolgt lokal auf dem Server. Die Konfigurationsanforderungen an den UniFi-Web-Server bleiben somit minimal.

Als Reverse-Proxy nutzen wir nginx. Der nginx Web-Server ist ein Open Source-Projekt und wird besonders gern als Reverse Proxy eingesetzt.

Zunächst führen wir eine Installation von nginx durch, legen eine Standardwebseite für die Domäne unifi.beispiel.de unter /etc/nginx/conf.d/de.beispiel.unifi.conf an und sichern den Zugriff per Cerbot/HTTPS ab. Dieser Workflow ist ausführlich im Artikel HTTPS unter nginx/Ubuntu beschrieben.

Anschließend öffnen wir unsere soeben angelegte Konfigurationsdatei erneut:

$ sudo nano /etc/nginx/conf.d/de.beispiel.unifi.conf

Wir ersetzen den Inhalt wie folgt:

server {
   server_name  unifi.beispiel.de;

   # UniFi Websockets Support
   location /wss/ {
	   proxy_pass https://localhost:8442;
	   proxy_http_version 1.1;
	   proxy_set_header Host $host;
	   proxy_set_header Upgrade $http_upgrade;
	   proxy_set_header Connection "Upgrade";
   }

   # UniFi Reverse Proxy
   location / {
	   proxy_pass https://localhost:8442/;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
       proxy_buffering off;   
   }
   
   listen 443 ssl http2; # managed by Certbot
   ssl_certificate /etc/letsencrypt/live/unifi.beispiel.de/fullchain.pem; # managed by Certbot
   ssl_certificate_key /etc/letsencrypt/live/unifi.beispiel.de/privkey.pem; # managed by Certbot
   include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
   ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}
server {
   if ($host = unifi.beispiel.de) {
	   return 301 https://$host$request_uri;
   } # managed by Certbot

   listen       80;
   server_name  unifi.beispiel.de;
   return 404; # managed by Certbot
}

Speichere Deine Änderung und starte nginx neu:

$ sudo systemctl reload nginx

Was haben wir gemacht?

Wir haben den ersten Server-Block unter nginx so umkonfiguriert, dass er auf https://unifi.beispiel.de horcht und alle Anfragen lokal an https://localhost:8433 weiterleitet. Dies umfasst auch die Kommunikation via Web-Sockets. Mehr Infos zum Thema NGINX als WebSocket-Proxy findest Du in diesem Blog-Artikel auf der nginx-Webseite.

Firewall

Als letzte Maßnahme wollen wir die Ubuntu-Firewall konfigurieren, um die direkten Aufrufe http://unifi.beispiel.de:8080 und https://unifi.beispiel.de:8443 zu unterbinden.

Die Installation erfolgt wie folgt:

$ sudo apt install ufw

Standardmäßig ist die Firewall deaktiviert. Wir konfigurieren sie (beispielhaft) wie folgt und aktivieren sie anschließend.

$ sudo ufw default deny incoming
$ sudo ufw allow ssh
$ sudo ufw allow http
$ sudo ufw allow https
$ sudo ufw allow 3478/udp
$ sudo ufw allow 8080/tcp
$ sudo ufw allow 6789/tcp
$ sudo ufw enable

Was haben wir gemacht?

Wir haben zunächst alle einkommenden Anfragen geblockt. Anschließend haben wir die Protokolle ssh (Port 22), http (Port 80) und https (Port 443) wieder geöffnet. Die weiteren Ports ergeben sich aus der UniFi-Dokumentation und können zum Teil auch weggelassen werden. Zu guter Letzt haben wir die Firewall aktiviert.

Noch ein paar Tipps:

Status der Firewall abfragen:
```
$ sudo ufw status
```
Die Firewall wieder deaktivieren:
```
$ sudo ufw disable
```

Abschließende Diskussion

In der Regel ist der UniFi-Controller in einem lokalen Netzwerk installiert, nämlich dort, wo sich auch die WLAN-Geräte befinden.

Um den UniFi-Controller im Web verfügbar zu machen, muss im lokalen Netzwerk ein Gateway vorhanden sein. Dieses Gateway muss eine öffentliche IP-Adresse intern so auflösen, dass sie bei unserem Ubuntu Server ankommt. Ist dies nicht der Fall, können wir keine TLS-Zertifikate von Let’s Encrypt nutzen.

Alternativen in diesem Fall wären:

Nutzung eines selbstsignierten Zertifikats. Kann z.B. mittels OpenSSL ausgestellt werden.
Nutzung eines von einer eigenen privaten Zertifizierungsstelle ausgestellten TLS-Zertifikats. Dies setzt eine passende PKI (Public-Key-Infrastruktur) voraus.

Wir nutzen Cookies, um die Diskussionsplattform Disqus zu integrieren. Mit Klicken auf Kommentare anzeigen stimmen Sie dem zu und Disqus wird geladen.

Der UniFi Network Controller

UniFi Network Controller einrichten

Installieren

Testen

UniFi Controller Setup

Troubleshooting

Konfiguration anpassen

Ressourcen-Limits umgehen

UniFi-Dokumentation

Reverse-Proxy mit nginx einrichten

Firewall

Abschließende Diskussion